跳转到主内容

dialog

显示用于打开和保存文件、警报等的本机系统对话框。

Process: Main

下面是一个选择多个文件的对话框示例：

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

方法​

dialog 模块具有以下方法:

dialog.showOpenDialogSync([window, ]options)​

  • window BaseWindow (optional)
  • 选项 对象
    • title string (可选) - 对话框窗口的标题
    • defaultPath string (可选) - 对话框的默认展示路径
    • buttonLabel string (可选) - 「确认」按钮的自定义标签, 当为空时, 将使用默认标签。
    • filters FileFilter[] (optional)
    • properties string[] (可选) - 包含对话框相关属性。 支持以下属性值:
      • openFile - 允许选择文件
      • openDirectory - 允许选择文件夹
      • multiSelections-允许多选。
      • showHiddenFiles-显示对话框中的隐藏文件。
      • createDirectory macOS -允许你通过对话框的形式创建新的目录。
      • promptToCreate Windows-如果输入的文件路径在对话框中不存在, 则提示创建。 这并不是真的在路径上创建一个文件，而是允许返回一些不存在的地址交由应用程序去创建。
      • noResolveAliases macOS-禁用自动的别名路径(符号链接) 解析。 所选别名现在将会返回别名路径而非其目标路径。
      • treatPackageAsDirectory_ macOS _-将包 (如 .app 文件夹) 视为目录而不是文件。
      • dontAddToRecent Windows - 不要将正在打开的项目添加到最近的文档列表中。
    • message string (可选) _ macOS _-显示在输入框上方的消息。
    • securityScopedBookmarks boolean (可选) macOS MAS - 在打包提交到Mac App Store时创建 security scoped bookmarks

返回 string[] | undefined, 用户选择的文件路径，如果对话框被取消了 ，则返回undefined。

The window argument allows the dialog to attach itself to a parent window, making it modal.

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']
})

Note: On Linux defaultPath is not supported when using portal file chooser dialogs unless the portal backend is version 4 or higher. You can use --xdg-portal-required-version command-line switch to force gtk or kde dialogs.

dialog.showOpenDialog([window, ]options)​

  • window BaseWindow (optional)
  • 选项 对象
    • title string (可选) - 对话框窗口的标题
    • defaultPath string (可选) - 对话框的默认展示路径
    • buttonLabel string (可选) - 「确认」按钮的自定义标签, 当为空时, 将使用默认标签。
    • filters FileFilter[] (optional)
    • properties string[] (可选) - 包含对话框相关属性。 支持以下属性值:
      • openFile - 允许选择文件
      • openDirectory - 允许选择文件夹
      • multiSelections-允许多选。
      • showHiddenFiles-显示对话框中的隐藏文件。
      • createDirectory macOS -允许你通过对话框的形式创建新的目录。
      • promptToCreate Windows-如果输入的文件路径在对话框中不存在, 则提示创建。 这并不是真的在路径上创建一个文件，而是允许返回一些不存在的地址交由应用程序去创建。
      • noResolveAliases macOS-禁用自动的别名路径(符号链接) 解析。 所选别名现在将会返回别名路径而非其目标路径。
      • treatPackageAsDirectory_ macOS _-将包 (如 .app 文件夹) 视为目录而不是文件。
      • dontAddToRecent Windows - 不要将正在打开的项目添加到最近的文档列表中。
    • message string (可选) _ macOS _-显示在输入框上方的消息。
    • securityScopedBookmarks boolean (可选) macOS MAS - 在打包提交到Mac App Store时创建 security scoped bookmarks

返回 Promise<Object> - resolve包含以下内容的object：

  • canceled boolean - 对话框是否被取消。
  • filePaths string[] - 用户选择的文件路径的数组. 如果对话框被取消，这将是一个空的数组。
  • bookmarks string[] (optional) macOS MAS - 一个数组， filePaths 数组，base64编码字符串包含安全范围书签数据。 securityScopedBookmarks 必须启用才能捕获数据。 (返回值见 这里的表格。)

The window argument allows the dialog to attach itself to a parent window, making it modal.

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)
})

Note: On Linux defaultPath is not supported when using portal file chooser dialogs unless the portal backend is version 4 or higher. You can use --xdg-portal-required-version command-line switch to force gtk or kde dialogs.

dialog.showSaveDialogSync([window, ]options)​

  • window BaseWindow (optional)
  • 选项 对象
    • title string (可选) - 对话框标题。 无法在一些 Linux 桌面环境中显示。
    • defaultPath string (可选) - 默认情况下使用的绝对目录路径、绝对文件路径或文件名。
    • buttonLabel string (可选) - 「确认」按钮的自定义标签, 当为空时, 将使用默认标签。
    • filters FileFilter[] (optional)
    • message string (可选) _ macOS _-显示在对话框上的消息。
    • nameFieldLabel string (可选) _ macOS _ - 文件名输入框对应的自定义标签名。
    • showsTagField boolean (可选) _ macOS _-显示标记输入框, 默认为 true。
    • properties string[] (可选)
      • showHiddenFiles-显示对话框中的隐藏文件。
      • createDirectory macOS -允许你通过对话框的形式创建新的目录。
      • treatPackageAsDirectory_ macOS _-将包 (如 .app 文件夹) 视为目录而不是文件。
      • showOverwriteConfirmation Linux - 设置如果用户输入了已存在的文件名，是否会向用户显示确认对话框。
      • dontAddToRecent Windows - 不要将正在保存的项目添加到最近的文档列表中。
    • securityScopedBookmarks boolean (可选) macOS MAS - 在打包提交到Mac App Store时创建 security scoped bookmarks 当该选项被启用且文件尚不存在时，那么在选定的路径下将创建一个空文件。

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

The window argument allows the dialog to attach itself to a parent window, making it modal.

filters 可以指定可显示文件的数组类型，详见 dialog.showOpenDialog 事例

dialog.showSaveDialog([window, ]options)​

  • window BaseWindow (optional)
  • 选项 对象
    • title string (可选) - 对话框标题。 无法在一些 Linux 桌面环境中显示。
    • defaultPath string (可选) - 默认情况下使用的绝对目录路径、绝对文件路径或文件名。
    • buttonLabel string (可选) - 「确认」按钮的自定义标签, 当为空时, 将使用默认标签。
    • filters FileFilter[] (optional)
    • message string (可选) _ macOS _-显示在对话框上的消息。
    • nameFieldLabel string (可选) _ macOS _ - 文件名输入框对应的自定义标签名。
    • showsTagField boolean (可选) macOS - 显示标签输入框，默认为 true。
    • properties string[] (可选)
      • showHiddenFiles-显示对话框中的隐藏文件。
      • createDirectory macOS -允许你通过对话框的形式创建新的目录。
      • treatPackageAsDirectory_ macOS _-将包 (如 .app 文件夹) 视为目录而不是文件。
      • showOverwriteConfirmation Linux - 设置如果用户输入了已存在的文件名，是否会向用户显示确认对话框。
      • dontAddToRecent Windows - 不要将正在保存的项目添加到最近的文档列表中。
    • securityScopedBookmarks boolean (可选) macOS MAS - 在打包提交到Mac App Store时创建 security scoped bookmarks 当该选项被启用且文件尚不存在时，那么在选定的路径下将创建一个空文件。

返回 Promise<Object> - resolve包含以下内容的object：

  • canceled boolean - 对话框是否被取消。
  • filePath string - If the dialog is canceled, this will be an empty string.
  • bookmark string(optional) macOS MAS - 包含了安全作用域的书签数据 Base64 编码的字符串来保存文件。 securityScopedBookmarks 必须启用才有效。 (返回值见 这里的表格。)

The window argument allows the dialog to attach itself to a parent window, making it modal.

filters 可以指定可显示文件的数组类型，详见 dialog.showOpenDialog 事例

注意： 在macOS上，建议使用异步版本，以避免展开和折叠对话框时出现问题。

dialog.showMessageBoxSync([wndow, ]options)​

  • window BaseWindow (optional)
  • 选项 对象
    • message string - message box 的内容.
    • type string (可选) - 可以为 none, info, error, question 或者 warning. 在 Windows 上, question 与info显示相同的图标, 除非你使用了 icon 选项设置图标。 在 macOS 上, warning 和 error 显示相同的警告图标
    • buttons string[] (可选) - 按钮文本数组。 在 Windows上，一个空数组将导致按钮被标为“OK”。
    • defaultId Integer (可选) - 在 message box 对话框打开的时候，设置默认选中的按钮，值为在 buttons 数组中的索引.
    • title string (可选) - message box 的标题，一些平台不显示.
    • detail string (可选) - 额外信息.
    • icon (NativeImage | string) (optional)
    • textWidth Integer (可选) macOS - 自定义消息框中文本的宽度
    • cancelId Integer (可选) - 用于取消对话框的按钮的索引，例如 Esc 键. 默认情况下，它被分配给第一个按钮，文字为 “cancel” 或 “no”。 如果不存在这个标签的按钮，同时该选项又未设置，返回值为0。
    • noLink boolean (可选) - 在Windows上，应用将尝试找出哪个 buttons 是常用按钮(例如 "Cancel" 或 "Yes")，然后在对话框中以链接命令的方式展现其它的按钮。 这可以使对话框以现代Windows应用程序的风格显示。 如果你不喜欢这个行为, 你可以设置 noLink 为 true.
    • normalizeAccessKeys boolean (可选) -规范跨平台的键盘访问键。 默认值为 false. 用 & 连接和转换键盘访问键, 以便它们在每个平台上正常工作.& 字符会在macOS上被删除，在 Linux 上会被转换为 _，在 Windows 上保持不变。 例如 Vie&w 的按钮标签在 Linux 上会被转换为 Vie_w，在 macOS 转换为 View 并且可以被选择。而Windows和Linux上表示 Alt-W 。

返回 Integer - 点击的按钮的索引。

显示一个消息框，它将阻塞进程直到消息框关闭。 它返回点击的按钮的索引。

The window argument allows the dialog to attach itself to a parent window, making it modal. If window is not shown dialog will not be attached to it. 在这种情况想，它将作为一个独立的窗口显示。

dialog.showMessageBox([window, ]options)​

  • window BaseWindow (optional)
  • 选项 对象
    • message string - message box 的内容.
    • type string (可选) - 可以为 none, info, error, question 或者 warning. 在 Windows 上, question 与info显示相同的图标, 除非你使用了 icon 选项设置图标。 在 macOS 上, warning 和 error 显示相同的警告图标
    • buttons string[] (可选) - 按钮文本数组。 在 Windows上，一个空数组将导致按钮被标为“OK”。
    • defaultId Integer (可选) - 在 message box 对话框打开的时候，设置默认选中的按钮，值为在 buttons 数组中的索引.
    • signal AbortSignal (可选) - 通过 AbortSignal 信号实例可选地关闭消息框，消息框的行为就像用户点击取消一样。 在 macOS, signal 不适用于没有父窗口的消息框。因为平台限制，这些消息框同步运行
    • title string (可选) - message box 的标题，一些平台不显示.
    • detail string (可选) - 额外信息.
    • checkboxLabel string (可选) - 如果使用了，消息框将包含带有给定标签的复选框。
    • checkboxChecked boolean (可选) - checkbox 的初始值。 默认值为 false
    • icon (NativeImage | string) (optional)
    • textWidth Integer (可选) macOS - 自定义消息框中文本的宽度
    • cancelId Integer (可选) - 用于取消对话框的按钮的索引，例如 Esc 键. 默认情况下，它被分配给第一个按钮，文字为 “cancel” 或 “no”。 如果不存在这个标签的按钮，同时该选项又未设置，返回值为0。
    • noLink boolean (可选) - 在Windows上，应用将尝试找出哪个 buttons 是常用按钮(例如 "Cancel" 或 "Yes")，然后在对话框中以链接命令的方式展现其它的按钮。 这可以使对话框以现代Windows应用程序的风格显示。 如果你不喜欢这个行为, 你可以设置 noLink 为 true.
    • normalizeAccessKeys boolean (可选) -规范跨平台的键盘访问键。 默认值为 false. 用 & 连接和转换键盘访问键, 以便它们在每个平台上正常工作.& 字符会在macOS上被删除，在 Linux 上会被转换为 _，在 Windows 上保持不变。 例如 Vie&w 的按钮标签在 Linux 上会被转换为 Vie_w，在 macOS 转换为 View 并且可以被选择。而Windows和Linux上表示 Alt-W 。

返回 Promise<Object> - resolve包含以下属性的promise：

  • response number - 点击的按钮的索引。
  • checkboxChecked boolean - 如果设置了 checkboxLabel，返回复选框是否被选中的状态。 否则，返回 false。

显示一个消息框

The window argument allows the dialog to attach itself to a parent window, making it modal.

dialog.showErrorBox(title, content)​

  • title string - 显示在错误框中的标题.
  • content string - 显示在错误框中的文本内容.

显示一个显示错误消息的模态对话框。

这个API可以在 app 模块触发 ready 事件之前被安全地调用，它通常用在启动时报告错误。 在 Linux 上, ready 事件之前调用这个API, 消息将被发送到stderr, 并且不会出现GUI对话框。

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

  • window BaseWindow (optional)
  • 选项 对象
    • certificate Certificate - The certificate to trust/import.
    • message string - 要向用户显示的消息

返回 Promise<void> - 当显示信任证书对话框时resolve。

在macOS中, 将弹出一个用于展示消息与证书信息并向用户提供信任/导入证书的选项的模态对话框。 If you provide a window argument the dialog will be attached to the parent window, making it modal.

在Windows中, 受限于Win32 API，可选项变得更为有限:

  • message 参数无效，因为操作系统提供了自身的确认对话框。
  • window 参数被忽略，因此无法成为模态对话框。

Bookmarks 数组​

showOpenDialog and showSaveDialog resolve to an object with a bookmarks field. This field is an array of Base64 encoded strings that contain the security scoped bookmark data for the saved file. The securityScopedBookmarks option must be enabled for this to be present.

构建类型securityScopedBookmarks boolean返回类型返回值
macOS masTrue成功['LONGBOOKMARKSTRING']
macOS masTrueError[''] (空字符串数组)
macOS masFalseNA[] (空数组)
non masanyNA[] (空数组)

工作表​

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.

您可以调用 BaseWindow.getCurrentWindow().setSheetOffset(offset) 来更改附加工作表的窗口框架的偏移量。