跳到主要内容

dialog

显示用于打开和保存文件、提醒等的原生系统对话框。

进程: 主进程

显示用于选择多个文件的对话框示例

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

方法

`dialog` 模块有以下方法

dialog.showOpenDialogSync([window, ]options)

  • window BaseWindow (可选)
  • options 对象
    • title 字符串 (可选)
    • defaultPath 字符串 (可选)
    • buttonLabel 字符串 (可选) - 确认按钮的自定义标签,如果留空将使用默认标签。
    • filters FileFilter[] (可选)
    • 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`。

`window` 参数允许对话框附加到父窗口,使其成为模态对话框。

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

注意: 在 Linux 上,除非门户后端版本为 4 或更高版本,否则在使用门户文件选择器对话框时不支持 `defaultPath`。 您可以使用 `--xdg-portal-required-version` 命令行开关 来强制使用 gtk 或 kde 对话框。

dialog.showOpenDialog([window, ]options)

  • window BaseWindow (可选)
  • options 对象
    • title 字符串 (可选)
    • defaultPath 字符串 (可选)
    • buttonLabel 字符串 (可选) - 确认按钮的自定义标签,如果留空将使用默认标签。
    • filters FileFilter[] (可选)
    • 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` 数组匹配的 base64 编码字符串数组,其中包含安全作用域书签数据。 必须启用 `securityScopedBookmarks` 才能填充此项。 (有关返回值,请参阅此处的表格。)

`window` 参数允许对话框附加到父窗口,使其成为模态对话框。

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

注意: 在 Linux 上,除非门户后端版本为 4 或更高版本,否则在使用门户文件选择器对话框时不支持 `defaultPath`。 您可以使用 `--xdg-portal-required-version` 命令行开关 来强制使用 gtk 或 kde 对话框。

dialog.showSaveDialogSync([window, ]options)

  • window BaseWindow (可选)
  • 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`,用户选择的文件路径;如果对话框被取消,则返回空字符串。

`window` 参数允许对话框附加到父窗口,使其成为模态对话框。

`filters` 指定一个可以显示的文件类型数组,有关示例,请参见 `dialog.showOpenDialog`。

dialog.showSaveDialog([window, ]options)

  • window BaseWindow (可选)
  • 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 字符串 - 如果对话框被取消,这将是一个空字符串。
  • bookmark 字符串 (可选) macOS MAS - Base64 编码的字符串,其中包含已保存文件的安全作用域书签数据。 必须启用 `securityScopedBookmarks` 才能显示此项。 (有关返回值,请参阅此处的表格。)

`window` 参数允许对话框附加到父窗口,使其成为模态对话框。

`filters` 指定一个可以显示的文件类型数组,有关示例,请参见 `dialog.showOpenDialog`。

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

dialog.showMessageBoxSync([wndow, ]options)

  • window BaseWindow (可选)
  • options 对象
    • message 字符串 - 消息框的内容。
    • type 字符串 (可选) - 可以是 noneinfoerrorquestionwarning。 在 Windows 上,question 显示与 info 相同的图标,除非您使用 icon 选项设置图标。 在 macOS 上,warningerror 都显示相同的警告图标。
    • 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 在 Linux 上将转换为 Vie_w,在 macOS 上将转换为 View,并且可以通过 Windows 和 Linux 上的 Alt-W 选择。

返回 `Integer` - 单击按钮的索引。

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

`window` 参数允许对话框附加到父窗口,使其成为模态对话框。 如果未显示 `window`,则对话框将不会附加到父窗口。 在这种情况下,它将显示为独立窗口。

dialog.showMessageBox([window, ]options)

  • window BaseWindow (可选)
  • options 对象
    • message 字符串 - 消息框的内容。
    • type 字符串 (可选) - 可以是 noneinfoerrorquestionwarning。 在 Windows 上,question 显示与 info 相同的图标,除非您使用 icon 选项设置图标。 在 macOS 上,warningerror 都显示相同的警告图标。
    • 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 在 Linux 上将转换为 Vie_w,在 macOS 上将转换为 View,并且可以通过 Windows 和 Linux 上的 Alt-W 选择。

返回 `Promise<Object>` - 使用包含以下属性的 Promise 进行解析

  • response 数字 - 单击按钮的索引。
  • checkboxChecked 布尔值 - 如果设置了 checkboxLabel,则为复选框的选中状态。 否则为 false

显示一个消息框。

`window` 参数允许对话框附加到父窗口,使其成为模态对话框。

dialog.showErrorBox(title, content)

  • title 字符串 - 要在错误框中显示的标题。
  • content 字符串 - 要在错误框中显示的文本内容。

显示一个模态对话框,其中显示错误消息。

可以在 app 模块发出 ready 事件之前安全地调用此 API,它通常用于报告启动早期的错误。 如果在 Linux 上在 app ready 事件之前调用,则消息将发送到 stderr,并且不会出现 GUI 对话框。

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

  • window BaseWindow (可选)
  • options 对象
    • certificate Certificate - 要信任/导入的证书。
    • message 字符串 - 要向用户显示的消息。

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

在 macOS 上,这将显示一个模态对话框,其中显示消息和证书信息,并为用户提供信任/导入证书的选项。 如果您提供 window 参数,则对话框将附加到父窗口,使其成为模态对话框。

在 Windows 上,由于使用的 Win32 API,选项更加有限

  • 不使用 `message` 参数,因为操作系统提供了自己的确认对话框。
  • `window` 参数被忽略,因为无法使此确认对话框成为模态对话框。

书签数组

`showOpenDialog` 和 `showSaveDialog` 解析为一个带有 bookmarks 字段的对象。 此字段是一个 Base64 编码字符串数组,其中包含已保存文件的 安全作用域书签 数据。 必须启用 `securityScopedBookmarks` 选项才能显示此项。

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

工作表

在 macOS 上,如果您在 window 参数中提供 BaseWindow 引用,则对话框将显示为附加到窗口的工作表;如果未提供窗口,则显示为模态对话框。

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