dialog
显示用于打开和保存文件、提醒等的原生系统对话框。
进程: 主进程
显示用于选择多个文件的对话框示例
const { dialog } = require('electron')
console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))
方法
`dialog` 模块有以下方法
dialog.showOpenDialogSync([window, ]options)
window
BaseWindow (可选)
返回 `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 (可选)
返回 `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 (可选)
返回 `string`,用户选择的文件路径;如果对话框被取消,则返回空字符串。
`window` 参数允许对话框附加到父窗口,使其成为模态对话框。
`filters` 指定一个可以显示的文件类型数组,有关示例,请参见 `dialog.showOpenDialog`。
dialog.showSaveDialog([window, ]options)
window
BaseWindow (可选)
返回 `Promise<Object>` - 使用包含以下内容的对象进行解析
canceled
布尔值 - 对话框是否被取消。filePath
字符串 - 如果对话框被取消,这将是一个空字符串。bookmark
字符串 (可选) macOS MAS - Base64 编码的字符串,其中包含已保存文件的安全作用域书签数据。 必须启用 `securityScopedBookmarks` 才能显示此项。 (有关返回值,请参阅此处的表格。)
`window` 参数允许对话框附加到父窗口,使其成为模态对话框。
`filters` 指定一个可以显示的文件类型数组,有关示例,请参见 `dialog.showOpenDialog`。
注意: 在 macOS 上,建议使用异步版本,以避免在展开和折叠对话框时出现问题。
dialog.showMessageBoxSync([wndow, ]options)
window
BaseWindow (可选)
返回 `Integer` - 单击按钮的索引。
显示一个消息框,它将阻塞进程,直到消息框关闭。 它返回单击按钮的索引。
`window` 参数允许对话框附加到父窗口,使其成为模态对话框。 如果未显示 `window`,则对话框将不会附加到父窗口。 在这种情况下,它将显示为独立窗口。
dialog.showMessageBox([window, ]options)
window
BaseWindow (可选)
返回 `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 (可选)
返回 `Promise<void>` - 当显示证书信任对话框时解析。
在 macOS 上,这将显示一个模态对话框,其中显示消息和证书信息,并为用户提供信任/导入证书的选项。 如果您提供 window
参数,则对话框将附加到父窗口,使其成为模态对话框。
在 Windows 上,由于使用的 Win32 API,选项更加有限
- 不使用 `message` 参数,因为操作系统提供了自己的确认对话框。
- `window` 参数被忽略,因为无法使此确认对话框成为模态对话框。
书签数组
`showOpenDialog` 和 `showSaveDialog` 解析为一个带有 bookmarks
字段的对象。 此字段是一个 Base64 编码字符串数组,其中包含已保存文件的 安全作用域书签 数据。 必须启用 `securityScopedBookmarks` 选项才能显示此项。
构建类型 | securityScopedBookmarks 布尔值 | 返回类型 | 返回值 |
---|---|---|---|
macOS mas | True | 成功 | ['LONGBOOKMARKSTRING'] |
macOS mas | True | 错误 | [''] (空字符串数组) |
macOS mas | False | NA | [] (空数组) |
non mas | any | NA | [] (空数组) |
工作表
在 macOS 上,如果您在 window
参数中提供 BaseWindow
引用,则对话框将显示为附加到窗口的工作表;如果未提供窗口,则显示为模态对话框。
您可以调用 BaseWindow.getCurrentWindow().setSheetOffset(offset)
来更改工作表附加到的窗口框架的偏移量。