dialog
顯示用於開啟和儲存檔案、警示等的原生系統對話框。
程序：主程序
顯示對話框以選取多個檔案的範例
const { dialog } = require('electron')
console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))
方法
dialog 模組具有以下方法
dialog.showOpenDialogSync([window, ]options)
windowBaseWindow (選用)
傳回 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)
windowBaseWindow (選用)
傳回 Promise<Object> - 使用包含以下內容的物件解析
canceledboolean - 對話框是否已取消。filePathsstring[] - 使用者選擇的檔案路徑陣列。若對話框已取消，則這將會是空陣列。bookmarksstring[] (選用) 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)
windowBaseWindow (選用)
傳回 string，使用者選擇的檔案路徑；若對話框已取消，則傳回空字串。
window 引數允許對話框附加到父視窗，使其成為強制回應視窗。
filters 指定檔案類型陣列，如需範例，請參閱 dialog.showOpenDialog。
dialog.showSaveDialog([window, ]options)
windowBaseWindow (選用)
傳回 Promise<Object> - 使用包含以下內容的物件解析
canceledboolean - 對話框是否已取消。filePath字串 - 若對話框已取消，則這將會是空字串。bookmark字串 (選用) macOS MAS - Base64 編碼字串，其中包含已儲存檔案的安全範圍書籤資料。必須啟用securityScopedBookmarks才能顯示此欄位。(如需傳回值，請參閱此處的表格。)
window 引數允許對話框附加到父視窗，使其成為強制回應視窗。
filters 指定檔案類型陣列，如需範例，請參閱 dialog.showOpenDialog。
注意： 在 macOS 上，建議使用非同步版本，以避免在展開和摺疊對話框時發生問題。
dialog.showMessageBoxSync([wndow, ]options)
windowBaseWindow (選用)
傳回 Integer - 按下的按鈕索引。
顯示訊息框，它會封鎖程序，直到訊息框關閉。它會傳回按下的按鈕索引。
window 引數允許對話框附加到父視窗，使其成為強制回應視窗。若未顯示 window，則對話框將不會附加到父視窗。在這種情況下，它會顯示為獨立視窗。
dialog.showMessageBox([window, ]options)
windowBaseWindow (選用)
傳回 Promise<Object> - 使用包含以下屬性的 Promise 解析
responsenumber - 按下的按鈕索引。checkboxCheckedboolean - 若已設定checkboxLabel，則為核取方塊的核取狀態。否則為false。
顯示訊息框。
window 引數允許對話框附加到父視窗，使其成為強制回應視窗。
dialog.showErrorBox(title, content)
title字串 - 要在錯誤框中顯示的標題。content字串 - 要在錯誤框中顯示的文字內容。
顯示強制回應對話框，其中顯示錯誤訊息。
此 API 可以在 app 模組發出的 ready 事件之前安全地呼叫，它通常用於回報啟動早期階段的錯誤。若在 Linux 上應用程式的 ready 事件之前呼叫，則訊息將會發送到 stderr，並且不會出現 GUI 對話框。
dialog.showCertificateTrustDialog([window, ]options) macOS Windows
windowBaseWindow (選用)
傳回 Promise<void> - 在顯示憑證信任對話框時解析。
在 macOS 上，這會顯示強制回應對話框，其中顯示訊息和憑證資訊，並讓使用者選擇信任/匯入憑證。若您提供 window 引數，對話框將會附加到父視窗，使其成為強制回應視窗。
在 Windows 上，由於使用的 Win32 API，選項更受限制
- 未使用
message引數，因為作業系統提供其自己的確認對話框。 window引數會被忽略，因為無法使此確認對話框成為強制回應視窗。
書籤陣列
showOpenDialog 和 showSaveDialog 解析為具有 bookmarks 欄位的物件。此欄位是 Base64 編碼字串的陣列，其中包含已儲存檔案的安全範圍書籤資料。必須啟用 securityScopedBookmarks 選項才能顯示此欄位。
| 建置類型 | securityScopedBookmarks boolean | 傳回類型 | 傳回值 |
|---|---|---|---|
| macOS mas | True | 成功 | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | 錯誤 | [''] (空字串陣列) |
| macOS mas | False | 不適用 | [] (空陣列) |
| non mas | any | 不適用 | [] (空陣列) |
工作表
在 macOS 上，若您在 window 參數中提供 BaseWindow 參照，則對話框會顯示為附加到視窗的工作表；若未提供視窗，則會顯示為強制回應視窗。
您可以呼叫 BaseWindow.getCurrentWindow().setSheetOffset(offset) 以變更工作表附加到視窗框架的偏移量。