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 macOS Windows - 在对话框中显示隐藏文件。
  • 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' 不正确）。要显示所有文件，请使用 '*' 通配符（不支持其他通配符）。

[!NOTE] 在 Windows 和 Linux 上，打开对话框不能同时作为文件选择器和目录选择器，因此如果在这两个平台上将 properties 设置为 ['openFile', 'openDirectory']，将显示目录选择器。

```js @ts-type={mainWindow:Electron.BaseWindow} dialog.showOpenDialog(mainWindow, { properties: ['openFile', 'openDirectory'] }).then(result => { console.log(result.canceled) console.log(result.filePaths) }).catch(err => { console.log(err) })

> [!NOTE]
> 在 Linux 上，使用 portal 文件选择器对话框时，除非 portal 后端版本为 4 或更高，否则不支持 `defaultPath`。你可以使用 `--xdg-portal-required-version` [命令行开关](command-line-switches.md#--xdg-portal-required-versionversion) 来强制使用 gtk 或 kde 对话框。

### `dialog.showSaveDialogSync([window, ]options)` {#dialog-showsavedialogsync-window-options}

<!--
```YAML history
added:
  - pr-url: https://github.com/electron/electron/pull/17054

• 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 macOS Windows - 在对话框中显示隐藏文件。
  • 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
• message string - 消息框的内容。
• type string（可选） - 可以是 none、info、error、question 或 warning。在 Windows 上，question 显示与 info 相同的图标，除非 你使用 icon 选项设置图标。在 macOS 上，warning 和 error 都显示相同的警告图标。
• buttons string[] （可选） - 按钮文本的数组。在 Windows 上，空数组 将生成一个标记为 "OK" 的按钮。
• defaultId Integer（可选） - 消息框打开时默认选中的按钮在按钮数组中的索引。
• title string（可选） - 消息框的标题，某些平台不会显示它。
• detail string（可选） - 消息的附加信息。
• icon (NativeImage | string)（可选）
• textWidth Integer（可选） macOS - 消息框中文字的自定义宽度。
• cancelId Integer（可选） - 用于通过 Esc 键取消对话框的按钮索引。默认情况下， 它分配给标签为 "cancel" 或 "no" 的第一个按钮。如果不存在此类标签的按钮且未设置此选项， 将使用 0 作为返回值。
• noLink boolean（可选） - 在 Windows 上，Electron 会尝试确定 buttons 中哪些是 常用按钮（如 "Cancel" 或 "Yes"），并将其他按钮作为对话框中的命令链接显示。 这可以使对话框呈现出现代 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
• certificate Certificate - 要信任/导入的证书。
• message string - 要显示给用户的消息。

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

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

在 Windows 上，由于使用了 Win32 API，选项更为有限：

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

书签数组¶

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

工作表¶

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

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