dialog

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

プロセス: メイン

複数ファイルを選択するためのダイアログを表示する例

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

メソッド

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

dialog.showOpenDialogSync([window, ]options)

• window BaseWindow (オプション)
• options オブジェクト
  • title 文字列 (オプション)
  • defaultPath 文字列 (オプション)
  • buttonLabel 文字列 (オプション) - 確認ボタンのカスタムラベル。空のままにすると、デフォルトラベルが使用されます。
  • filters FileFilter[] (オプション)
  • properties 文字列配列 (オプション) - ダイアログが使用する機能を含みます。以下の値がサポートされています。
    • openFile - ファイルの選択を許可します。
    • openDirectory - ディレクトリの選択を許可します。
    • multiSelections - 複数パスの選択を許可します。
    • showHiddenFiles - ダイアログに隠しファイルを表示します。
    • createDirectory macOS - ダイアログから新しいディレクトリの作成を許可します。
    • promptToCreate Windows - ダイアログに入力されたファイルパスが存在しない場合、作成を促します。これは実際にはパスにファイルを作成しませんが、アプリケーションによって作成されるべき存在しないパスを返すことができます。
    • noResolveAliases macOS - 自動エイリアス (シンボリックリンク) パス解決を無効にします。選択されたエイリアスは、ターゲットパスではなくエイリアスパスを返します。
    • treatPackageAsDirectory macOS - .appフォルダなどのパッケージをファイルではなくディレクトリとして扱います。
    • dontAddToRecent Windows - 開いているアイテムを最近使用したドキュメントリストに追加しません。
  • message 文字列 (オプション) macOS - 入力ボックスの上に表示するメッセージ。
  • securityScopedBookmarks 真偽値 (オプション) macOS MAS - Mac App Store用にパッケージ化するときに、セキュリティスコープブックマークを作成します。

戻り値 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']
})

`dialog.showOpenDialog([window, ]options)`

• window BaseWindow (オプション)
• options オブジェクト
  • title 文字列 (オプション)
  • defaultPath 文字列 (オプション)
  • buttonLabel 文字列 (オプション) - 確認ボタンのカスタムラベル。空のままにすると、デフォルトラベルが使用されます。
  • filters FileFilter[] (オプション)
  • properties 文字列配列 (オプション) - ダイアログが使用する機能を含みます。以下の値がサポートされています。
    • openFile - ファイルの選択を許可します。
    • openDirectory - ディレクトリの選択を許可します。
    • multiSelections - 複数パスの選択を許可します。
    • showHiddenFiles - ダイアログに隠しファイルを表示します。
    • createDirectory macOS - ダイアログから新しいディレクトリの作成を許可します。
    • promptToCreate Windows - ダイアログに入力されたファイルパスが存在しない場合、作成を促します。これは実際にはパスにファイルを作成しませんが、アプリケーションによって作成されるべき存在しないパスを返すことができます。
    • noResolveAliases macOS - 自動エイリアス (シンボリックリンク) パス解決を無効にします。選択されたエイリアスは、ターゲットパスではなくエイリアスパスを返します。
    • treatPackageAsDirectory macOS - .appフォルダなどのパッケージをファイルではなくディレクトリとして扱います。
    • dontAddToRecent Windows - 開いているアイテムを最近使用したドキュメントリストに追加しません。
  • message 文字列 (オプション) macOS - 入力ボックスの上に表示するメッセージ。
  • securityScopedBookmarks 真偽値 (オプション) macOS MAS - Mac App Store用にパッケージ化するときに、セキュリティスコープブックマークを作成します。

戻り値 `Promise<Object>` - 以下を含むオブジェクトで解決します。

• `canceled` 真偽値 - ダイアログがキャンセルされたかどうか。
• `filePaths` 文字列配列 - ユーザーが選択したファイルパスの配列。ダイアログがキャンセルされた場合、これは空の配列になります。
• bookmarks 文字列配列 (オプション) 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 オブジェクト
  • title 文字列 (オプション) - ダイアログのタイトル。一部のLinuxデスクトップ環境では表示できません。
  • defaultPath 文字列 (オプション) - デフォルトで使用する絶対ディレクトリパス、絶対ファイルパス、またはファイル名。
  • buttonLabel 文字列 (オプション) - 確認ボタンのカスタムラベル。空のままにすると、デフォルトラベルが使用されます。
  • filters FileFilter[] (オプション)
  • message 文字列 (オプション) macOS - テキストフィールドの上に表示するメッセージ。
  • nameFieldLabel 文字列 (オプション) macOS - ファイル名テキストフィールドの前に表示されるテキストのカスタムラベル。
  • showsTagField 真偽値 (オプション) macOS - タグ入力ボックスを表示します。デフォルトは`true`です。
  • properties 文字列配列 (オプション)
    • showHiddenFiles - ダイアログに隠しファイルを表示します。
    • createDirectory macOS - ダイアログから新しいディレクトリの作成を許可します。
    • treatPackageAsDirectory macOS - .appフォルダなどのパッケージをファイルではなくディレクトリとして扱います。
    • showOverwriteConfirmation Linux - ユーザーがすでに存在するファイル名を入力した場合に、確認ダイアログを表示するかどうかを設定します。
    • dontAddToRecent Windows - 保存されているアイテムを最近使用したドキュメントリストに追加しません。
  • securityScopedBookmarks 真偽値 (オプション) macOS MAS - Mac App Store用にパッケージ化するときに、セキュリティスコープブックマークを作成します。このオプションが有効になっていて、ファイルがまだ存在しない場合、選択したパスに空のファイルが作成されます。

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

window引数を使用すると、ダイアログを親ウィンドウにアタッチしてモーダルにすることができます。

filtersは、表示できるファイルタイプの配列を指定します。例については、`dialog.showOpenDialog`を参照してください。

`dialog.showSaveDialog([window, ]options)`

• window BaseWindow (オプション)
• options オブジェクト
  • title 文字列 (オプション) - ダイアログのタイトル。一部のLinuxデスクトップ環境では表示できません。
  • defaultPath 文字列 (オプション) - デフォルトで使用する絶対ディレクトリパス、絶対ファイルパス、またはファイル名。
  • buttonLabel 文字列 (オプション) - 確認ボタンのカスタムラベル。空のままにすると、デフォルトラベルが使用されます。
  • filters FileFilter[] (オプション)
  • message 文字列 (オプション) macOS - テキストフィールドの上に表示するメッセージ。
  • nameFieldLabel 文字列 (オプション) macOS - ファイル名テキストフィールドの前に表示されるテキストのカスタムラベル。
  • showsTagField 真偽値 (オプション) macOS - タグ入力ボックスを表示します。デフォルトは`true`です。
  • properties 文字列配列 (オプション)
    • showHiddenFiles - ダイアログに隠しファイルを表示します。
    • createDirectory macOS - ダイアログから新しいディレクトリの作成を許可します。
    • treatPackageAsDirectory macOS - .appフォルダなどのパッケージをファイルではなくディレクトリとして扱います。
    • showOverwriteConfirmation Linux - ユーザーがすでに存在するファイル名を入力した場合に、確認ダイアログを表示するかどうかを設定します。
    • dontAddToRecent Windows - 保存されているアイテムを最近使用したドキュメントリストに追加しません。
  • securityScopedBookmarks 真偽値 (オプション) macOS MAS - Mac App Store用にパッケージ化するときに、セキュリティスコープブックマークを作成します。このオプションが有効になっていて、ファイルがまだ存在しない場合、選択したパスに空のファイルが作成されます。

戻り値 `Promise<Object>` - 以下を含むオブジェクトで解決します。

• `canceled` 真偽値 - ダイアログがキャンセルされたかどうか。
• filePath 文字列 - ダイアログがキャンセルされた場合、これは空の文字列になります。
• bookmark 文字列 (オプション) macOS MAS - 保存されたファイルのセキュリティスコープのブックマークデータを含む、base64エンコードされた文字列。これが存在するには、`securityScopedBookmarks`を有効にする必要があります。(戻り値については、ここにある表を参照してください。)

window引数を使用すると、ダイアログを親ウィンドウにアタッチしてモーダルにすることができます。

filtersは、表示できるファイルタイプの配列を指定します。例については、`dialog.showOpenDialog`を参照してください。

**注意:** macOSでは、ダイアログの展開と折りたたみ時の問題を回避するために、非同期バージョンを使用することをお勧めします。

`dialog.showMessageBoxSync([window, ]options)`

• window BaseWindow (オプション)
• options オブジェクト
  • message 文字列 - メッセージボックスの内容。
  • type 文字列 (オプション) - `none`、`info`、`error`、`question`、または`warning`を指定できます。Windowsでは、`icon`オプションを使用してアイコンを設定しない限り、`question`は`info`と同じアイコンを表示します。macOSでは、`warning`と`error`はどちらも同じ警告アイコンを表示します。
  • buttons 文字列配列 (オプション) - ボタンのテキストの配列。Windowsでは、空の配列は「OK」というラベルのボタンになります。
  • defaultId 整数 (オプション) - メッセージボックスが開いたときにデフォルトで選択される、`buttons`配列のボタンのインデックス。
  • title 文字列 (オプション) - メッセージボックスのタイトル。一部のプラットフォームでは表示されません。
  • detail 文字列 (オプション) - メッセージの追加情報。
  • icon (NativeImage | 文字列) (オプション)
  • textWidth 整数 (オプション) macOS - メッセージボックス内のテキストのカスタム幅。
  • cancelId 整数 (オプション) - `Esc`キーを使用してダイアログをキャンセルするために使用されるボタンのインデックス。デフォルトでは、これはラベルとして「キャンセル」または「いいえ」が付いた最初のボタンに割り当てられます。そのようなラベルのボタンが存在せず、このオプションが設定されていない場合、戻り値として`0`が使用されます。
  • noLink 真偽値 (オプション) - Windowsでは、Electronは`buttons`のどれが共通ボタン(「キャンセル」や「はい」など)であるかを判断し、ダイアログにコマンドリンクとして他のボタンを表示しようとします。これにより、ダイアログが最新のWindowsアプリのスタイルで表示される可能性があります。この動作が気に入らない場合は、`noLink`を`true`に設定できます。
  • normalizeAccessKeys ブール値（オプション） - プラットフォーム間でキーボードアクセスキーを正規化します。デフォルトは false です。これを有効にすると、キーボードショートカットアクセスキーの配置にボタンラベルで & が使用されていると想定され、各プラットフォームで正しく機能するようにラベルが変換されます。macOS では & 文字が削除され、Linux では _ に変換され、Windows では変更されません。たとえば、Vie&w というボタンラベルは、Linux では Vie_w に、macOS では View に変換され、Windows と Linux では Alt-W で選択できます。

Integer を返します - クリックされたボタンのインデックス。

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

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

dialog.showMessageBox([window, ]options)

• window BaseWindow (オプション)
• options オブジェクト
  • message 文字列 - メッセージボックスの内容。
  • type 文字列 (オプション) - `none`、`info`、`error`、`question`、または`warning`を指定できます。Windowsでは、`icon`オプションを使用してアイコンを設定しない限り、`question`は`info`と同じアイコンを表示します。macOSでは、`warning`と`error`はどちらも同じ警告アイコンを表示します。
  • buttons 文字列配列 (オプション) - ボタンのテキストの配列。Windowsでは、空の配列は「OK」というラベルのボタンになります。
  • defaultId 整数 (オプション) - メッセージボックスが開いたときにデフォルトで選択される、`buttons`配列のボタンのインデックス。
  • signal AbortSignal（オプション） - AbortSignal のインスタンスを渡して、オプションでメッセージボックスを閉じます。メッセージボックスは、ユーザーによってキャンセルされたかのように動作します。 macOS では、プラットフォームの制限により、親ウィンドウのないメッセージボックスは同期的に実行されるため、signal は機能しません。
  • title 文字列 (オプション) - メッセージボックスのタイトル。一部のプラットフォームでは表示されません。
  • detail 文字列 (オプション) - メッセージの追加情報。
  • checkboxLabel 文字列（オプション） - 指定された場合、メッセージボックスには指定されたラベルのチェックボックスが含まれます。
  • checkboxChecked ブール値（オプション） - チェックボックスの初期チェック状態。デフォルトは false です。
  • icon (NativeImage | 文字列) (オプション)
  • textWidth 整数 (オプション) macOS - メッセージボックス内のテキストのカスタム幅。
  • cancelId 整数 (オプション) - `Esc`キーを使用してダイアログをキャンセルするために使用されるボタンのインデックス。デフォルトでは、これはラベルとして「キャンセル」または「いいえ」が付いた最初のボタンに割り当てられます。そのようなラベルのボタンが存在せず、このオプションが設定されていない場合、戻り値として`0`が使用されます。
  • noLink 真偽値 (オプション) - Windowsでは、Electronは`buttons`のどれが共通ボタン(「キャンセル」や「はい」など)であるかを判断し、ダイアログにコマンドリンクとして他のボタンを表示しようとします。これにより、ダイアログが最新のWindowsアプリのスタイルで表示される可能性があります。この動作が気に入らない場合は、`noLink`を`true`に設定できます。
  • normalizeAccessKeys ブール値（オプション） - プラットフォーム間でキーボードアクセスキーを正規化します。デフォルトは false です。これを有効にすると、キーボードショートカットアクセスキーの配置にボタンラベルで & が使用されていると想定され、各プラットフォームで正しく機能するようにラベルが変換されます。macOS では & 文字が削除され、Linux では _ に変換され、Windows では変更されません。たとえば、Vie&w というボタンラベルは、Linux では Vie_w に、macOS では View に変換され、Windows と Linux では Alt-W で選択できます。

Promise<Object> を返します - 次のプロパティを含むPromiseで解決します

• response 数値 - クリックされたボタンのインデックス。
• checkboxChecked ブール値 - checkboxLabel が設定されている場合、チェックボックスのチェック状態。それ以外の場合は false です。

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

window引数を使用すると、ダイアログを親ウィンドウにアタッチしてモーダルにすることができます。

dialog.showErrorBox(title, content)

• title 文字列 - エラーボックスに表示するタイトル。
• content 文字列 - エラーボックスに表示するテキストコンテンツ。

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

このAPIは、app モジュールが発行する ready イベントの前に安全に呼び出すことができます。通常、起動の初期段階でエラーを報告するために使用されます。Linux でアプリの ready イベントの前に呼び出された場合、メッセージは stderr に出力され、GUI ダイアログは表示されません。

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

• window BaseWindow (オプション)
• options オブジェクト
  • certificate 証明書 - 信頼/インポートする証明書。
  • message 文字列 - ユーザーに表示するメッセージ。

Promise<void> を返します - 証明書の信頼ダイアログが表示されたときに解決します。

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

Windows では、使用される Win32 API により、オプションがより制限されます

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

ブックマーク配列

showOpenDialog、showOpenDialogSync、showSaveDialog、および showSaveDialogSync は、bookmarks 配列を返します。

ビルドタイプ	securityScopedBookmarks ブール値	戻り値の型	戻り値
macOS mas	True	成功	['LONGBOOKMARKSTRING']
macOS mas	True	エラー	[''] (空の文字列の配列)
macOS mas	False	該当なし	[] (空の配列)
mas 以外	任意	該当なし	[] (空の配列)

シート

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

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