dialog
显示用于打开和保存文件、警报等的本机系统对话框。
进程:主进程
下面是一个选择多个文件的对话框示例:
const { dialog } = require('electron')
console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))
方法
dialog
模块具有以下方法:
dialog.showOpenDialogSync([window, ]options)
window
BaseWindow (optional)选项
对象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时创建 security scoped bookmarks
返回 string[] | undefined
, 用户选择的文件路径,如果对话框被取消了 ,则返回undefined
。
The window
argument allows the dialog to attach itself to a parent window, making it modal.
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']
})
dialog.showOpenDialog([window, ]options)
window
BaseWindow (optional)选项
对象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时创建 security scoped bookmarks
返回 Promise<Object>
- resolve包含以下内容的object:
canceled
boolean - 对话框是否被取消。filePaths
string[] - 用户选择的文件路径的数组. 如果对话框被取消,这将是一个空的数组。bookmarks
string[] (optional) macOS MAS - 一个数组,filePaths
数组,base64编码字符串包含安全范围书签数据。securityScopedBookmarks
必须启用才能捕获数据。 (返回值见 这里的表格。)
The window
argument allows the dialog to attach itself to a parent window, making it modal.
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)
})
dialog.showSaveDialogSync([window, ]options)
window
BaseWindow (optional)选项
对象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时创建 security scoped bookmarks 当该选项被启用且文件尚不存在时,那么在选定的路径下将创建一个空文件。
Returns string
, the path of the file chosen by the user; if the dialog is cancelled it returns an empty string.
The window
argument allows the dialog to attach itself to a parent window, making it modal.
filters
可以指定可显示文件的数组类型,详见 dialog.showOpenDialog
事例
dialog.showSaveDialog([window, ]options)
window
BaseWindow (optional)选项
对象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时创建 security scoped bookmarks 当该选项被启用且文件尚不存在时,那么在选定的路径下将创建一个空文件。
返回 Promise<Object>
- resolve包含以下内容的object:
canceled
boolean - 对话框是否被取消。filePath
string - If the dialog is canceled, this will be an empty string.bookmark
string(optional) macOS MAS - 包含了安全作用域的书签数据 Base64 编码的字符串来保存文件。securityScopedBookmarks
必须启用才有效。 (返回值见 这里的表格。)
The window
argument allows the dialog to attach itself to a parent window, making it modal.
filters
可以指定可显示文件的数组类型,详见 dialog.showOpenDialog
事例
注意: 在macOS上,建议使用异步版本,以避免展开和折叠对话框时出现问题。
dialog.showMessageBoxSync([wndow, ]options)
window
BaseWindow (optional)选项
对象message
string - message box 的内容.type
string (可选) - 可以为none
,info
,error
,question
或者warning
. 在 Windows 上,question
与info
显示相同的图标, 除非你使用了icon
选项设置图标。 在 macOS 上,warning
和error
显示相同的警告图标buttons
string[] (可选) - 按钮文本数组。 在 Windows上,一个空数组将导致按钮被标为“OK”。defaultId
Integer (可选) - 在 message box 对话框打开的时候,设置默认选中的按钮,值为在 buttons 数组中的索引.title
string (可选) - message box 的标题,一些平台不显示.detail
string (可选) - 额外信息.icon
(NativeImage | string) (可选)textWidth
Integer (可选) macOS - 自定义消息框中文本的宽度cancelId
Integer (可选) - 用于取消对话框的按钮的索引,例如Esc
键. 默认情况下,它被分配给第一个按钮,文字为 “cancel” 或 “no”。 如果不存在这个标签的按钮,同时该选项又未设置,返回值为0
。noLink
boolean (可选) - 在Windows上,应用将尝试找出哪个buttons
是常用按钮(例如 "Cancel" 或 "Yes"),然后在对话框中以链接命令的方式展现其它的按钮。 这可以使对话框以现代Windows应用程序的风格显示。 如果你不喜欢这个行为, 你可以设置noLink
为true
.normalizeAccessKeys
boolean (可选) -规范跨平台的键盘访问键。 默认值为false
. 用&
连接和转换键盘访问键, 以便它们在每个平台上正常工作.&
字符会在macOS上被删除,在 Linux 上会被转换为_
,在 Windows 上保持不变。 例如Vie&w
的按钮标签在 Linux 上会被转换为Vie_w
,在 macOS 转换为View
并且可以被选择。而Windows和Linux上表示Alt-W
。
返回 Integer
- 点击的按钮的索引。
显示一个消息框,它将阻塞进程直到消息框关闭。 它返回点击的按钮的索引。
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. 在这种情况想,它将作为一个独立的窗口显示。
dialog.showMessageBox([window, ]options)
window
BaseWindow (optional)选项
对象message
string - message box 的内容.type
string (可选) - 可以为none
,info
,error
,question
或者warning
. 在 Windows 上,question
与info
显示相同的图标, 除非你使用了icon
选项设置图标。 在 macOS 上,warning
和error
显示相同的警告图标buttons
string[] (可选) - 按钮文本数组。 在 Windows上,一个空数组将导致按钮被标为“OK”。defaultId
Integer (可选) - 在 message box 对话框打开的时候,设置默认选中的按钮,值为在 buttons 数组中的索引.signal
AbortSignal (可选) - 通过 AbortSignal 信号实例可选地关闭消息框,消息框的行为就像用户点击取消一样。 在 macOS,signal
不适用于没有父窗口的消息框。因为平台限制,这些消息框同步运行title
string (可选) - message box 的标题,一些平台不显示.detail
string (可选) - 额外信息.checkboxLabel
string (可选) - 如果使用了,消息框将包含带有给定标签的复选框。checkboxChecked
boolean (可选) - checkbox 的初始值。 默认值为false
icon
(NativeImage | string) (可选)textWidth
Integer (可选) macOS - 自定义消息框中文本的宽度cancelId
Integer (可选) - 用于取消对话框的按钮的索引,例如Esc
键. 默认情况下,它被分配给第一个按钮,文字为 “cancel” 或 “no”。 如果不存在这个标签的按钮,同时该选项又未设置,返回值为0
。noLink
boolean (可选) - 在Windows上,应用将尝试找出哪个buttons
是常用按钮(例如 "Cancel" 或 "Yes"),然后在对话框中以链接命令的方式展现其它的按钮。 这可以使对话框以现代Windows应用程序的风格显示。 如果你不喜欢这个行为, 你可以设置noLink
为true
.normalizeAccessKeys
boolean (可选) -规范跨平台的键盘访问键。 默认值为false
. 用&
连接和转换键盘访问键, 以便它们在每个平台上正常工作.&
字符会在macOS上被删除,在 Linux 上会被转换为_
,在 Windows 上保持不变。 例如Vie&w
的按钮标签在 Linux 上会被转换为Vie_w
,在 macOS 转换为View
并且可以被选择。而Windows和Linux上表示Alt-W
。
返回 Promise<Object>
- resolve包含以下属性的promise:
response
number - 点击的按钮的索引。checkboxChecked
boolean - 如果设置了checkboxLabel
,返回复选框是否被选中的状态。 否则,返回false
。
显示一个消息框
The window
argument allows the dialog to attach itself to a parent window, making it modal.
dialog.showErrorBox(title, content)
title
string - 显示在错误框中的标题.content
string - 显示在错误框中的文本内容.
显示一个显示错误消息的模态对话框。
这个API可以在 app
模块触发 ready
事件之前被安全地调用,它通常用在启动时报告错误。 在 Linux 上, ready
事件之前调用这个API, 消息将被发送到stderr, 并且不会出现GUI对话框。
dialog.showCertificateTrustDialog([window, ]options)
macOS Windows
window
BaseWindow (optional)选项
对象certificate
Certificate - 信任/导入的证书message
string - 要向用户显示的消息
返回 Promise<void>
- 当显示信任证书对话框时resolve。
在macOS中, 将弹出一个用于展示消息与证书信息并向用户提供信任/导入证书的选项的模态对话框。 If you provide a window
argument the dialog will be attached to the parent window, making it modal.
在Windows中, 受限于Win32 API,可选项变得更为有限:
message
参数无效,因为操作系统提供了自身的确认对话框。window
参数被忽略,因此无法成为模态对话框。
Bookmarks 数组
showOpenDialog
、 showOpenDialogSync
、 showSaveDialog
和 showSaveDialogSync
将返回一个 bookmarks
数组。
构建类型 | securityScopedBookmarks boolean | 返回类型 | 返回值 |
---|---|---|---|
macOS mas | True | 成功 | ['LONGBOOKMARKSTRING'] |
macOS mas | True | Error | [''] (空字符串数组) |
macOS mas | False | NA | [] (空数组) |
non mas | any | NA | [] (空数组) |
工作表
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)
来更改附加工作表的窗口框架的偏移量。