跳到主要内容

dialog

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

进程:主进程

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

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

方法

dialog 模块包含以下方法

dialog.showOpenDialogSync([window, ]options)

  • window BaseWindow (可选)
  • options Object
    • title string (可选)
    • defaultPath string (可选)
    • buttonLabel string (可选) - 确认按钮的自定义标签,如果留空将使用默认标签。
    • filters FileFilter[] (可选)
    • 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 时创建安全范围的书签

返回 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 上,当使用 portal 文件选择器对话框时,除非 portal 后端版本为 4 或更高,否则不支持 defaultPath。您可以使用 --xdg-portal-required-version 命令行开关强制使用 gtk 或 kde 对话框。

dialog.showOpenDialog([window, ]options)

  • window BaseWindow (可选)
  • options Object
    • title string (可选)
    • defaultPath string (可选)
    • buttonLabel string (可选) - 确认按钮的自定义标签,如果留空将使用默认标签。
    • filters FileFilter[] (可选)
    • 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 时创建安全范围的书签

返回 Promise<Object> - 解析为包含以下内容的对象

  • canceled boolean - 对话框是否被取消。
  • filePaths string[] - 用户选择的文件路径数组。如果对话框被取消,这将是一个空数组。
  • bookmarks string[] (可选) 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 上,当使用 portal 文件选择器对话框时,除非 portal 后端版本为 4 或更高,否则不支持 defaultPath。您可以使用 --xdg-portal-required-version 命令行开关强制使用 gtk 或 kde 对话框。

dialog.showSaveDialogSync([window, ]options)

  • window BaseWindow (可选)
  • options Object
    • title string (可选) - 对话框标题。在某些Linux桌面环境中可能无法显示。
    • defaultPath string (可选) - 默认使用的绝对目录路径、绝对文件路径或文件名。
    • buttonLabel string (可选) - 确认按钮的自定义标签,如果留空将使用默认标签。
    • filters FileFilter[] (可选)
    • 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 时创建安全范围的书签。如果启用此选项且文件不存在,将在所选路径创建空白文件。

返回 string,用户选择的文件路径;如果对话框被取消,则返回空字符串。

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

filters 指定了一个可显示的文件类型数组,请参阅 dialog.showOpenDialog 了解示例。

dialog.showSaveDialog([window, ]options)

  • window BaseWindow (可选)
  • options Object
    • title string (可选) - 对话框标题。在某些Linux桌面环境中可能无法显示。
    • defaultPath string (可选) - 默认使用的绝对目录路径、绝对文件路径或文件名。
    • buttonLabel string (可选) - 确认按钮的自定义标签,如果留空将使用默认标签。
    • filters FileFilter[] (可选)
    • 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 时创建安全范围的书签。如果启用此选项且文件不存在,将在所选路径创建空白文件。

返回 Promise<Object> - 解析为包含以下内容的对象

  • canceled boolean - 对话框是否被取消。
  • filePath string - 如果对话框被取消,这将是一个空字符串。
  • bookmark string (可选) macOS MAS - Base64 编码的字符串,包含保存文件的安全范围书签数据。必须启用 securityScopedBookmarks 才能存在此项。(有关返回值,请参见此处表格。)

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

filters 指定了一个可显示的文件类型数组,请参阅 dialog.showOpenDialog 了解示例。

注意

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

dialog.showMessageBoxSync([window, ]options)

  • window BaseWindow (可选)
  • options Object
    • message string - 消息框的内容。
    • type string (可选) - 可以是 noneinfoerrorquestionwarning。在 Windows 上,question 显示的图标与 info 相同,除非您使用 icon 选项设置了图标。在 macOS 上,warningerror 都显示相同的警告图标。
    • buttons string[] (可选) - 按钮文本数组。在 Windows 上,空数组将导致一个标记为“确定”的按钮。
    • defaultId Integer (可选) - 消息框打开时默认选中的按钮在 buttons 数组中的索引。
    • title string (可选) - 消息框的标题,某些平台不显示。
    • detail string (可选) - 消息的附加信息。
    • icon (NativeImage | string) (可选)
    • textWidth Integer (可选) macOS - 消息框中文本的自定义宽度。
    • cancelId Integer (可选) - 用于通过 Esc 键取消对话框的按钮索引。默认情况下,此项分配给标签为“cancel”或“no”的第一个按钮。如果不存在此类标签按钮且未设置此选项,则将使用 0 作为返回值。
    • noLink boolean (可选) - 在 Windows 上,Electron 会尝试找出 buttons 中哪些是常用按钮 (如“取消”或“是”),并将其他按钮显示为对话框中的命令链接。这可以使对话框以现代 Windows 应用的风格显示。如果您不喜欢此行为,可以将 noLink 设置为 true
    • normalizeAccessKeys boolean (可选) - 跨平台标准化键盘访问键。默认为 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 Object
    • message string - 消息框的内容。
    • type string (可选) - 可以是 noneinfoerrorquestionwarning。在 Windows 上,question 显示的图标与 info 相同,除非您使用 icon 选项设置了图标。在 macOS 上,warningerror 都显示相同的警告图标。
    • buttons string[] (可选) - 按钮文本数组。在 Windows 上,空数组将导致一个标记为“确定”的按钮。
    • defaultId Integer (可选) - 消息框打开时默认选中的按钮在 buttons 数组中的索引。
    • signal AbortSignal (可选) - 传递 AbortSignal 实例以选择性地关闭消息框,消息框将表现为被用户取消。在 macOS 上,signal 不适用于没有父窗口的消息框,因为这些消息框由于平台限制是同步运行的。
    • title string (可选) - 消息框的标题,某些平台不显示。
    • detail string (可选) - 消息的附加信息。
    • checkboxLabel string (可选) - 如果提供,消息框将包含一个带有给定标签的复选框。
    • checkboxChecked boolean (可选) - 复选框的初始选中状态。默认为 false
    • icon (NativeImage | string) (可选)
    • textWidth Integer (可选) macOS - 消息框中文本的自定义宽度。
    • cancelId Integer (可选) - 用于通过 Esc 键取消对话框的按钮索引。默认情况下,此项分配给标签为“cancel”或“no”的第一个按钮。如果不存在此类标签按钮且未设置此选项,则将使用 0 作为返回值。
    • noLink boolean (可选) - 在 Windows 上,Electron 会尝试找出 buttons 中哪些是常用按钮 (如“取消”或“是”),并将其他按钮显示为对话框中的命令链接。这可以使对话框以现代 Windows 应用的风格显示。如果您不喜欢此行为,可以将 noLink 设置为 true
    • normalizeAccessKeys boolean (可选) - 跨平台标准化键盘访问键。默认为 false。启用此选项假定按钮标签中使用 & 来放置键盘快捷方式访问键,并且标签将进行转换,使其在每个平台上都能正常工作,& 字符在 macOS 上被移除,在 Linux 上转换为 _,在 Windows 上保持不变。例如,按钮标签 Vie&w 在 Linux 上将转换为 Vie_w,在 macOS 上转换为 View,并且可以通过 Windows 和 Linux 上的 Alt-W 进行选择。

返回 Promise<Object> - 解析为包含以下属性的 Promise

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

显示一个消息框。

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

dialog.showErrorBox(title, content)

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

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

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

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

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

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

在 macOS 上,此方法会显示一个模态对话框,显示消息和证书信息,并允许用户选择信任/导入证书。如果提供 window 参数,对话框将附加到父窗口,使其成为模态对话框。

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

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

书签数组

showOpenDialogshowSaveDialog 解析为一个带有 bookmarks 字段的对象。此字段是 Base64 编码字符串的数组,其中包含已保存文件的安全范围书签数据。必须启用 securityScopedBookmarks 选项才能存在此项。

构建类型securityScopedBookmarks boolean返回类型返回值
macOS mas成功['LONGBOOKMARKSTRING']
macOS mas错误[''] (空字符串数组)
macOS mas不适用[] (空数组)
非 mas任意不适用[] (空数组)

表单

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

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