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> - 使用包含以下內容的物件解析
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)
windowBaseWindow (選用)
傳回 string，使用者選擇的檔案路徑；如果取消對話框，則傳回空字串。
window 引數允許對話框附加到父視窗，使其成為強制回應視窗。
filters 指定可顯示的檔案類型陣列，如需範例，請參閱 dialog.showOpenDialog。
dialog.showSaveDialog([window, ]options)
windowBaseWindow (選用)
傳回 Promise<Object> - 使用包含以下內容的物件解析
canceled布林值 - 是否取消對話框。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)
titlestring - 要在錯誤框中顯示的標題。contentstring - 要在錯誤框中顯示的文字內容。
顯示一個強制回應對話框，其中顯示錯誤訊息。
此 API 可以在 app 模組發出的 ready 事件之前安全地呼叫，它通常用於報告啟動早期的錯誤。如果在 Linux 上應用程式 ready 事件之前呼叫，則訊息將會發送到 stderr，並且不會出現 GUI 對話框。
dialog.showCertificateTrustDialog([window, ]options) macOS Windows
windowBaseWindow (選用)
傳回 Promise<void> - 在顯示憑證信任對話框時解析。
在 macOS 上，這會顯示一個強制回應對話框，其中顯示訊息和憑證資訊，並讓使用者選擇信任/匯入憑證。如果您提供 window 參數，對話框將會附加到父視窗，使其成為強制回應視窗。
在 Windows 上，由於使用的 Win32 API，選項受到更多限制。
- 不使用
message參數，因為作業系統會提供自己的確認對話框。 - 會忽略
window參數，因為無法使此確認對話框成為強制回應視窗。
書籤陣列
showOpenDialog、showOpenDialogSync、showSaveDialog 和 showSaveDialogSync 會傳回一個 bookmarks 陣列。
| 建置類型 | securityScopedBookmarks 布林值 | 傳回類型 | 傳回值 |
|---|---|---|---|
| macOS mas | True | 成功 | ['LONGBOOKMARKSTRING'] |
| macOS mas | True | 錯誤 | [''] (空字串陣列) |
| macOS mas | False | NA | [] (空陣列) |
| non mas | 任何 | NA | [] (空陣列) |
工作表
在 macOS 上，如果您在 window 參數中提供 BaseWindow 參考，則對話框會以附加到視窗的工作表形式呈現，如果沒有提供視窗，則會以強制回應視窗的形式呈現。
您可以呼叫 BaseWindow.getCurrentWindow().setSheetOffset(offset) 來變更工作表附加到視窗框架的偏移量。