dialog

ファイルを開いたり、保存したり、アラートを出したりするために、ネイティブのシステムダイアログを表示します。

Process: Main

以下は複数のファイルを選択する dialog を表示する例です。

const { dialog } = require('electron')
console.log(dialog.showOpenDialog({ properties: ['openFile', 'multiSelections'] }))

メソッド

dialog モジュールには以下のメソッドがあります。

dialog.showOpenDialogSync([window, ]options)

• window BaseWindow (任意)
• options Object
  • title string (任意)
  • defaultPath string (任意)
  • buttonLabel string (任意) - 確認ボタンのカスタムラベル。空のままにすると、既定のラベルが使用されます。
  • filters FileFilter[] (optional)
  • 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 向けにパッケージしたときに セキュリティスコープ付きブックマーク を作成します。

戻り値 string[] | undefined - ユーザが選択したファイルパス。dialog がキャンセルされた場合は 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']
})

dialog.showOpenDialog([window, ]options)

• window BaseWindow (任意)
• options Object
  • title string (任意)
  • defaultPath string (任意)
  • buttonLabel string (任意) - 確認ボタンのカスタムラベル。空のままにすると、既定のラベルが使用されます。
  • filters FileFilter[] (optional)
  • 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 向けにパッケージしたときに セキュリティスコープ付きブックマーク を作成します。

戻り値 Promise<Object> - 以下を含むオブジェクトで実行されます。

• canceled boolean - dialog がキャンセルされたかそうでないか。
• filePaths string[] - ユーザーによって選択されたファイルパスの配列. ダイアログがキャンセルされた場合、これは空の配列になります。
• bookmarks string[] (任意)macOS MAS - セキュリティスコープ付きブックマークを含む base64 エンコードされた filePaths 配列にマッチする配列。 データを取り込むために 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)
})

dialog.showSaveDialogSync([window, ]options)

• window BaseWindow (任意)
• options Object
  • title string (任意) - ダイアログのタイトル。 一部の Linux デスクトップ環境では表示できないことがあります。
  • defaultPath string (任意) - 既定で使用される絶対ディレクトリパス、絶対ファイルパスもしくはファイル名。
  • buttonLabel string (任意) - 確認ボタンのカスタムラベル。空のままにすると、既定のラベルが使用されます。
  • filters FileFilter[] (optional)
  • 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 向けにパッケージしたときに セキュリティスコープ付きブックマーク を作成します。 このオプションが有効でファイルが存在しない場合は、選択したパスに空のファイルが作成されます。

戻り値 string - ユーザが選択したファイルパス。dialog がキャンセルされた場合は空文字列を返します。

window の引数で、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。

filters には、表示することのできるファイルの種類の配列を指定します。例については、dialog.showOpenDialog を参照して下さい。

dialog.showSaveDialog([window, ]options)

• window BaseWindow (任意)
• options Object
  • title string (任意) - ダイアログのタイトル。 一部の Linux デスクトップ環境では表示できないことがあります。
  • defaultPath string (任意) - 既定で使用される絶対ディレクトリパス、絶対ファイルパスもしくはファイル名。
  • buttonLabel string (任意) - 確認ボタンのカスタムラベル。空のままにすると、既定のラベルが使用されます。
  • filters FileFilter[] (optional)
  • 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 向けにパッケージしたときに セキュリティスコープ付きブックマーク を作成します。 このオプションが有効でファイルが存在しない場合は、選択したパスに空のファイルが作成されます。

戻り値 Promise<Object> - 以下を含むオブジェクトで実行されます。

• canceled boolean - dialog がキャンセルされたかそうでないか。
• filePath string - ダイアログがキャンセルされると、これは空文字列になります。
• bookmark string (任意)macOS MAS - 保存されたファイルのセキュリティスコープのブックマークデータを含む Base64 エンコードされた文字列。 出力するために securityScopedBookmarks を有効にする必要があります。 (戻り値については、この表 を参照してください。)

window の引数で、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。

filters には、表示することのできるファイルの種類の配列を指定します。例については、dialog.showOpenDialog を参照して下さい。

注意: macOS では、ダイアログを展開したり折りたたんだりする際の問題を避けるために、非同期バージョンを使用することを推奨します。

dialog.showMessageBoxSync([wndow, ]options)

• window BaseWindow (任意)
• options Object
  • message string - メッセージボックスの内容。
  • type string (任意) - none、info、error、question、warning にすることができます。 Windowsでは、icon のオプションを使用してアイコンを設定しない場合、question は、info と同じアイコンを表示します。 macOSでは、warning と error の両方で同じ警告アイコンを表示します。
  • buttons string[] (任意) - ボタン用テキストの配列。 Windows では、空の配列は 1 つの "OK" ボタンになります。
  • defaultId Integer (任意) - メッセージボックスを開いたとき、既定で選択されるボタンの配列の中のボタンのインデックス。
  • title string (任意) - メッセージボックスのタイトル。いくつかのプラットフォームでは表示されません。
  • detail string (任意) - メッセージの追加情報。
  • icon (NativeImage | string) (optional)
  • textWidth Integer (任意) macOS - メッセージボックス内のテキストのカスタムな幅。
  • cancelId Integer (任意) - Esc キー経由でダイアログをキャンセルするのに使用されるボタンのインデックス。 既定では、これはラベルとして "cancel" または "no" の付いた最初のボタンに割り当てられます。 そのようにラベル付けされたボタンがなく、このオプションが設定されていない場合、0 が戻り値として使用されます。
  • noLink boolean (任意) - WindowsでElectronはどの buttons が ("Cancel" や "Yes" のような) 一般的なボタンかを把握し、その他をダイアログでコマンドリンクとして表示しようとします。 これにより、モダンなWindowsアプリのスタイルでダイアログを表示させることができます。 この動作が気に入らない場合、noLink を true に設定することができます。
  • normalizeAccessKeys boolean (任意) - プラットフォーム間でキーボードのアクセスキーを正規化します。 省略値は false です。 これを有効にすると、& が、ボタンのラベルでキーボードショートカットアクセスキーの位置として使用されているとみなされ、各プラットフォームで正常に動作するようにラベルが変換されます。macOSでは、& の文字は削除され、Linuxでは、_ に変換され、Windowsでは、そのままにされます。 例えば、Vie&w というボタンラベルは、Linuxでは、Vie_w、macOSでは、View に変換され、WindowsとLinuxでは、Alt-W 経由で選択できます。

戻り値 Integer - クリックされたボタンのインデックス。

メッセージボックスを表示し、メッセージボックスが閉じられるまでプロセスをブロックします。 クリックされたボタンのインデックスを返します。

window の引数で、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。 window が表示されていない場合、dialog はアタッチされません。 この場合は独立したウインドウとして表示されます。

dialog.showMessageBox([window, ]options)

• window BaseWindow (任意)
• options Object
  • message string - メッセージボックスの内容。
  • type string (任意) - none、info、error、question、warning にすることができます。 Windowsでは、icon のオプションを使用してアイコンを設定しない場合、question は、info と同じアイコンを表示します。 macOSでは、warning と error の両方で同じ警告アイコンを表示します。
  • buttons string[] (任意) - ボタン用テキストの配列。 Windows では、空の配列は 1 つの "OK" ボタンになります。
  • defaultId Integer (任意) - メッセージボックスを開いたとき、既定で選択されるボタンの配列の中のボタンのインデックス。
  • signal AbortSignal (任意) - 任意でメッセージボックスを閉じるために AbortSignal のインスタンスを渡すことができます。メッセージボックスはあたかもユーザーによってキャンセルされたかのように動作します。 macOS では、signal は親ウインドウのないメッセージボックスで動作しません。これらのメッセージボックスは、プラットフォーム上の制約により同期的に動作するからです。
  • title string (任意) - メッセージボックスのタイトル。いくつかのプラットフォームでは表示されません。
  • detail string (任意) - メッセージの追加情報。
  • checkboxLabel string (任意) - 指定した場合、メッセージボックスには、指定したラベルを持つチェックボックスが含まれます。
  • checkboxChecked boolean (任意) - チェックボックスの初期のチェック状態。 省略値は false です。
  • icon (NativeImage | string) (optional)
  • textWidth Integer (任意) macOS - メッセージボックス内のテキストのカスタムな幅。
  • cancelId Integer (任意) - Esc キー経由でダイアログをキャンセルするのに使用されるボタンのインデックス。 既定では、これはラベルとして "cancel" または "no" の付いた最初のボタンに割り当てられます。 そのようにラベル付けされたボタンがなく、このオプションが設定されていない場合、0 が戻り値として使用されます。
  • noLink boolean (任意) - WindowsでElectronはどの 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> - 以下のプロパティを含む Promise で解決されます。

• response number - クリックされたボタンのインデックス。
• checkboxChecked boolean - checkboxLabel が設定された場合、チェックボックスのチェック状態。 そうでない場合は false になります。

メッセージボックスを表示します。

window の引数で、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。

dialog.showErrorBox(title, content)

• title string - エラーボックスに表示するタイトル.
• content string - エラーボックスに表示するテキストの内容.

エラーメッセージを表示するモーダルダイアログを表示します。

app モジュールで ready イベントが発生する前でも、このAPIは安全に呼び出すことができます。これは、起動の初期段階でのエラーを報告するのによく使用されます。 Linuxで、appの ready イベントの前に呼び出すと、メッセージは標準エラーに出力され、GUIのダイアログは表示されません。

dialog.showCertificateTrustDialog([window, ]options) macOS Windows

• window BaseWindow (任意)
• options Object
  • certificate Certificate - The certificate to trust/import.
  • message string - ユーザーに表示するメッセージ。

戻り値 Promise<void> - 証明書信頼ダイアログが表示されると実行されます。

macOSでは、これはメッセージと証明書情報を表示するモーダルダイアログを表示し、ユーザーに証明書を信頼/インポートする選択肢を提供します。 window の引数を指定すると、ダイアログは親ウインドウにアタッチされ、モーダル表示になります。

Windowsでは、使用されているWin32 APIのため、オプションはより限定的です。

• OSが独自の確認ダイアログを提供しているため、message の引数は使用されません。
• この確認ダイアログをモーダル表示にすることができないため、window の引数は無視されます。

ブックマーク配列

showOpenDialog、showOpenDialogSync、showSaveDialog、 showSaveDialogSync は bookmarks と言う配列を返します。

ビルド種別	securityScopedBookmarks 真偽値	戻り値の型	返り値
macOS mas	True	Success	['LONGBOOKMARKSTRING']
macOS mas	True	エラー	[''] (空文字列の配列)
macOS mas	False	なし	[] (空の配列)
non mas	any	なし	[] (空の配列)

シート

macOS では、window パラメータに BaseWindow の参照を指定した場合、ダイアログはウインドウにアタッチされたシートとして表示されます。ウインドウを指定しない場合、モーダルで表示されます。

BaseWindow.getCurrentWindow().setSheetOffset(offset) を呼び出すことで、シートがアタッチされるウインドウフレームからのオフセットを変更することができます。