Spec-Zone.ru › Electron

Диалог

Отображение системных диалогов для открытия и сохранения файлов, сообщений и т. д.

Процесс: Основной

Пример отображения диалога для выбора нескольких файлов:

const { dialog } = require('electron')
console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))

Методы​

В модуле dialog есть следующие методы:

dialog.showOpenDialogSync([browserWindow, ]options)​

  • browserWindow Окно браузера (необязательно)
  • options Объект
    • title строка (необязательно)
    • defaultPath строка (необязательно)
    • buttonLabel строка (необязательно) — Пользовательская надпись для кнопки подтверждения. Если поле пустое, используется значение по умолчанию.
    • filters ФильтрФайлов[] (необязательно)
    • properties массив строк (необязательно) — Содержит функции, которые должен использовать диалог. Поддерживаются следующие значения:
      • openFile — Разрешить выбор файлов.
      • openDirectory — Разрешить выбор папок.
      • multiSelections — Разрешить выбор нескольких путей.
      • showHiddenFiles — Показывать скрытые файлы в диалоге.
      • createDirectory macOS — Разрешить создание новых папок из диалога.
      • promptToCreate Windows — Запрашивать создание, если введённый в диалоге путь к файлу не существует. Файл фактически не создаётся по указанному пути, но позволяет возвращать несуществующие пути, которые должны быть созданы приложением.
      • noResolveAliases macOS — Отключить автоматическое разрешение пути псевдонима (символической ссылки). Выбранные псевдонимы теперь будут возвращать путь псевдонима, а не путь к целевому объекту.
      • treatPackageAsDirectory macOS — Обрабатывать пакеты, такие как .app папки, как папки, а не как файлы.
      • dontAddToRecent Windows — Не добавлять открываемый элемент в список последних документов.
    • message строка (необязательно) macOS — Сообщение, отображаемое над полями ввода.
    • securityScopedBookmarks логическое значение (необязательно) macOS mas — Создавать маркеры безопасности при упаковке для Mac App Store.

Возвращает string[] | undefined, пути к файлам, выбранные пользователем; если диалог отменён, возвращает undefined.

Аргумент browserWindow позволяет диалогу привязаться к родительскому окну, сделав его модальным.

filters определяет массив типов файлов, которые могут быть отображены или выбраны, когда вы хотите ограничить пользователя определённым типом. Например:

{
  filters: [
    { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Custom File Type', extensions: ['as'] },
    { name: 'All Files', extensions: ['*'] }
  ]
}

Массив extensions должен содержать расширения без диких символов или точек (например, 'png' хорошо, но '.png' и '*.png' плохо). Чтобы отобразить все файлы, используйте дикий символ '*' (другие дикие символы не поддерживаются).

Примечание: в Windows и Linux диалог открытия не может быть одновременно селектором файла и селектором папки, поэтому, если вы зададите properties в ['openFile', 'openDirectory'] на этих платформах, будет показан селектор папок.

dialog.showOpenDialogSync(mainWindow, {
  properties: ['openFile', 'openDirectory']
})

dialog.showOpenDialog([browserWindow, ]options)​

  • browserWindow Окно браузера (необязательно)
  • options Объект
    • title строка (необязательно)
    • defaultPath строка (необязательно)
    • buttonLabel строка (необязательно) — Пользовательская надпись для кнопки подтверждения. Если поле пустое, используется значение по умолчанию.
    • filters ФильтрФайлов[] (необязательно)
    • properties массив строк (необязательно) — Содержит функции, которые должен использовать диалог. Поддерживаются следующие значения:
      • openFile — Разрешить выбор файлов.
      • openDirectory — Разрешить выбор папок.
      • multiSelections — Разрешить выбор нескольких путей.
      • showHiddenFiles — Показывать скрытые файлы в диалоге.
      • createDirectory macOS — Разрешить создание новых папок из диалога.
      • promptToCreate Windows — Запрашивать создание, если введённый в диалоге путь к файлу не существует. Файл фактически не создаётся по указанному пути, но позволяет возвращать несуществующие пути, которые должны быть созданы приложением.
      • noResolveAliases macOS — Отключить автоматическое разрешение пути псевдонима (символической ссылки). Выбранные псевдонимы теперь будут возвращать путь псевдонима, а не путь к целевому объекту.
      • treatPackageAsDirectory macOS — Обрабатывать пакеты, такие как .app папки, как папки, а не как файлы.
      • dontAddToRecent Windows — Не добавлять открываемый элемент в список последних документов.
    • message строка (необязательно) macOS — Сообщение, отображаемое над полями ввода.
    • securityScopedBookmarks логическое значение (необязательно) macOS mas — Создавать маркеры безопасности при упаковке для Mac App Store.

Возвращает Promise<Object> — Разрешает объект, содержащий следующее:

  • canceled логическое значение — отменён ли диалог.
  • filePaths массив строк — массив путей к файлам, выбранных пользователем. Если диалог отменён, массив пуст.
  • bookmarks массив строк (необязательно) macOS mas — Массив, соответствующий массиву filePaths базовых 64-битных закодированных строк, содержащий данные маркеров безопасности. securityScopedBookmarks должен быть включен, чтобы он заполнялся. (Для значений возврата см. таблицу здесь.)

Аргумент browserWindow позволяет диалогу привязаться к родительскому окну, сделав его модальным.

filters определяет массив типов файлов, которые могут быть отображены или выбраны, когда вы хотите ограничить пользователя определённым типом. Например:

{
  filters: [
    { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Custom File Type', extensions: ['as'] },
    { name: 'All Files', extensions: ['*'] }
  ]
}

Массив extensions должен содержать расширения без диких символов или точек (например, 'png' хорошо, но '.png' и '*.png' плохо). Чтобы отобразить все файлы, используйте дикий символ '*' (другие дикие символы не поддерживаются).

Примечание: в Windows и Linux диалог открытия не может быть одновременно селектором файла и селектором папки, поэтому, если вы зададите properties в ['openFile', 'openDirectory'] на этих платформах, будет показан селектор папок.

dialog.showOpenDialog(mainWindow, {
  properties: ['openFile', 'openDirectory']
}).then(result => {
  console.log(result.canceled)
  console.log(result.filePaths)
}).catch(err => {
  console.log(err)
})

dialog.showSaveDialogSync([browserWindow, ]options)​

  • browserWindow BrowserWindow (необязательно)
  • options Объект
    • title строка (необязательно) — Заголовок диалогового окна. Не может быть отображен на некоторых Linux настольных средах.
    • defaultPath строка (необязательно) — Абсолютный путь к каталогу, абсолютный путь к файлу или имя файла по умолчанию.
    • buttonLabel строка (необязательно) — Настраиваемая подпись для кнопки подтверждения. Если пусто, используется значение по умолчанию.
    • filters FileFilter[] (необязательно)
    • message строка (необязательно) macOS — Сообщение, отображаемое над полями ввода.
    • nameFieldLabel строка (необязательно) macOS — Настраиваемая подпись для текста, отображаемого перед полем ввода имени файла.
    • showsTagField логическое значение (необязательно) macOS — Показывать поле ввода тегов, по умолчанию true.
    • properties массив строк (необязательно)
      • showHiddenFiles — Показывать скрытые файлы в диалоговом окне.
      • createDirectory macOS — Разрешить создание новых каталогов в диалоговом окне.
      • treatPackageAsDirectory macOS — Рассматривать пакеты, такие как папки .app, как каталоги, а не файлы.
      • showOverwriteConfirmation Linux — Указывает, будет ли отображаться диалоговое окно подтверждения, если пользователь введет имя файла, которое уже существует.
      • dontAddToRecent Windows — Не добавлять сохраняемый элемент в список последних документов.
    • securityScopedBookmarks логическое значение (необязательно) macOS mas — Создать маркер с ограниченным доступом при упаковке для Mac App Store. Если этот параметр включен и файл еще не существует, в выбранном пути будет создан пустой файл.

Возвращает string | undefined, путь к файлу, выбранному пользователем; если диалог отменён, возвращает undefined.

Аргумент browserWindow позволяет диалоговому окну прикрепляться к родительскому окну, делая его модальным.

Аргумент filters задаёт массив типов файлов, которые могут быть отображены. См. dialog.showOpenDialog для примера.

dialog.showSaveDialog([browserWindow, ]options)​

  • browserWindow BrowserWindow (необязательно)
  • options Объект
    • title строка (необязательно) — Заголовок диалогового окна. Не может быть отображен на некоторых Linux настольных средах.
    • defaultPath строка (необязательно) — Абсолютный путь к каталогу, абсолютный путь к файлу или имя файла по умолчанию.
    • buttonLabel строка (необязательно) — Настраиваемая подпись для кнопки подтверждения. Если пусто, используется значение по умолчанию.
    • filters FileFilter[] (необязательно)
    • message строка (необязательно) macOS — Сообщение, отображаемое над полями ввода.
    • nameFieldLabel строка (необязательно) macOS — Настраиваемая подпись для текста, отображаемого перед полем ввода имени файла.
    • showsTagField логическое значение (необязательно) macOS — Показывать поле ввода тегов, по умолчанию true.
    • properties массив строк (необязательно)
      • showHiddenFiles — Показывать скрытые файлы в диалоговом окне.
      • createDirectory macOS — Разрешить создание новых каталогов в диалоговом окне.
      • treatPackageAsDirectory macOS — Рассматривать пакеты, такие как папки .app, как каталоги, а не файлы.
      • showOverwriteConfirmation Linux — Указывает, будет ли отображаться диалоговое окно подтверждения, если пользователь введет имя файла, которое уже существует.
      • dontAddToRecent Windows — Не добавлять сохраняемый элемент в список последних документов.
    • securityScopedBookmarks логическое значение (необязательно) macOS mas — Создать маркер с ограниченным доступом при упаковке для Mac App Store. Если этот параметр включен и файл еще не существует, в выбранном пути будет создан пустой файл.

Возвращает Promise<Object> — разрешение с объектом, содержащим следующее:

  • canceled логическое значение — отменено ли диалоговое окно.
  • filePath строка (необязательно) — Если диалог отменён, это будет undefined.
  • bookmark строка (необязательно) macOS mas — строка Base64, содержащая данные маркера с ограниченным доступом для сохранённого файла. securityScopedBookmarks должен быть включён, чтобы это значение было доступно. (Для значений возврата см. таблицу здесь.)

Аргумент browserWindow позволяет диалоговому окну прикрепляться к родительскому окну, делая его модальным.

Аргумент filters задаёт массив типов файлов, которые могут быть отображены. См. dialog.showOpenDialog для примера.

Примечание: На macOS рекомендуется использовать асинхронную версию для предотвращения проблем при раскрытии и сворачивании диалогового окна.

dialog.showMessageBoxSync([browserWindow, ]options)​

  • browserWindow BrowserWindow (необязательно)
  • options Объект
    • message строка — Содержимое окна сообщения.
    • type строка (необязательно) — Может быть "none", "info", "error", "question" или "warning". В Windows "question" отображает тот же значок, что и "info", если не задан значок с помощью опции "icon". В macOS "warning" и "error" отображают один и тот же значок предупреждения.
    • buttons массив строк (необязательно) — Массив текстов для кнопок. В Windows пустой массив приведёт к появлению одной кнопки с надписью «ОК».
    • defaultId целое число (необязательно) — Индекс кнопки в массиве кнопок, которая будет выбрана по умолчанию при открытии окна сообщения.
    • title строка (необязательно) — Заголовок окна сообщения. На некоторых платформах он не отображается.
    • detail строка (необязательно) — Дополнительная информация сообщения.
    • icon (NativeImage | строка) (необязательно)
    • textWidth целое число (необязательно) macOS — Пользовательская ширина текста в окне сообщения.
    • cancelId целое число (необязательно) — Индекс кнопки для отмены диалогового окна, через ключ Esc. По умолчанию этому значению соответствует первая кнопка с надписью «отмена» или «нет». Если таких кнопок нет и этот параметр не задан, используется 0 в качестве значения возврата.
    • noLink логическое значение (необязательно) — В Windows Electron попытается определить, какие из buttons являются общими кнопками (например, «Отмена» или «Да»), и отобразит остальные как ссылки команд в диалоговом окне. Это может сделать диалоговое окно похожим по стилю на современные приложения Windows. Если вам не нравится такое поведение, вы можете установить noLink в true.
    • normalizeAccessKeys логическое значение (необязательно) — Нормализовать клавиши доступа на клавиатуре по разным платформам. По умолчанию false. Включение этого предполагает, что в метках кнопок используется &, для размещения клавиш быстрого доступа клавиатуры. Метки будут преобразованы для правильной работы на каждой платформе. Символы & удаляются на macOS, преобразуются в _ на Linux и остаются без изменений в Windows. Например, метка кнопки Vie&w будет преобразована в Vie_w на Linux и View на macOS и может быть выбрана с помощью Alt-W в Windows и Linux.

Возвращает Integer — индекс нажатой кнопки.

Отображает окно сообщения, блокируя процесс до закрытия окна. Возвращает индекс нажатой кнопки.

Аргумент browserWindow позволяет диалоговому окну прикрепляться к родительскому окну, делая его модальным. Если browserWindow не отображается, диалоговое окно не будет прикреплено к нему. В таком случае оно будет отображено как отдельное окно.

dialog.showMessageBox([browserWindow, ]options)​

  • browserWindow BrowserWindow (необязательно)
  • options Объект
    • message строка - Содержимое поля сообщения.
    • type строка (необязательно) - Может быть "none", "info", "error", "question" или "warning". В Windows "question" отображает тот же значок, что и "info", если не задан значок с помощью опции "icon". В macOS, как "warning", так и "error" отображают тот же значок предупреждения.
    • buttons массив строк (необязательно) - Массив текстов для кнопок. В Windows, пустой массив приведет к одной кнопке с подписью "ОК".
    • defaultId Целое число (необязательно) - Индекс кнопки в массиве кнопок, которая будет выбрана по умолчанию при открытии окна сообщения.
    • signal AbortSignal (необязательно) - Передайте экземпляр AbortSignal, чтобы, при необходимости, закрыть окно сообщения. Окно сообщения будет вести себя так, как если бы оно было отменено пользователем. В macOS, signal не работает с окнами сообщений, у которых нет родительского окна, так как эти окна сообщений выполняются синхронно из-за ограничений платформы.
    • title строка (необязательно) - Заголовок окна сообщения, некоторые платформы его не отображают.
    • detail строка (необязательно) - Дополнительная информация о сообщении.
    • checkboxLabel строка (необязательно) - Если указано, окно сообщения будет содержать флажок с заданной подписью.
    • checkboxChecked логическое значение (необязательно) - Начальное состояние флажка. false по умолчанию.
    • icon (NativeImage | строка) (необязательно)
    • textWidth Целое число (необязательно) macOS - Пользовательская ширина текста в окне сообщения.
    • cancelId Целое число (необязательно) - Индекс кнопки, которая будет использована для отмены диалога, с помощью ключа Esc. По умолчанию это назначается первой кнопке с подписью "отмена" или "нет". Если таких кнопок нет, и эта опция не задана, 0 будет использоваться в качестве возвращаемого значения.
    • noLink логическое значение (необязательно) - В Windows Electron попытается определить, какие из buttons являются общими кнопками (например, "Отмена" или "Да"), и отобразить остальные как ссылки команд в диалоге. Это может сделать диалог похожим по стилю на современные приложения Windows. Если вам не нравится это поведение, вы можете установить noLink в true.
    • normalizeAccessKeys логическое значение (необязательно) - Нормализовать клавиши доступа с клавиатуры на разных платформах. По умолчанию false. Включение этой опции предполагает, что & используется в подписях кнопок для размещения клавиш быстрого доступа с клавиатуры, и подписи будут преобразованы, чтобы правильно работать на каждой платформе. & символы удаляются в macOS, преобразуются в _ в Linux и остаются неизменными в Windows. Например, подпись кнопки Vie&w будет преобразована в Vie_w в Linux и View в macOS и может быть выбрана с помощью Alt-W в Windows и Linux.

Возвращает Promise<Object> - разрешает обещание, содержащее следующие свойства:

  • response число - Индекс нажатой кнопки.
  • checkboxChecked логическое значение - Состояние флажка, если checkboxLabel было установлено. В противном случае false.

Отображает окно сообщения.

Аргумент browserWindow позволяет диалогу привязаться к родительскому окну, делая его модальным.

dialog.showErrorBox(title, content)​

  • title строка - Заголовок, который нужно отобразить в окне ошибки.
  • content строка - Текст, который нужно отобразить в окне ошибки.

Отображает модальный диалог, показывающий сообщение об ошибке.

Этот API можно безопасно вызывать до события ready модуля app, обычно он используется для сообщения об ошибках на ранней стадии запуска. Если вызывать его до события приложения ready в Linux, сообщение будет выведено в stderr, и диалог GUI не появится.

dialog.showCertificateTrustDialog([browserWindow, ]options) macOS Windows​

  • browserWindow BrowserWindow (необязательно)
  • options Объект
    • certificate Сертификат - Сертификат, которому нужно доверять/импортировать.
    • message строка - Сообщение для отображения пользователю.

Возвращает Promise<void> - разрешается, когда диалог подтверждения доверия сертификата показан.

В macOS это отображает модальный диалог, который отображает информацию о сообщении и сертификате, и предоставляет пользователю возможность довериться/импортировать сертификат. Если вы предоставите аргумент browserWindow, диалог будет прикреплен к родительскому окну, делая его модальным.

В Windows опции ограничены из-за используемых API Win32:

  • Аргумент message не используется, так как операционная система предоставляет свой диалог подтверждения.
  • Аргумент browserWindow игнорируется, так как сделать этот диалог подтверждения модальным невозможно.

Массив закладок​

showOpenDialog, showOpenDialogSync, showSaveDialog, и showSaveDialogSync вернут массив bookmarks.

Тип сборки securityScopedBookmarks boolean Тип возвращаемого значения Возвращаемое значение
macOS mas True Успех ['LONGBOOKMARKSTRING']
macOS mas True Ошибка [''] (массив пустых строк)
macOS mas False НЕ применимо [] (пустой массив)
не mas любое НЕ применимо [] (пустой массив)

Листы​

В macOS диалоги представлены в виде листов, прикрепленных к окну, если вы предоставите ссылку на BrowserWindow в параметре browserWindow, или модальные, если окно не предоставлено.

Вы можете вызвать BrowserWindow.getCurrentWindow().setSheetOffset(offset) для изменения смещения от рамки окна, где прикреплены листы.

© GitHub Inc.
Licensed under the MIT license.
https://www.electronjs.org/docs/latest/api/dialog

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API