dialog

Показывает стандартные диалоги для открытия и сохранения файлов, предупреждения и т.п.

Process: Main

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

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

Методы

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

dialog.showOpenDialogSync([window, ]options)

• window BaseWindow (optional)
• options Object
  • title string (опционально)
  • defaultPath string (опционально)
  • buttonLabel string (опционально) - Пользовательский текст кнопки подтверждения. Если оставить пустым будет использован стандартный текст.
  • filters FileFilter[] (optional)
  • properties string[] (optional) - Contains which features the dialog should use. The following values are supported:
    • openFile - Позволяет выбирать файлы.
    • openDirectory - Позволяет выбирать папки.
    • multiSelections - Позволяет выбрать несколько объектов.
    • showHiddenFiles - Отображает в диалоге скрытые файлы.
    • createDirectory macOS - Позволяет создавать новые директории из диалога.
    • promptToCreate Windows - Запрашивает подтверждение на создание недостающих папок по выбранному пути, если они не существуют. На самом деле, эта функция не создаёт их. Она всего лишь позволяет возвращать несуществующие пути из диалогового окна, которые должны после этого быть созданы приложением.
    • noResolveAliases macOS - Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.
    • treatPackageAsDirectory macOS - Считает пакеты, такие как папки .app, за папки, а не файлы.
    • dontAddToRecent Windows - Do not add the item being opened to the recent documents list.
  • message string (опционально) macOS - Сообщение, которое будет отображено над полями ввода.
  • securityScopedBookmarks boolean (опционально) macOS MAS - Создает закладки с областью безопасности, при сборке пакета для Mac App Store.

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

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

The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Например:

{
  filters: [
    { name: 'Изображения', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Видео', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Свой тип файлов', extensions: ['as'] },
    { name: 'Все файлы', extensions: ['*'] }
  ]
}

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

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

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

dialog.showOpenDialog([window, ]options)

• window BaseWindow (optional)
• options Object
  • title string (опционально)
  • defaultPath string (опционально)
  • buttonLabel string (опционально) - Пользовательский текст кнопки подтверждения. Если оставить пустым будет использован стандартный текст.
  • filters FileFilter[] (optional)
  • properties string[] (optional) - Contains which features the dialog should use. The following values are supported:
    • openFile - Позволяет выбирать файлы.
    • openDirectory - Позволяет выбирать папки.
    • multiSelections - Позволяет выбрать несколько объектов.
    • showHiddenFiles - Отображает в диалоге скрытые файлы.
    • createDirectory macOS - Позволяет создавать новые директории из диалога.
    • promptToCreate Windows - Запрашивает подтверждение на создание недостающих папок по выбранному пути, если они не существуют. На самом деле, эта функция не создаёт их. Она всего лишь позволяет возвращать несуществующие пути из диалогового окна, которые должны после этого быть созданы приложением.
    • noResolveAliases macOS - Disable the automatic alias (symlink) path resolution. Selected aliases will now return the alias path instead of their target path.
    • treatPackageAsDirectory macOS - Считает пакеты, такие как папки .app, за папки, а не файлы.
    • dontAddToRecent Windows - Do not add the item being opened to the recent documents list.
  • message string (опционально) macOS - Сообщение, которое будет отображено над полями ввода.
  • securityScopedBookmarks boolean (опционально) macOS MAS - Создает закладки с областью безопасности, при сборке пакета для Mac App Store.

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

• canceled boolean - независимо от того, был ли диалог отменен.
• filePaths string[] - Массив файлов, которые выбрал пользователь. If the dialog is cancelled this will be an empty array.
• bookmarks string[] (optional) macOS MAS - An array matching the filePaths array of base64 encoded strings which contains security scoped bookmark data. Для его использования, securityScopedBookmarks должны быть активированы. (For return values, see table here.)

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

The filters specifies an array of file types that can be displayed or selected when you want to limit the user to a specific type. Например:

{
  filters: [
    { name: 'Изображения', extensions: ['jpg', 'png', 'gif'] },
    { name: 'Видео', extensions: ['mkv', 'avi', 'mp4'] },
    { name: 'Свой тип файлов', extensions: ['as'] },
    { name: 'Все файлы', extensions: ['*'] }
  ]
}

Массив extentions должен содержать расширения файлов без шаблонов поиска и точек (например, 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([window, ]options)

• window BaseWindow (optional)
• options Object
  • title string (optional) - The dialog title. Cannot be displayed on some Linux desktop environments.
  • defaultPath string (опционально) - Абсолютный путь к директории, файлу или имя файла выбранного по умолчанию.
  • buttonLabel string (опционально) - Пользовательский текст кнопки подтверждения. Если оставить пустым будет использован стандартный текст.
  • filters FileFilter[] (optional)
  • message string (опционально) macOS - Сообщение, которое будет показано над полями ввода.
  • nameFieldLabel string (опционально) macOS - Специальная метка для текста, отображаемая перед текстовым полем с именем файла.
  • showsTagField boolean (опционально) macOS - Показать поле ввода тегов, по умолчанию true.
  • properties string[] (optional)
    • showHiddenFiles - Отображает в диалоге скрытые файлы.
    • createDirectory macOS - Позволяет создавать новые директории из диалога.
    • treatPackageAsDirectory macOS - Считает пакеты, такие как папки .app, за папки, а не файлы.
    • showOverwriteConfirmation Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.
    • dontAddToRecent Windows - Do not add the item being saved to the recent documents list.
  • securityScopedBookmarks boolean (опционально) maxOS MAS - Создавать закладки с областью безопасности при сборке для Mac App Store. Если эта опция включена и выбранного файла не существует, то пустой файл будет создан по выбранному пути.

Returns string, the path of the file chosen by the user; if the dialog is cancelled it returns an empty string.

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

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

dialog.showSaveDialog([window, ]options)

• window BaseWindow (optional)
• options Object
  • title string (optional) - The dialog title. Cannot be displayed on some Linux desktop environments.
  • defaultPath string (опционально) - Абсолютный путь к директории, файлу или имя файла выбранного по умолчанию.
  • buttonLabel string (опционально) - Пользовательский текст кнопки подтверждения. Если оставить пустым будет использован стандартный текст.
  • filters FileFilter[] (optional)
  • message string (опционально) macOS - Сообщение, которое будет показано над полями ввода.
  • nameFieldLabel string (опционально) macOS - Специальная метка для текста, отображаемая перед текстовым полем с именем файла.
  • showsTagField boolean (optional) macOS - Show the tags input box, defaults to true.
  • properties string[] (optional)
    • showHiddenFiles - Отображает в диалоге скрытые файлы.
    • createDirectory macOS - Позволяет создавать новые директории из диалога.
    • treatPackageAsDirectory macOS - Считает пакеты, такие как папки .app, за папки, а не файлы.
    • showOverwriteConfirmation Linux - Sets whether the user will be presented a confirmation dialog if the user types a file name that already exists.
    • dontAddToRecent Windows - Do not add the item being saved to the recent documents list.
  • securityScopedBookmarks boolean (опционально) maxOS MAS - Создавать закладки с областью безопасности при сборке для Mac App Store. Если эта опция включена и выбранного файла не существует, то пустой файл будет создан по выбранному пути.

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

• canceled boolean - независимо от того, был ли диалог отменен.
• filePath string - If the dialog is canceled, this will be an empty string.
• bookmark string (необязательно) macOS MAS - Строка в кодировке base64, содержащая зкладку с областью безопасности сохранённого файла. securityScopedBookmarks должны быть активированы для её использования. (For return values, see table here.)

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

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

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

dialog.showMessageBoxSync([wndow, ]options)

• window BaseWindow (optional)
• options Object
  • message string - содержимое сообщения.
  • type string (опционально) - Может быть none, info, error, question или warning. В Windows, question отображает ту же иконку, что и info, если вы не установили иконку, используя опцию icon. На macOS и warning и error отображают ту же иконку предупреждения (warning).
  • buttons string[] (optional) - Array of texts for buttons. On Windows, an empty array will result in one button labeled "OK".
  • defaultId Integer (опционально) - Индекс кнопки в массиве кнопок, который будет выбран по умолчанию при открытии окна сообщения.
  • title string (optional) - Title of the message box, some platforms will not show it.
  • detail string (опционально) - Дополнительные сведения о сообщении.
  • icon (NativeImage | string) (optional)
  • textWidth Integer (optional) macOS - Custom width of the text in the message box.
  • cancelId Integer (опционально) - Индекс кнопки, которая будет использоваться для отмены диалога, через клавишу Esc. По умолчанию это назначается первой кнопке с меткой "Отмена" или "Нет". Если этот параметр не установлен и нет таких отмеченных кнопок, как возвращаемое значение будет использоваться 0.
  • noLink boolean (опционально) - В Windows Electron попытается выяснить, какие из buttons являются общими кнопками (например, «Отмена» или «Да»), и отобразить остальные как ссылки команд в диалоговом окне. Это может сделать диалог в стиле современных приложений Windows. Если вам не нравится такое поведение, вы можете установить noLink на true.
  • normalizeAccessKeys boolean (опционально) - Нормализация клавиш доступа к клавиатуре на разных платформах. По умолчанию - false. Включение этого предполагает, что & используется в метках кнопок для размещения клавиши быстрого доступа, и метки будут преобразованы, чтобы они правильно работали на каждой платформе, символы & удаляются в macOS, преобразуются в _ в Linux и остаются нетронутыми в Windows. Например, метка кнопки Vie&w будет преобразована в Vie_w в Linux и View в macOS и может быть выбрана с помощью Alt-W в Windows и Linux.

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

Показывает окно сообщения, оно будет блокировать процесс, пока не будет закрыто окно сообщения. It returns the index of the clicked button.

Аргумент window позволяет диалоговому окну прикрепляться к родительскому, что делает его модальным. If window is not shown dialog will not be attached to it. В этом случае он будет отображаться как независимое окно.

dialog.showMessageBox([window, ]options)

• window BaseWindow (optional)
• options Object
  • message string - содержимое сообщения.
  • type string (опционально) - Может быть none, info, error, question или warning. В Windows, question отображает ту же иконку, что и info, если вы не установили иконку, используя опцию icon. На macOS и warning и error отображают ту же иконку предупреждения (warning).
  • buttons string[] (optional) - Array of texts for buttons. On Windows, an empty array will result in one button labeled "OK".
  • defaultId Integer (опционально) - Индекс кнопки в массиве кнопок, который будет выбран по умолчанию при открытии окна сообщения.
  • signal AbortSignal (optional) - Pass an instance of AbortSignal to optionally close the message box, the message box will behave as if it was cancelled by the user. On macOS, signal does not work with message boxes that do not have a parent window, since those message boxes run synchronously due to platform limitations.
  • title string (optional) - Title of the message box, some platforms will not show it.
  • detail string (опционально) - Дополнительные сведения о сообщении.
  • checkboxLabel string (опционально) - Если это предусмотрено, в окне сообщения будет установлен флажок с данной меткой.
  • checkboxChecked boolean (optional) - Initial checked state of the checkbox. По умолчанию false.
  • icon (NativeImage | string) (optional)
  • textWidth Integer (optional) macOS - Custom width of the text in the message box.
  • cancelId Integer (опционально) - Индекс кнопки, которая будет использоваться для отмены диалога, через клавишу Esc. По умолчанию это назначается первой кнопке с меткой "Отмена" или "Нет". Если этот параметр не установлен и нет таких отмеченных кнопок, как возвращаемое значение будет использоваться 0.
  • noLink boolean (опционально) - В Windows Electron попытается выяснить, какие из buttons являются общими кнопками (например, «Отмена» или «Да»), и отобразить остальные как ссылки команд в диалоговом окне. Это может сделать диалог в стиле современных приложений Windows. Если вам не нравится такое поведение, вы можете установить noLink на true.
  • normalizeAccessKeys boolean (опционально) - Нормализация клавиш доступа к клавиатуре на разных платформах. По умолчанию - false. Включение этого предполагает, что & используется в метках кнопок для размещения клавиши быстрого доступа, и метки будут преобразованы, чтобы они правильно работали на каждой платформе, символы & удаляются в macOS, преобразуются в _ в Linux и остаются нетронутыми в Windows. Например, метка кнопки Vie&w будет преобразована в Vie_w в Linux и View в macOS и может быть выбрана с помощью Alt-W в Windows и Linux.

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

• response number - The index of the clicked button.
• checkboxChecked boolean - The checked state of the checkbox if checkboxLabel was set. Otherwise false.

Shows a message box.

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

dialog.showErrorBox(title, content)

• title string - Заголовок для отображения в поле ошибки.
• title string - Текстовое содержимое для отображения в поле ошибки.

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

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

dialog.showCertificateTrustDialog([window, ]options) macOS Windows

• window BaseWindow (optional)
• options Object
  • certificate Certificate - The certificate to trust/import.
  • message string - Сообщение, отображаемое пользователю.

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

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

В Windows параметры более ограничены, благодаря используемым API Win32:

• Не используется аргумент message, так как ОС предоставляет свое собственное подтверждение диалогового окна.
• Экран window игнорируется, поскольку невозможно сделать это диалоговое окно подтверждения.

Bookmarks array

showOpenDialog, showOpenDialogSync, showSaveDialog, and showSaveDialogSync will return a bookmarks array.

Build Type	securityScopedBookmarks boolean	Return Type	Return Value
macOS mas	True	Success	['LONGBOOKMARKSTRING']
macOS mas	True	Error	[''] (array of empty string)
macOS mas	False	NA	[] (empty array)
non mas	any	NA	[] (empty array)

"Листы"

On macOS, dialogs are presented as sheets attached to a window if you provide a BaseWindow reference in the window parameter, or modals if no window is provided.

You can call BaseWindow.getCurrentWindow().setSheetOffset(offset) to change the offset from the window frame where sheets are attached.