dialog
显示用于打开和保存文件、警告等的本地系统对话框。
进程：主进程
🌐 Process: Main
显示选择多个文件的对话框的示例：
🌐 An example of showing a dialog to select multiple files:
const { dialog } = require('electron')
console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))
方法
🌐 Methods
dialog 模块具有以下方法：
🌐 The dialog module has the following methods:
dialog.showOpenDialogSync([window, ]options)
windowBaseWindow（可选）
返回 string[] | undefined，即用户选择的文件路径；如果对话框被取消，则返回 undefined。
🌐 Returns string[] | undefined, the file paths chosen by the user; if the dialog is cancelled it returns undefined.
window 参数允许对话框附加到父窗口，使其成为模态窗口。
🌐 The window argument allows the dialog to attach itself to a parent window, making it modal.
filters 指定了一个文件类型数组，当你想限制用户只能选择特定类型时，可以显示或选择这些类型。例如：
🌐 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. For example:
{
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' 是错误的）。要显示所有文件，请使用 '*' 通配符（不支持其他通配符）。
🌐 The extensions array should contain extensions without wildcards or dots (e.g.
'png' is good but '.png' and '*.png' are bad). To show all files, use the
'*' wildcard (no other wildcard is supported).
在 Windows 和 Linux 上，打开对话框不能同时作为文件选择器和目录选择器使用，因此如果你在这些平台上将 properties 设置为 ['openFile', 'openDirectory']，将会显示目录选择器。
dialog.showOpenDialogSync(mainWindow, {
properties: ['openFile', 'openDirectory']
})
在 Linux 上，除非门户后端版本为 4 或更高，否则在使用门户文件选择器对话框时不支持 defaultPath。
你可以使用 --xdg-portal-required-version 命令行选项 来强制使用 gtk 或 kde 对话框。
dialog.showOpenDialog([window, ]options)
windowBaseWindow（可选）
返回 Promise<Object> - 解析为包含以下内容的对象：
🌐 Returns Promise<Object> - Resolve with an object containing the following:
canceled布尔值 - 对话框是否被取消。filePathsstring[] - 用户选择的文件路径数组。如果对话框被取消，将会是一个空数组。bookmarksstring[]（可选）macOS MAS - 一个与filePaths数组匹配的 base64 编码字符串数组，包含安全范围书签数据。必须启用securityScopedBookmarks才能填充此数据。（有关返回值，请参见此表）
window 参数允许对话框附加到父窗口，使其成为模态窗口。
🌐 The window argument allows the dialog to attach itself to a parent window, making it modal.
filters 指定了一个文件类型数组，当你想限制用户只能选择特定类型时，可以显示或选择这些类型。例如：
🌐 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. For example:
{
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' 是错误的）。要显示所有文件，请使用 '*' 通配符（不支持其他通配符）。
🌐 The extensions array should contain extensions without wildcards or dots (e.g.
'png' is good but '.png' and '*.png' are bad). To show all files, use the
'*' wildcard (no other wildcard is supported).
在 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)
windowBaseWindow（可选）
返回 string，即用户选择的文件路径；如果对话框被取消，则返回空字符串。
🌐 Returns string, the path of the file chosen by the user; if the dialog is cancelled it returns an empty string.
window 参数允许对话框附加到父窗口，使其成为模态窗口。
🌐 The window argument allows the dialog to attach itself to a parent window, making it modal.
filters 指定可以显示的文件类型数组，示例请参见 dialog.showOpenDialog。
🌐 The filters specifies an array of file types that can be displayed, see
dialog.showOpenDialog for an example.
dialog.showSaveDialog([window, ]options)
windowBaseWindow（可选）
返回 Promise<Object> - 解析为包含以下内容的对象：
🌐 Returns Promise<Object> - Resolve with an object containing the following:
canceled布尔值 - 对话框是否被取消。filePath字符串 - 如果对话被取消，则此字符串将为空。bookmark字符串（可选）macOS MAS - 包含已保存文件的安全范围书签数据的 Base64 编码字符串。必须启用securityScopedBookmarks才会出现此内容。（有关返回值，请参见 此处表格。）
window 参数允许对话框附加到父窗口，使其成为模态窗口。
🌐 The window argument allows the dialog to attach itself to a parent window, making it modal.
filters 指定可以显示的文件类型数组，示例请参见 dialog.showOpenDialog。
🌐 The filters specifies an array of file types that can be displayed, see
dialog.showOpenDialog for an example.
在 macOS 上，建议使用异步版本，以避免在展开和折叠对话框时出现问题。
dialog.showMessageBoxSync([window, ]options)
windowBaseWindow（可选）
返回 Integer —— 点击按钮的索引。
🌐 Returns Integer - the index of the clicked button.
显示一个消息框，它会阻塞进程直到消息框被关闭。它返回被点击按钮的索引。
🌐 Shows a message box, it will block the process until the message box is closed. It returns the index of the clicked button.
window 参数允许对话框附加到父窗口，使其成为模态窗口。如果未显示 window，对话框将不会附加到它。在这种情况下，它将作为独立窗口显示。
🌐 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. In such case it will be displayed as an independent window.
dialog.showMessageBox([window, ]options)
windowBaseWindow（可选）
返回 Promise<Object> - 解析为包含以下属性的 Promise：
🌐 Returns Promise<Object> - resolves with a promise containing the following properties:
response编号 - 被点击按钮的索引。checkboxChecked布尔值 - 如果设置了checkboxLabel，则表示复选框的选中状态。否则为false。
显示消息框。
🌐 Shows a message box.
window 参数允许对话框附加到父窗口，使其成为模态窗口。
🌐 The window argument allows the dialog to attach itself to a parent window, making it modal.
dialog.showErrorBox(title, content)
title字符串 - 在错误框中显示的标题。content字符串 - 要在错误框中显示的文本内容。
显示一个显示错误消息的模式对话框。
🌐 Displays a modal dialog that shows an error message.
在 app 模块触发 ready 事件之前，可以安全调用此 API，通常用于报告启动早期的错误。如果在 Linux 上应用触发 ready 事件之前调用，则消息将输出到 stderr，并且不会出现 GUI 对话框。
🌐 This API can be called safely before the ready event the app module emits,
it is usually used to report errors in early stage of startup. If called
before the app ready event on Linux, the message will be emitted to stderr,
and no GUI dialog will appear.
dialog.showCertificateTrustDialog([window, ]options) macOS Windows
windowBaseWindow（可选）
返回 Promise<void> - 当显示证书信任对话框时解析。
🌐 Returns Promise<void> - resolves when the certificate trust dialog is shown.
在 macOS 上，这会显示一个模态对话框，显示信息和证书信息，并给用户选择信任/导入证书的选项。如果提供 window 参数，对话框将附加到父窗口，使其成为模态窗口。
🌐 On macOS, this displays a modal dialog that shows a message and certificate
information, and gives the user the option of trusting/importing the
certificate. If you provide a window argument the dialog will be
attached to the parent window, making it modal.
在 Windows 上，由于使用了 Win32 API，选项更加有限：
🌐 On Windows the options are more limited, due to the Win32 APIs used:
message参数未使用，因为操作系统提供了自己的确认对话框。window参数会被忽略，因为无法将此确认对话框设置为模态。
书签数组
🌐 Bookmarks array
showOpenDialog 和 showSaveDialog 解析为一个包含 bookmarks 字段的对象。该字段是一个 Base64 编码字符串数组，包含已保存文件的 安全范围书签 数据。必须启用 securityScopedBookmarks 选项才能存在此字段。
| 构建类型 | securityScopedBookmarks 布尔值 | 返回类型 | 返回值 |
|---|---|---|---|
| macOS mas | True | 成功 | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | 错误 | ['']（空字符串数组） |
| macOS mas | False | 不适用 | []（空数组） |
| 非 mas | 任意 | 不适用 | []（空数组） |
床单
🌐 Sheets
在 macOS 上，如果你在 window 参数中提供了 BaseWindow 引用，对话框将作为附加在窗口上的面板显示；如果没有提供窗口，则显示为模态窗口。
🌐 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) 来更改工作表附着在窗口框架上的偏移量。
🌐 You can call BaseWindow.getCurrentWindow().setSheetOffset(offset) to change
the offset from the window frame where sheets are attached.