app

アプリケーションのイベントライフサイクルを制御します。

Process: Main

以下の例では最後のウインドウが閉じられたときにアプリケーションを終了する方法を示します。

const { app } = require('electron')
app.on('window-all-closed', () => {
  app.quit()
})

イベント

app オブジェクトでは以下のイベントが発生します。

イベント: 'will-finish-launching'

アプリケーションが基本的な起動処理を完了したときに発生します。 Windows と Linux上では、will-finish-launching イベントは ready イベントと同じです。macOS上では、このイベントはNSApplication の applicationWillFinishLaunching 通知を表しています。

ほとんどの場合、ready イベントハンドラーですべてのことを行うようにするべきです。

イベント: 'ready'

戻り値：

event Event
launchInfo Record<string, any> | NotificationResponse macOS

Electron が一度、初期化処理を完了したときに発生します。 macOS でアプリケーションが通知センターから起動された場合、launchInfo はアプリケーションを開くために使用された NSUserNotification の userInfo や UNNotificationResponse の情報を保持しています。また、app.isReady() を呼び出してこのイベントが発生したことがあるかどうかを確認したり、app.whenReady() を呼び出して Electron 初期化時に解決される Promise を取得したりできます。

注意: ready イベントは、メインプロセスがイベントループの最初のティックを完遂した後にのみ発生します。 ready イベントの前に Electron API を呼び出す必要がある場合は、メインプロセスのトップレベルのコンテキストで同期呼び出しをしてください。

イベント: 'window-all-closed'

すべてのウィンドウが閉じられたときに発生します。

このイベントを購読せずに全てのウインドウを閉じた場合、既定の動作としてアプリは終了します。しかし、このイベントを購読している場合は、アプリを終了するかどうかを制御することができます。ユーザが Cmd + Q を押下したり、開発者が app.quit() を呼び出したりした場合では、Electron はまず全てのウインドウを閉じようとして、その後に will-quit イベントを発生させます。しかし、この場合は window-all-closed イベントは発生しません。

イベント: 'before-quit'

戻り値：

event Event

アプリケーションがウィンドウを閉じ始める前に発生します。 event.preventDefault() を呼び出すことで、アプリケーションが終了する既定の動作を阻害できます。

注: アプリケーションの終了が autoUpdater.quitAndInstall() によって開始された場合、全てのウインドウで close イベントを発生させ、それらが閉じた_後_ に before-quit が発生します。

注釈: Windows では、このイベントはシステムのシャットダウン/再起動やユーザーのログアウトでアプリケーションが閉じられようとしている場合には発生しません。

イベント: 'will-quit'

戻り値：

event Event

すべてのウィンドウが閉じられ、アプリが終了しようとしているときに発生します。 event.preventDefault() を呼び出すことで、アプリケーションが終了する既定の動作を阻害できます。

will-quit と window-all-closed イベントの差異を確認するためには、window-all-closed イベントの説明もお読みください。

イベント: 'quit'

戻り値：

event Event
exitCode Integer

アプリケーションが終了するときに発生します。

イベント: 'open-file' macOS

戻り値：

event Event
path string

ユーザがアプリケーションでファイルを開こうとしたときに発生します。 open-file イベントは、大抵の場合ファイルをアプリケーションが既に開いていて、OS が開くために再利用しようとしたときに発生します。 open-file は、Dock にファイルがドロップされて、アプリケーションがまだ起動していないときにも発生します。このようなケースに対処するために、アプリケーション起動時の非常に早い段階 ( ready イベントが発生するよりも前) で open-file イベントを監視するようにしてください。

このイベントを処理する場合、event.preventDefault() を呼び出す必要があります。

Windows では、ファイルパスを取得するために (メインプロセスの) process.argv をパースしなければなりません。

イベント: 'open-url' macOS

戻り値：

event Event
url string

ユーザがこのアプリケーションで URL を開こうとしたときに発生します。アプリケーションの Info.plist ファイルで CFBundleURLTypes キーの中に URL スキームを定義し、NSPrincipalClass に AtomApplication を設定しなければなりません。

open-file イベントと同様に、アプリケーションの起動時に open-url イベントのリスナーを必ず登録し、アプリケーションが URL のハンドリングとして開かれているかどうかを検出するようにしてください。 ready イベントの応答でリスナーを登録すると、アプリケーション起動のトリガーとなった URL を逃すことになります。

イベント: 'activate' macOS

戻り値：

event Event
hasVisibleWindows boolean

アプリケーションがアクティブになったときに発生します。アプリケーションが最初に起動される、既に実行中のときにアプリケーションを再起動しようとする、アプリケーションの Dock やタスクバーのアイコンをクリックするなど、いろいろなアクションがこのイベントの引き金となり得ます。

イベント: 'did-become-active' macOS

戻り値：

event Event

アプリケーションがアクティブになったときに発生します。 did-become-active は activate イベントと異なり、アプリがアクティブになるときだけでなく、Dock アイコンがクリックされた時やアプリケーションが再起動した時にも発生します。また、ユーザーが macOS のアプリ切り替えでこのアプリへと切り替えたときにも発生します。

イベント: 'did-resign-active' macOS

戻り値：

event Event

アプリがアクティブでなくなり、フォーカスがなくなったときに発生します。これは例えば、他のアプリケーションをクリックしたり、macOS のアプリ切り替えで他のアプリケーションへ切り替えたりすると発生します。

イベント: 'continue-activity' macOS

戻り値：

event Event
type string - アクティビティを識別する文字列。 NSUserActivity.activityType と対応しています。
userInfo unknown - 別のデバイスのアクティビティによって保存されたアプリ固有の情報が含まれています。
details Object
- webpageURL string (任意) - 利用可能な場合、別デバイス上の操作でアクセスしたウェブページの URL を特定する文字列になります。

Handoff 中に別のデバイスからアクティビティを継続したいときに発生します。このイベントを処理する場合、event.preventDefault() を呼び出す必要があります。

ユーザのアクティビティはアクティビティ元のアプリと同一の開発者チームIDを持ち、アクティビティタイプをサポートするアプリでしか継続させることができません。サポートされるアクティビティタイプは、アプリの Info.plist の NSUserActivityTypes キーで指定されています。

イベント: 'will-continue-activity' macOS

戻り値：

event Event
type string - アクティビティを識別する文字列。 NSUserActivity.activityType と対応しています。

Handoff 中に別のデバイスからのアクティビティを継続しようとする前に発生します。このイベントを処理する場合、event.preventDefault() を呼び出す必要があります。

イベント: 'continue-activity-error' macOS

戻り値：

event Event
type string - アクティビティを識別する文字列。 NSUserActivity.activityType と対応しています。
error string - エラーのローカライズされた説明としての文字列。

Handoff 中に別のデバイスからのアクティビティを継続できなかったときに発生します。

イベント: 'activity-was-continued' macOS

戻り値：

event Event
type string - アクティビティを識別する文字列。 NSUserActivity.activityType と対応しています。
userInfo unknown - アクティビティによって保存されたアプリ固有の情報が含まれています。

Handoff 中にこのデバイスからのアクティビティを他のデバイスで継続させることに成功した後で発生します。

イベント: 'update-activity-state' macOS

戻り値：

event Event
type string - アクティビティを識別する文字列。 NSUserActivity.activityType と対応しています。
userInfo unknown - アクティビティによって保存されたアプリ固有の情報が含まれています。

Handoff が別のデバイスで継続し始めようとしているときに発生します。送信される情報を更新する必要があれば、event.preventDefault() をすぐに呼び出してください。そして、新しい userInfo 辞書を構築して app.updateCurrentActivity() を適切に呼び出してください。さもなくば操作は失敗し、continue-activity-error が呼び出されます。

イベント: 'new-window-for-tab' macOS

戻り値：

event Event

ユーザーが macOS ネイティブの新規タブボタンをクリックすると発生します。新規タブボタンは現在の BrowserWindow に tabbingIdentifier が設定されている場合にだけ表示されます。

イベント: 'browser-window-blur'

戻り値：

event Event
window BrowserWindow

Emitted when a browserWindow gets blurred.

イベント: 'browser-window-focus'

戻り値：

event Event
window BrowserWindow

Emitted when a browserWindow gets focused.

イベント: 'browser-window-created'

戻り値：

event Event
window BrowserWindow

Emitted when a new browserWindow is created.

イベント: 'web-contents-created'

戻り値：

event Event
webContents WebContents

Emitted when a new webContents is created.

イベント: 'certificate-error'

戻り値：

event Event
webContents WebContents
url string
error string - エラーコード
certificate Certificate
callback Function
- isTrusted boolean - 証明書を信頼できるものと見なすかどうか
isMainFrame boolean

url に対する certificate の検証に失敗したときに発生します。証明書を信頼するためには、event.preventDefault() で既定の動作をキャンセルして、callback(true) を呼び出すようにしてください。

const { app } = require('electron')

app.on('certificate-error', (event, webContents, url, error, certificate, callback) => {
  if (url === 'https://github.com') {
    // 検証ロジック。
    event.preventDefault()
    callback(true)
  } else {
    callback(false)
  }
})

イベント: 'select-client-certificate'

戻り値：

event Event
webContents WebContents
url URL
certificateList Certificate[]
callback Function
- certificate Certificate (optional)

クライアント証明書が要求されたときに発生します。

url がクライアント証明書を要求しているナビゲーションエントリーに対応していれば、リストからフィルターされたエントリーで callback を呼び出すことができます。 event.preventDefault() を使うことで、アプリケーションがストアから最初の証明書を使うのをキャンセルできます。

const { app } = require('electron')

app.on('select-client-certificate', (event, webContents, url, list, callback) => {
  event.preventDefault()
  callback(list[0])
})

戻り値：

event Event
webContents WebContents (任意)
authenticationResponseDetails Object
- url URL
- pid number
authInfo Object
- isProxy boolean
- scheme string
- host string
- port Integer
- realm string
callback Function
- username string (任意)
- password string (optional)

webContents またはユーテリティプロセスが Basic 認証を要求すると発生します。

既定の動作では、全てに認証をキャンセルします。これを変更するには、event.preventDefault() で既定の動作をキャンセルして、資格情報と共に callback(username, password) を呼び出すようにしてください。

const { app } = require('electron')

app.on('login', (event, webContents, details, authInfo, callback) => {
  event.preventDefault()
  callback('username', 'secret')
})

ユーザー名またはパスワードを渡さずに callback を呼び出すと、認証リクエストはキャンセルされ、認証エラーがページに返されます。

イベント: 'gpu-info-update'

GPU 情報の更新がある場合に発生します。

イベント: 'render-process-gone'

戻り値：

event Event
webContents WebContents
details RenderProcessGoneDetails

renderer processが予期せず消えたときに発生します。プロセスがクラッシュした場合やキルされた場合は正常です。

イベント: 'child-process-gone'

戻り値：

event Event
details Object
- type string - プロセスの種別。以下の値のいずれかです。
  - Utility
  - Zygote
  - Sandbox helper
  - GPU
  - Pepper Plugin
  - Pepper Plugin Broker
  - Unknown
- reason string - 子プロセスがなくなった理由。取りうる値:
  - clean-exit - ゼロの終了コードでプロセスが終了した
  - abnormal-exit - 非ゼロの終了コードでプロセスが終了した
  - killed - プロセスが SIGTERM シグナルの送信などの方法でキルされた
  - crashed - プロセスがクラッシュした
  - oom - プロセスがメモリ不足になった
  - launch-failed - プロセスが正常に起動されなかった
  - integrity-failure - Windows コードの整合性チェックに失敗した
- exitCode number - The exit code for the process (e.g. status from waitpid if on POSIX, from GetExitCodeProcess on Windows).
- serviceName string (任意) - そのプロセスのローカライズされていない名前。
- name string (任意) - そのプロセスの名前。ユーティリティの例: Audio Service, Content Decryption Module Service, Network Service, Video Captureなど

子 processが予期せず消えたときに発生します。プロセスがクラッシュした場合やキルされた場合は正常です。レンダラープロセスを含みません。

イベント: 'accessibility-support-changed' macOS Windows

戻り値：

event Event
accessibilitySupportEnabled boolean - Chrome のユーザ補助機能が有効な場合は true、そうでない場合は false。

Chromeのユーザ補助機能が変更されると発生します。このイベントはスクリーンリーダーのような支援技術が有効にされたり、無効にされたりしたときに発火します。詳細については、https://www.chromium.org/developers/design-documents/accessibility を参照してください。

イベント: 'session-created'

戻り値：

session Session

Electron が新しい session を作成したときに発生します。

const { app } = require('electron')

app.on('session-created', (session) => {
  console.log(session)
})

イベント: 'second-instance'

戻り値：

event Event
argv string[] - 2 つ目のインスタンスのコマンドライン引数の配列
workingDirectory string - 2 つ目のインスタンスの作業ディレクトリ
additionalData unknown - 2 つ目のインスタンスから渡される追加データの JSON オブジェクト

このイベントは、2 つ目のインスタンスが実行され app.requestSingleInstanceLock() が実行されたとき、アプリケーションの1つ目のインスタンス内で発火されます。

argv は2番目のインスタンスのコマンドライン引数の配列で、workingDirectory はその現在の作業ディレクトリです。通常、アプリケーションはこれに対して1番目のウインドウにフォーカスを当て、最小化しないように対応します。

注意: argv は 2 番目のインスタンスに渡されたものと全く同じ引数リストになるとは限りません。順番が変わったり、追加の引数が付け加えられたりする可能性があります。全く同じ引数を保持する必要がある場合は、代わりに additionalData の使用を推奨します。

注意: 2 つ目のインスタンスを 1 つ目のインスタンスと別のユーザーが起動した場合、 argv 配列には引数が含まれません。

このイベントは app の ready イベントが発生した後で実行されることが保証されます。

注意: Chromium が --original-process-start-time などのコマンドライン引数を追加することがあります。

メソッド

app オブジェクトには以下のメソッドがあります。

注意: いくつかのメソッドは特定のオペレーティングシステムでのみ利用可能ですので、そのようなラベルを付けてあります。

`app.quit()`

すべてのウインドウを閉じようとします。 before-quit イベントが最初に発生します。すべてのウインドウを閉じることに成功した場合、will-quit イベントが発生し、既定ではアプリケーションは終了します。

このメソッドは、すべての beforeunload および unload イベントハンドラーが正しく実行されることを保証します。 beforeunload イベントハンドラーで false を返すことによって、ウインドウが終了処理をキャンセルすることができます。

`app.exit([exitCode])`

exitCode Integer (optional)

exitCode ですぐに終了します。 exitCode の省略値は 0 です。

ユーザに確認することなくすべてのウインドウがすぐに閉じられ、before-quit および will-quit イベントは発生しません。

`app.relaunch([options])`

options Object (任意)
- args string[] (任意)
- execPath string (任意)

現在のインスタンスが終了したときに、アプリを再起動します。

既定では新しいインスタンスは現在のインスタンスと同じ作業ディレクトリおよびコマンドライン引数を使用します。 args が指定された場合、args がコマンドライン引数として代わりに引き渡されます。 execPath が指定された場合、execPath が再起動のため現在のアプリに代わって実行されます。

このメソッドは実行されているアプリを終了しないことに注意してください。アプリを再起動するには、app.relaunch を呼び出した後、app.quit または app.exit を呼び出さなければなりません。

app.relaunch を複数回呼び出した場合、現在のインスタンスが終了した後、複数のインスタンスが開始されます。

現在のインスタンスをすぐに再起動し、新しいコマンドライン引数を新しいインスタンスに追加する例:

const { app } = require('electron')

app.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) })
app.exit(0)

`app.isReady()`

戻り値 boolean - Electron の初期化が完了している場合 true、そうでない場合 false。 app.whenReady() も参照してください。

`app.whenReady()`

Returns Promise<void> - Electron が初期化されるときに実行される Promise。 app.isReady() を確認してアプリの準備がまだできていないときに ready イベントに登録するための、便利な代替手段として使用できます。

`app.focus([options])`

options Object (任意)
- steal boolean macOS - 他のアプリがアクティブな状態でも、レシーバのアプリをアクティブにします。

Linux では、最初の表示ウィンドウにフォーカスします。 macOS では、アプリケーションがアクティブになります。 Windows では、アプリケーションの最初のウィンドウにフォーカスします。

steal オプションはできるだけ慎重に使用してください。

`app.hide()` macOS

最小化することなくアプリケーションのすべてのウインドウを非表示にします。

`app.isHidden()` macOS

戻り値 boolean - アプリケーションがそのすべてのウィンドウを含めて (例えば Command-H で) 隠されている場合は true、それ以外は false です。

`app.show()` macOS

非表示にされたアプリケーションのウインドウを表示します。自動的にフォーカスしません。

`app.setAppLogsPath([path])`

path string (任意) - ログのカスタムパス。絶対パスでなければなりません。

アプリがロギングするディレクトリを設定または作成します。これは app.getPath() や app.setPath(pathName, newPath) で操作できます。

path 引数なしで app.setAppLogsPath() を呼び出すと、このディレクトリは、macOS では ~/Library/Logs/アプリ名 に、Linux と Windows では userData ディレクトリ内に設定されます。

`app.getAppPath()`

戻り値 string - 現在のアプリケーションのディレクトリ。

`app.getPath(name)`

name string - 以下のパスを名前で要求することができます。
- home ユーザのホームディレクトリ。
- appData - 既定のユーザ毎のアプリケーションデータディレクトリ。
  - Windowsの場合、%APPDATA%
  - Linuxの場合、$XDG_CONFIG_HOME もしくは ~/.config
  - macOSの場合、~/Library/Application Support
- userData アプリの設定ファイルが保存されるディレクトリで、既定ではアプリ名が加えられた appData のディレクトリ。慣習上ユーザーデータを保存するファイルはこのディレクトリに書き込まれるはずですが、環境によってはこのディレクトリをクラウドストレージにバックアップすることもあるため、大きなファイルをここに書き込むことは非推奨です。
- sessionData localStorage、Cookie、ディスクキャッシュ、ダウンロードした辞書、ネットワーク状態、デベロッパーツールのファイルなど、Session で生成したデータを保存するディレクトリです。既定ではこれは userData を指します。 Chromium はここに非常に大きなディスクキャッシュを書き込む可能性があるため、ユーザーデータの保存を localStorage や Cookie などのブラウザストレージに依存しないアプリの場合、userData ディレクトリを汚染しないよう、このディレクトリを他の場所に設定することが推奨されます。
- temp 一時ディレクトリ。
- exe 現在の実行ファイル。
- module libchromiumcontent ライブラリ。
- desktop 現在のユーザのデスクトップディレクトリ。
- documents ユーザの"マイドキュメント"のディレクトリ。
- downloads ユーザのダウンロードのディレクトリ。
- music ユーザのミュージックのディレクトリ。
- pictures ユーザのピクチャのディレクトリ。
- videos ユーザのビデオのディレクトリ。
- recent ユーザーが最近開いたファイルのディレクトリ (Windows のみ)。
- logs アプリのログフォルダのディレクトリ。
- crashDumps クラッシュダンプを格納するディレクトリ。

戻り値 string - name に関連付けられた特別なディレクトリもしくはファイルのパス。失敗した場合、Error が送出されます。

app.setAppLogsPath() を呼び出すよりも先に app.getPath('logs') が呼び出された場合、path 引数なしで app.setAppLogsPath() を呼び出すのに等しい、デフォルトのログディレクトリが作成されます。

`app.getFileIcon(path[, options])`

path string
options Object (任意)
- size string
  - small - 16x16
  - normal - 32x32
  - large - Linux の場合は 48x48、_Windows_の場合は 32x32、macOS の場合はサポートされていません。

Returns Promise<NativeImage> - fulfilled with the app's icon, which is a NativeImage.

パスに関連付けられているアイコンを取得します。

Windows の場合、以下の 2 種類のアイコンがあります。

.mp3、.png など、特定のファイル拡張子に関連付けられたアイコン。
.exe、.dll、.ico のような、ファイル自体に含まれるアイコン。

Linux と macOS の場合、アイコンはファイルの MIME タイプに関連付けられたアプリケーションによって決まります。

`app.setPath(name, path)`

name string
path string

name に関連付けられた特別なディレクトリもしくはファイルの path を上書きします。パスとして存在しないディレクトリが指定された場合、Error が投げられます。その場合、そのディレクトリを fs.mkdirSync や類似のもので作成するべきです。

app.getPath で定義されている name のパスだけを上書きすることができます。

既定では、WebページのCookieとキャッシュは sessionData ディレクトリに保存されます。この場所を変更するには、app モジュールの ready イベントが発生する前に sessionData を上書きする必要があります。

`app.getVersion()`

戻り値 string - ロードされたアプリケーションのバージョン。アプリケーションの package.json ファイルにバージョンが見つからない場合、現在のバンドルもしくは実行可能ファイルのバージョンが返却されます。

`app.getName()`

戻り値 string - アプリケーションの package.json ファイルで名前として設定された現在のアプリケーション名。

通常、package.json の name フィールドは、npm のモジュール仕様に基づいて小文字だけの短い名前が設定されます。通常、すべて大文字で始まるアプリケーションの名前となる productName フィールドも指定してください。Electronによって、name よりも優先されます。

`app.setName(name)`

name string

現在のアプリケーションの名前を上書きします。

注釈: この関数は、Electron 内で使用する名前を上書きします。OS が使用する名前には影響しません。

`app.getLocale()`

戻り値 string - 現在のアプリケーションのロケールで、Chromium の l10n_util ライブラリを用いて取得されます。取りうる戻り値についてはこちらにドキュメントがあります。

To set the locale, you'll want to use a command line switch at app startup, which may be found here.

注: アプリをパッケージ化して配布する場合、locales フォルダを同梱する必要があります。

注意: この API は ready イベントが発生した後に呼び出さなければなりません。

注意: この API の戻り値と他のロケールや言語の API と比較したサンプルコードは、app.getPreferredSystemLanguages() をご参照ください。

`app.getLocaleCountryCode()`

戻り値 string - 2 文字の ISO 3166 国名コードで、ユーザーの OS のロケールを示します。この値はネイティブの OS API から取得します。

注意: ロケールの国コードを取得できなかった場合、これは空文字列を返します。

`app.getSystemLocale()`

戻り値 string - 現在のシステムロケール。 Windows と Linux では、Chromium の i18n ライブラリを用いて取得します。 macOS では、[NSLocale currentLocale] を代わりに使用します。ユーザーの現在のシステム言語を取得するには、app.getPreferredSystemLanguages() を使用するとよいでしょう。これはロケールと同じとは限りません。

また、オペレーティングシステムによってもリージョンデータの扱いが異なります。

Windows 11 は数値、日付、時刻にリージョンごとの書式を使用します。
macOS Monterey は数値、日付、時刻の書式設定や、通貨記号の選択にリージョンを使用します。

そのため、この API はカレンダーアプリで日付や時刻を表示する際のフォーマットを選択するような用途、特に開発者が OS に適したフォーマットを希望する場合に利用できます。

注意: この API は ready イベントが発生した後に呼び出さなければなりません。

注意: この API の戻り値と他のロケールや言語の API と比較したサンプルコードは、app.getPreferredSystemLanguages() をご参照ください。

`app.getPreferredSystemLanguages()`

戻り値 string[] - ユーザーが希望するシステム言語を、最も希望するものから最も希望しないものまで、国番号も含めたものです。 Windows や macOS では、ユーザーが言語と地域の設定からこのリストを変更したり追加したりできます。

Windows では GlobalizationPreferences (GetSystemPreferredUILanguages へのフォールバックあり)、macOS では \[NSLocale preferredLanguages\]、Linux では g_get_language_names が API として使用されます。

この API は、アプリケーションをどの言語で表示するかを決定するなどの目的で使用できます。

以下に、さまざまな言語とロケールの API を設定した場合の戻り値の例を示します。

Windows で、アプリケーションのロケールがドイツ語、リージョンフォーマットがフィンランド語 (フィンランド)、優先システム言語は上からフランス語 (カナダ)、英語 (米国)、簡体字中国語 (中国)、フィンランド語、スペイン語 (ラテンアメリカ) になっているとします。

app.getLocale() // 'de'
app.getSystemLocale() // 'fi-FI'
app.getPreferredSystemLanguages() // ['fr-CA', 'en-US', 'zh-Hans-CN', 'fi', 'es-419']

macOS で、アプリケーションのロケールがドイツ語、リージョンがフィンランド、優先システム言語は上からフランス語 (カナダ)、英語 (米国)、簡体字中国語、スペイン語 (ラテンアメリカ) になっているとします。

app.getLocale() // 'de'
app.getSystemLocale() // 'fr-FI'
app.getPreferredSystemLanguages() // ['fr-CA', 'en-US', 'zh-Hans-FI', 'es-419']

利用可能な言語と地域とその戻り値は、この 2 つのオペレーティングシステムでも異なります。

上記の例からわかるように、Windows では優先システム言語が国コードを持たず、優先システム言語の 1 つがリージョンのフォーマットに使用されている言語と一致することがあります。 macOS では、リージョンはデフォルトの国コードとしてより多くの役割を果たします。ユーザーはフィンランドをリージョンとするために優先言語をフィンランド語にする必要はなく、国コード FI は、言語名に関連する国がない優先システム言語の国コードとして使用されます。

`app.addRecentDocument(path)` macOS Windows

path string

path を最近使ったドキュメントのリストに追加します。

このリストは OS が管理します。 Windows の場合はタスクバーからリストにアクセスでき、macOS の場合は Dock メニューからリストにアクセスできます。

`app.clearRecentDocuments()` macOS Windows

最近使ったドキュメントのリストをクリアします。

`app.setAsDefaultProtocolClient(protocol[, path, args])`

protocol string - :// を除くプロトコルの名前。例えば、アプリで electron:// リンクを処理したい場合、引数を electron にしてこのメソッドを呼び出してください。
path string (任意) Windows - Electron 実行形式へのパス。省略値は process.execPath です。
args string[] (任意) Windows - 実行形式に渡す引数。省略値は空の配列です。

戻り値 boolean - 呼び出しが成功したかどうか。

このメソッドは現在の実行形式をプロトコル (または URI スキーム) の既定のハンドラーとして設定します。これにより、アプリをオペレーティングシステムと密接に統合できます。登録すると、プロトコル:// によるすべてのリンクは現在の実行形式で開かれるようになります。プロトコルを含むリンク全体が、アプリケーションに引数として渡されます。

注: macOS の場合はアプリの info.plist に追加されているプロトコルしか登録できず、実行時に変更できません。しかし、Electron Forge や Electron Packager を介するかテキストエディタで info.plist を編集することで、ビルド時にファイルを変更できます。詳細は Apple社のドキュメントを参照するようにしてください。

注釈: Windows ストア環境 (appx としてパッケージされている) 場合、この API はすべての呼び出しに true を返しますが、それにセットされたレジストリキーは他のアプリケーションからアクセスできません。 Windows ストアアプリケーションをデフォルトのプロトコルハンドラとして登録するには、マニフェストでプロトコルを宣言する必要があります。

この API は内部的に Windows レジストリや LSSetDefaultHandlerForURLScheme を使用します。

`app.removeAsDefaultProtocolClient(protocol[, path, args])` macOS Windows

protocol string - :// を除くプロトコルの名前。
path string (任意) Windows - 省略値は process.execPath
args string[] (任意) Windows - 省略値は空の配列

戻り値 boolean - 呼び出しが成功したかどうか。

このメソッドは、現在の実行ファイルがプロトコル (または URI スキーム) のデフォルトハンドラであるかどうかをチェックします。その場合、既定のハンドラーからアプリを削除します。

`app.isDefaultProtocolClient(protocol[, path, args])`

protocol string - :// を除くプロトコルの名前。
path string (任意) Windows - 省略値は process.execPath
args string[] (任意) Windows - 省略値は空の配列

戻り値 boolean - 現在の実行形式がプロトコル (または URI スキーム) の既定のハンドラーかどうか。

注: macOSの場合、このメソッドは、アプリがプロトコルの既定のハンドラーとして登録されていたかをチェックするのに使えます。 macOSのマシン上の ~/Library/Preferences/com.apple.LaunchServices.plist を確認することでもこれを検証することができます。詳細は Apple社のドキュメントを参照するようにしてください。

この API は内部的に Windows レジストリや LSCopyDefaultHandlerForURLScheme を使用します。

`app.getApplicationNameForProtocol(url)`

url string - 確認するプロトコル名が付いた URL。類似の他メソッドとは異なり、少なくとも :// までを含む URL 全体を受け付けます (例: https://)。

戻り値 string - そのプロトコルを処理するアプリケーションの名前。ハンドラーがない場合は空の文字列です。たとえば、Electron がその URL のデフォルトハンドラーである場合、Windows と Mac では Electron になります。ただし、厳密な形式に依存しないでください。変更されている可能性があります。 Linux では、.desktop 接尾子を付けた別の形式が必要でしょう。

このメソッドは、URL のプロトコル (別名 URI スキーム) のデフォルトハンドラーであるアプリケーション名を返します。

`app.getApplicationInfoForProtocol(url)` macOS Windows

url string - 確認するプロトコル名が付いた URL。類似の他メソッドとは異なり、少なくとも :// までを含む URL 全体を受け付けます (例: https://)。

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

icon NativeImage - プロトコルを処理するアプリの表示アイコン。
path string - プロトコルを扱うアプリのインストールパス。
name string - プロトコルを扱うアプリの表示名。

このメソッドは、URL のプロトコル (別名 URI スキーム) のデフォルトハンドラーであるアプリケーション名、アイコン、パスを含むPromiseを返します。

`app.setUserTasks(tasks)` Windows

tasks Task[] - Array of Task objects

tasks を Windows でのジャンプリストのタスクカテゴリに追加します。

tasks is an array of Task objects.

戻り値 boolean - 呼び出しが成功したかどうか。

注: ジャンプリストをもっとカスタマイズしたい場合は、app.setJumpList(categories) を代わりに使用してください。

`app.getJumpListSettings()` Windows

戻り値 Object:

minItems Integer - ジャンプリストに表示されるアイテムの最小の数 (この値の詳細な説明は MSDN ドキュメントを参照してください) 。
removedItems JumpListItem[] - Array of JumpListItem objects that correspond to items that the user has explicitly removed from custom categories in the Jump List. これらのアイテムを直後の app.setJumpList() の呼び出しでジャンプリストに再度追加してはいけません。Windowsは削除されたアイテムを含むいかなるカスタムカテゴリも表示することはできません。

`app.setJumpList(categories)` Windows

categories JumpListCategory[] | null - Array of JumpListCategory objects.

戻り値 string

アプリケーションのカスタムジャンプリストを設定もしくは削除し、以下の文字列のいずれかを返します。

ok - 正常。
error - 1つ以上のエラーが発生しました。何が原因かを把握するためには、実行時ログを有効にします。
invalidSeparatorError - ジャンプリストのカスタムカテゴリに区切りを追加しようとしました。区切りは標準の タスク カテゴリでしか使用できません。
fileTypeRegistrationError - アプリが処理できると登録されていないファイルタイプのファイルリンクをジャンプリストに追加しようとしました。
customCategoryAccessDeniedError - ユーザープライバシーもしくはグループポリシー設定のため、ジャンプリストにカスタムカテゴリを追加できません。

categories が null の場合、その前に設定されていたカスタムジャンプリスト (あれば) は、(Windowsによって管理される) アプリ標準のジャンプリストに置換されます。

注: JumpListCategory オブジェクトに type プロパティも name プロパティも設定されなかった場合、type は tasks と見做されます。 name プロパティは設定されている一方で type プロパティが省略された場合、type は custom と見做されます。

注: ユーザはカスタムカテゴリからアイテムを削除できますが、Windows では次の app.setJumpList(categories) の呼び出しが成功した後でないと、削除されたアイテムをカスタムカテゴリに追加し直すことができません。それより早くカスタムカテゴリに削除されたアイテムを再度追加しようとすると、ジャンプリストからカスタムカテゴリ全体が外れてしまいます。削除されたアイテムのリストは、app.getJumpListSettings() を使って取得できます。

注: ジャンプリストのアイテムの description プロパティは最大長は 260 文字です。この制限を超えると、アイテムはジャンプリストに追加されず、表示されません。

カスタムジャンプリストを作成する非常に簡単な例は以下の通りです。

const { app } = require('electron')

app.setJumpList([
  {
    type: 'custom',
    name: 'Recent Projects',
    items: [
      { type: 'file', path: 'C:\\Projects\\project1.proj' },
      { type: 'file', path: 'C:\\Projects\\project2.proj' }
    ]
  },
  { // `type` は "custom" と見なされます
    name: 'Tools',
    items: [
      {
        type: 'task',
        title: 'Tool A',
        program: process.execPath,
        args: '--run-tool-a',
        iconPath: process.execPath,
        iconIndex: 0,
        description: 'Runs Tool A'
      },
      {
        type: 'task',
        title: 'Tool B',
        program: process.execPath,
        args: '--run-tool-b',
        iconPath: process.execPath,
        iconIndex: 0,
        description: 'Runs Tool B'
      }
    ]
  },
  { type: 'frequent' },
  { // 名前とタイプが無いので `type` は "tasks" と見なされます
    items: [
      {
        type: 'task',
        title: 'New Project',
        program: process.execPath,
        args: '--new-project',
        description: 'Create a new project.'
      },
      { type: 'separator' },
      {
        type: 'task',
        title: 'プロジェクトの復元',
        program: process.execPath,
        args: '--recover-project',
        description: 'プロジェクトを復元します。'
      }
    ]
  }
])

`app.requestSingleInstanceLock([additionalData])`

additionalData Record<any, any> (optional) - 最初のインスタンスに送信する追加データを格納する JSON オブジェクトです。

戻り値 boolean

このメソッドの戻り値は、アプリケーションのこのインスタンスのロックが成功したかどうかを表します。ロック状態にできなかった場合、アプリケーションの他のインスタンスが既にロックされており、ただちに終了すると想定できます。

つまり、このメソッドは、プロセスがアプリケーションの 1 つ目のインスタンスで、アプリがロード処理を続行する必要がある場合に true を返します。既にロック状態にしたものとは別のインスタンスにパラメータを送信したためプロセスが直ちに終了する必要がある場合は、false を返します。

macOSの場合、ユーザがFinderでアプリの2番目のインスタンスを開こうとしたとき、システムは自動的にシングルインスタンスになるようにし、open-file と open-url イベントが発生します。ただし、ユーザがアプリをコマンドラインで開始する場合、シングルインスタンスを強制するシステムの仕組みが迂回されるため、シングルインスタンスであることを保証するには、このメソッドを使う必要があります。

以下は、2つ目のインスタンスが開始されたときに1つ目のインスタンスのウインドウをアクティブにする例です。

const { app, BrowserWindow } = require('electron')
let myWindow = null

const additionalData = { myKey: 'myValue' }
const gotTheLock = app.requestSingleInstanceLock(additionalData)

if (!gotTheLock) {
  app.quit()
} else {
  app.on('second-instance', (event, commandLine, workingDirectory, additionalData) => {
    // 2 つ目のインスタンスから受け取ったデータを出力します。
    console.log(additionalData)

    // 誰かが 2 つ目のインスタンスを実行しようとしたので、このウインドウにフォーカスする必要があります。
    if (myWindow) {
      if (myWindow.isMinimized()) myWindow.restore()
      myWindow.focus()
    }
  })

  app.whenReady().then(() => {
    myWindow = new BrowserWindow({})
    myWindow.loadURL('https://electronjs.org')
  })
}

`app.hasSingleInstanceLock()`

戻り値 boolean

このメソッドはアプリのこのインスタンスが現在シングルインスタンスロックをされているかどうかを返します。 app.requestSingleInstanceLock() でロックを要求し、app.releaseSingleInstanceLock() で解放できます。

`app.releaseSingleInstanceLock()`

requestSingleInstanceLock によって作成されたすべてのロックを解放します。これにより、並列実行するための複数インスタンスのアプリケーションが再び許可されます。

`app.setUserActivity(type, userInfo[, webpageURL])` macOS

type string - アクティビティを一意に識別します。 NSUserActivity.activityType と対応しています。
userInfo any - 別のデバイスで使用するために保存されたアプリ固有の情報。
webpageURL string (任意) - 続行するデバイスに適切なアプリがインストールされていない場合、ブラウザで読み込むウェブページ。スキームは http もしくは https でなければなりません。

NSUserActivity を作成し、現在のアクティビティとして設定します。このアクティビティは後に別のデバイス上の Handoff で適用されます。

`app.getCurrentActivityType()` macOS

戻り値 string - 現在実行されているアクティビティのタイプです。

`app.invalidateCurrentActivity()` macOS

現在の Handoff のユーザアクティビティを無効にします。

`app.resignCurrentActivity()` macOS

現在の Handoff ユーザアクティビティを、無効にせずに不活性化します。

`app.updateCurrentActivity(type, userInfo)` macOS

type string - アクティビティを一意に識別します。 NSUserActivity.activityType と対応しています。
userInfo any - 別のデバイスで使用するために保存されたアプリ固有の情報。

タイプが type と一致した場合、現在のアクティビティを更新し、現在の userInfo ディスクショナリに userInfo のエントリを統合します。

`app.setAppUserModelId(id)` Windows

id string

アプリケーションユーザモデル ID を id に変更します。

`app.setActivationPolicy(policy)` macOS

policy string - 'regular', 'accessory', 'formited' のいずれかにできます。

アプリのアクティベーションポリシーを設定します。

アクティベーションポリシーの種類は以下のとおりです。

'regular' - Dock に表示される通常のアプリで、ユーザーインターフェースがあったりします。
'accessory' - このアプリケーションはドックに表示されず、メニューバーもありません。プログラムから又はウィンドウをクリックすることでアクティベートできます。
'prohibited' - アプリケーションはドックに表示されず、ウィンドウも作られず、アクティベートできません。

`app.importCertificate(options, callback)` Linux

options Object
- certificate string - pkcs12 ファイルへのパス。
- password string - 証明書のパスフレーズ。
callback Function
- result Integer - インポート結果。

プラットフォームの証明書ストアにPACS#12形式で証明書をインポートします。インポート操作の result で callback が呼び出されます。0 という値は成功を意味しますが、その他の値はChromium の net_error_list にある通りの失敗を意味します。

`app.configureHostResolver(options)`

options Object
- enableBuiltInResolver boolean (任意) - getaddrinfo ではなく組み込みのホストリゾルバを使用するかどうか。有効にすると、組み込みリゾルバはシステムの DNS 設定を使用し、単体で DNS ルックアップを実行しようとします。 macOS ではデフォルトで有効、Windows と Linux ではデフォルトで無効になっています。
- secureDnsMode string (任意) - 'off', 'automatic' or 'secure' のいずれかにできます。 DNS-over-HTTP モードを設定します。 'off' の場合、DoH ルックアップは行われません。 'automatic' の場合、DoH が利用可能であれば DoH ルックアップが最初に実行され、フォールバックとして安全でない DNS ルックアップが実行されます。 'secure' の場合、DoH ルックアップのみが実行されます。既定値は 'automatic' です。
- secureDnsServers string[] (任意) - DNS-over-HTTP サーバのテンプレートのリスト。テンプレートのフォーマットについては、RFC8484 § 3 をご参照ください。ほとんどのサーバーは POST メソッドをサポートしており、そういったサーバーのテンプレートは単なる URI です。なお、一部のDNSプロバイダでは、このリストに DoH サーバーが提供されていなくても、DoH が明示的に無効化されていない限りリゾルバを自動的に DoH へアップグレードします。
- enableAdditionalDnsQueryTypes boolean (任意) - 安全でない DNS 経由でリクエストが行われた場合に、従来の A および AAAA のクエリに加えて HTTPS (DNS タイプ 65) などの追加の DNS クエリタイプを許可するかどうかを制御します。追加タイプを常に許可するセキュア DNS には影響しません。省略値は true です。

ホスト解決 (DNS と DNS-over-HTTPS) を設定します。デフォルトでは、以下のリゾルバがこの順番で使用されます。

DNS-over-HTTPS、DNS プロバイダがサポートしている場合
組み込みリゾルバ (macOS のみデフォルトで有効)
システムのリゾルバ (getaddrinfo など)

これは、暗号化されていない DNS の使用を制限する (secureDnsMode: "secure") か、DNS-over-HTTPS を無効にする (secureDnsMode: "off") ように設定できます。また、組み込みリゾルバの有効化または無効化もできます。

安全でない DNS を無効にするには、 secureDnsMode に "secure" を指定します。その場合、ユーザーの DNS 設定に DoH をサポートするプロバイダが無い場合に備えて、使用する DNS-over-HTTPS サーバのリストを提供しなければなりません。

const { app } = require('electron')

app.whenReady().then(() => {
  app.configureHostResolver({
    secureDnsMode: 'secure',
    secureDnsServers: [
      'https://cloudflare-dns.com/dns-query'
    ]
  })
})

この API は ready イベントが発生した後で呼ばなければいけません。

`app.disableHardwareAcceleration()`

現在のアプリのハードウェアアクセラレーションを無効にします。

このメソッドはアプリが ready になる前だけでしか呼び出すことができません。

`app.disableDomainBlockingFor3DAPIs()`

既定では、GPU プロセスがあまりに頻繁にクラッシュする場合、ドメイン単位の原則に基づき、再起動するまで Chromium は 3D API (例えばWebGL) を無効にします。この関数はその振る舞いを無効にします。

このメソッドはアプリが ready になる前だけでしか呼び出すことができません。

`app.getAppMetrics()`

Returns ProcessMetric[]: Array of ProcessMetric objects that correspond to memory and CPU usage statistics of all the processes associated with the app.

`app.getGPUFeatureStatus()`

Returns GPUFeatureStatus - The Graphics Feature Status from chrome://gpu/.

注: この情報は gpu-info-update イベントが発行された後にのみ利用できます。

`app.getGPUInfo(infoType)`

infoType string - basic か complete にできます。

戻り値 Promise<unknown>

infoType が complete に等しい場合、Promise は Chromium の GPUInfo オブジェクト内におけるすべてのGPU情報を含んだ Object で解決されます。これには chrome://gpu ページ上で表示されるバージョンとドライバ情報が含まれます。

infoType が basic に等しい場合、Promise は complete でのGPU情報より少ない属性を含んだ Object で解決されます。 basic の応答の例はこちらです。

{
  auxAttributes:
   {
     amdSwitchable: true,
     canSupportThreadedTextureMailbox: false,
     directComposition: false,
     directRendering: true,
     glResetNotificationStrategy: 0,
     inProcessGpu: true,
     initializationTime: 0,
     jpegDecodeAcceleratorSupported: false,
     optimus: false,
     passthroughCmdDecoder: false,
     sandboxed: false,
     softwareRendering: false,
     supportsOverlays: false,
     videoDecodeAcceleratorFlags: 0
   },
  gpuDevice:
   [{ active: true, deviceId: 26657, vendorId: 4098 },
     { active: false, deviceId: 3366, vendorId: 32902 }],
  machineModelName: 'MacBookPro',
  machineModelVersion: '11.5'
}

vendorId や deviceId のような基本的な情報だけ必要であれば、basic を用いることが好ましいです。

`app.setBadgeCount([count])` Linux macOS

count Integer (任意) - 値が指定されている場合は、指定された値のバッジを設定します。そうでない場合、macOS では無地の白点 (通知数不明などの意味) を表示します。 Linux で値を指定しない場合、バッジは表示されません。

戻り値 boolean - 呼び出しが成功したかどうか。

現在のアプリのカウンターバッジを設定します。カウントを 0 に設定すると、バッジを非表示にします。

macOS では Dock アイコンに表示されます。 Linux では Unity ランチャーでのみ動作します。

注意: Unity ランチャーは動作にあたって .desktop ファイルを必要とします。詳しい情報は、Unity 統合ドキュメントをご参照ください。

注意: macOS でこのメソッドを動作させるときは、アプリケーションに通知の表示権限があることを確かめてください。

`app.getBadgeCount()` Linux macOS

戻り値 Integer - カウンターバッジに表示されている現在の値。

`app.isUnityRunning()` Linux

戻り値 boolean - 現在のデスクトップ環境が Unity ランチャーであるかどうか。

`app.getLoginItemSettings([options])` macOS Windows

options Object (任意)
- type string (任意) macOS - mainAppService, agentService, daemonService, loginItemService のいずれかにできます。省略値は mainAppService です。 macOS 13 以降でのみ利用できます。各タイプの詳細については、app.setLoginItemSettings をご参照ください。
- serviceName string (任意) macOS - サービスの名称。 type がデフォルトではない場合は必須です。 macOS 13 以降でのみ利用できます。
- path string (任意) Windows - 比較対象となる実行形式のパス。省略値は process.execPath です。
- args string[] (任意) Windows - 比較するコマンドライン引数。省略値は空の配列です。

app.setLoginItemSettings に path と args オプションを指定した場合、openAtLogin が正しく設定されるように、ここで同じ引数を引き渡す必要があります。

戻り値 Object:

openAtLogin boolean - アプリがログイン時に開くよう設定されている場合、true です。
openAsHidden boolean macOS 非推奨 - ログイン時にアプリを隠して開くように設定されている場合、true です。これは macOS 13 以降では動作しません。
wasOpenedAtLogin boolean macOS - アプリがログイン時に自動で開かれた場合、true です。
wasOpenedAsHidden boolean macOS 非推奨 - アプリが非表示のログイン項目として開かれていた場合、true です。これは、アプリが起動時に何もウインドウを開いてはいけないことを示します。この設定は MAS ビルドまたは macOS 13 以降では利用できません。
restoreState boolean macOS 非推奨 - 以前のセッションから状態を復元すべきログイン項目としてアプリが開かれた場合は、true です。これは、最後に閉じたときに開いていたウインドウをアプリが復元すべきことを示します。この設定は MAS ビルドまたは macOS 13 以降では利用できません。
status string macOS - not-registered, enabled, requires-approval, not-found のいずれかにできます。
executableWillLaunchAtLogin boolean Windows - アプリがログイン時に開くように設定されており、その実行キーが無効化されていない場合、true です。 openAtLoginはargs オプションを無視する点が異なっています。与えられた実行ファイルがログイン時なんらかの引数が与えれた場合にこのプロパティは真になります。
launchItems Object[] Windows
- name string Windows - レジストリエントリの名前の値。
- path string Windows - レジストリエントリに対応するアプリの実行形式。
- args string[] Windows - 実行形式に渡すコマンドライン引数。
- scope string Windows - user または machine のどちらか。レジストリエントリが HKEY_CURRENT USER または HKEY_LOCAL_MACHINE の下にあるかどうかを示します。
- enabled boolean Windows - アプリのレジストリキーがスタートアップ承認されていて、タスクマネージャと Windows の設定で enabled として表示されている場合、true です。

`app.setLoginItemSettings(settings)` macOS Windows

settings Object
- openAtLogin boolean (任意) - true にするとログイン時にアプリを開き、false にするとログイン項目からアプリを取り除きます。省略値は false です。
- openAsHidden boolean (任意) macOS 非推奨 - true にするとアプリを非表示で開きます。省略値は false です。ユーザはこの設定をシステム環境設定から変更することができるので、現在の値を取得するために app.getLoginItemSettings().wasOpenedAsHidden をアプリが開かれたときに確認するようにしてください。この設定は MAS ビルドまたは macOS 13 以降では利用できません。
- type string (任意) macOS - ログイン項目として追加するサービスの種別。省略値は mainAppService です。 macOS 13 以降でのみ利用できます。
  - mainAppService - 通常のアプリケーション。
  - agentService - 起動エージェントのプロパティリスト名。プロパティリスト名は、アプリの Contents/Library/LaunchAgents ディレクトリ内のプロパティリストに対応している必要があります。
  - daemonService string (任意) macOS - 起動エージェントのプロパティリスト名。プロパティリスト名は、アプリの Contents/Library/LaunchDaemons ディレクトリ内のプロパティリストに対応している必要があります。
  - loginItemService string (任意) macOS - ログイン項目のサービスのプロパティリスト名。プロパティリスト名は、アプリの Contents/Library/LoginItems ディレクトリ内のプロパティリストに対応している必要があります。
- serviceName string (任意) macOS - サービスの名称。 type がデフォルトではない場合は必須です。 macOS 13 以降でのみ利用できます。
- path string (任意) Windows - ログイン時に起動する実行形式。省略値は process.execPath です。
- args string[] (任意) Windows - 実行形式に渡すコマンドライン引数。省略値は空の配列です。パスはテンプレート文字列にするようにしましょう。
- enabled boolean (任意) Windows - true の場合、スタートアップ承認されたレジストリキーを変更し、タスクマネージャと Windows の設定でアプリを enable / disable にします。省略値は true です。
- name string (任意) Windows - レジストリに書き込む名前の値。デフォルトはアプリの AppUserModelId() です。

アプリのログイン項目設定を設定します。

Windows 上で Electron の autoUpdater を Squirrel で動かす場合、起動するパスを Update.exe に設定し、渡す引数にアプリケーション名を指定してください。以下がその例です。

const { app } = require('electron')
const path = require('node:path')

const appFolder = path.dirname(process.execPath)
const updateExe = path.resolve(appFolder, '..', 'Update.exe')
const exeName = path.basename(process.execPath)

app.setLoginItemSettings({
  openAtLogin: true,
  path: updateExe,
  args: [
    '--processStart', `"${exeName}"`,
    '--process-start-args', '"--hidden"'
  ]
})

macOS 13 以降でログイン項目として異なるサービスを設定する方法については、 SMAppService を参照してください。

`app.isAccessibilitySupportEnabled()` macOS Windows

戻り値 boolean - Chrome のアクセシビリティサポートが有効な場合 true、そうでない場合 false です。このAPIは、スクリーンリーダーなどの支援技術を使っていることが検出された場合、true を返します。詳細については、https://www.chromium.org/developers/design-documents/accessibility を参照してください。

`app.setAccessibilitySupportEnabled(enabled)` macOS Windows

enabled boolean - アクセシビリティツリーレンダリングを有効もしくは無効にします。

手動でChromeのユーザ補助機能を有効にすると、アプリケーションの設定でユーザにアクセシビリティスイッチを出すことができます。詳細については Chromium のアクセシビリティドキュメントを参照してください。既定では無効です。

この API は ready イベントが発生した後で呼ばなければいけません。

注: アクセシビリティツリーをレンダリングすると、アプリのパフォーマンスに顕著な影響を与える可能性があります。既定で有効にすべきではありません。

`app.showAboutPanel()`

アプリの About パネルを表示します。このオプションは app.setAboutPanelOptions(options)で上書きできます。この関数は非同期実行されます。

`app.setAboutPanelOptions(options)`

options Object
- applicationName string (任意) - アプリの名前。
- applicationVersion string (任意) - アプリのバージョン。
- copyright string (任意) - 著作権情報。
- version string (任意) macOS - アプリのビルドバージョン番号。
- credits string (任意) macOS Windows - クレジット情報。
- authors string[] (任意) Linux - アプリの作者のリスト。
- website string (任意) Linux - アプリのウェブサイト。
- iconPath string (任意) Linux Windows - JPEGまたはPNGフォーッマットの、アプリのアイコンへのパス。 Linux で、アスペクト比を保ったまま 64×64 ピクセルで表示されます。 Windows では、48x48 の PNG を使用すると最良の視覚品質になります。

Aboutパネルのオプションを設定します。 macOS の場合、これはアプリの .plist ファイルで定義された値を上書きします。詳細は Apple のドキュメントを参照してください。 Linuxの場合、表示するために値をセットしなければなりません。デフォルトの値はありません。

credits を設定していなくてもアプリに表示したい場合、AppKit は NSBundle の main クラスメソッドから返されたバンドル内で、"Credits.html"、"Credits.rtf"、"Credits.rtfd" の順番でファイルを探します。最初に見つかったファイルが使用されます。見つからない場合、その情報の部分は空白のままです。詳細は Apple のドキュメントを参照してください。

`app.isEmojiPanelSupported()`

戻り値 boolean - 現在の OS バージョンがネイティブの絵文字ピッカーを許可しているかどうか。

`app.showEmojiPanel()` macOS Windows

プラットフォームのネイティブの絵文字ピッカーを表示します。

`app.startAccessingSecurityScopedResource(bookmarkData)` MAS

bookmarkData string - dialog.showOpenDialog または dialog.showSaveDialog メソッドによって返された、base64 でエンコードされたセキュリティスコープのブックマークデータ。

戻り値 Function - セキュリティスコープ付きファイルへのアクセスが終了すれば、この関数の呼び出しを しなければなりません。ブックマークへのアクセスを忘れた場合は、カーネルリソースがリークします。アプリが再起動されるまで、サンドボックスの外部にアクセスする権限は失われます。

const { app, dialog } = require('electron')
const fs = require('node:fs')

let filepath
let bookmark

dialog.showOpenDialog(null, { securityScopedBookmarks: true }).then(({ filePaths, bookmarks }) => {
  filepath = filePaths[0]
  bookmark = bookmarks[0]
  fs.readFileSync(filepath)
})

// ... アプリを再起動 ...

const stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(bookmark)
fs.readFileSync(filepath)
stopAccessingSecurityScopedResource()

セキュリティスコープ付きリソースへのアクセスを開始します。このメソッドでは、Mac App Store 用にパッケージ化された Electron アプリケーションが、ユーザーが選択したファイルにアクセスするためにサンドボックスの外部にアクセスすることがあります。このシステムの動作の詳細は、Apple のドキュメントを参照してください。

`app.enableSandbox()`

アプリで完全サンドボックスモードを有効にします。 This means that all renderers will be launched sandboxed, regardless of the value of the sandbox flag in WebPreferences.

このメソッドはアプリが ready になる前だけでしか呼び出すことができません。

`app.isInApplicationsFolder()` macOS

戻り値 boolean - アプリケーションが現在、システムのアプリケーションフォルダから実行されているかどうか。 app.moveToApplicationsFolder() と組み合わせて使ってください。

`app.moveToApplicationsFolder([options])` macOS

options Object (任意)
- conflictHandler Function<boolean> (任意) - 移動に失敗したときの潜在的競合のハンドラ。
  - conflictType string - ハンドラーが遭遇した移動で起こった競合の種類。exists か existsAndRunning になります。exists は同じ名前のアプリがアプリケーションディレクトリに存在し、existsAndRunning は存在し且つ現在実行されていることを意味します。

戻り値 boolean - 移動が成功したかどうか。移動が成功した場合、アプリケーションは終了し、再起動されることに注意してください。

デフォルトでは確認ダイアログは表示されません。ユーザに操作の確認をさせたい場合は、dialog API で実現できます。

注意: このメソッドはユーザ以外が移動の失敗を引き起こした場合にもエラーを送出します。例えば、ユーザが承認ダイアログをキャンセルした場合、このメソッドは false を返します。コピーの実行に失敗した場合、このメソッドはエラーをスローします。エラーのメッセージは意味の分かるものにする必要があり、何が間違っているのかを正確に知らせるようにしてください。

既定では、移動するアプリと同じ名前のアプリがアプリケーションディレクトリに存在し実行されて いない 場合、既存のアプリはゴミ箱に移動され、新たなアプリがその場所に移動します。実行 されている 場合、既存の実行中のアプリはフォーカスを引き継ぎ、新たなアプリは自動的に終了します。この挙動は、オプションの競合ハンドラを提供することで変更できます。この場合、ハンドラによって返されるブール値によって、移動の競合がデフォルトの動作で解決されるかどうかを決定します。つまり、false を返すとそれ以上のアクションは行われなくなります。true を返すとデフォルトの動作になり、メソッドが続行されます。

以下がその例です。

const { app, dialog } = require('electron')

app.moveToApplicationsFolder({
  conflictHandler: (conflictType) => {
    if (conflictType === 'exists') {
      return dialog.showMessageBoxSync({
        type: 'question',
        buttons: ['Halt Move', 'Continue Move'],
        defaultId: 0,
        message: 'An app of this name already exists'
      }) === 1
    }
  }
})

そのユーザーディレクトリにアプリが既に存在する場合、ユーザーが '移動を続行' を選択すると、関数は既定の動作を続行し、既存のアプリは破棄され、新たなアプリはその場所に移動します。

`app.isSecureKeyboardEntryEnabled()` macOS

戻り値 boolean - キーボード入力のセキュリティを保護 が有効になっているかどうか。

この API は既定で false を返します。

`app.setSecureKeyboardEntryEnabled(enabled)` macOS

enabled boolean - キーボード入力のセキュリティを保護 を有効にするかどうか

アプリケーションの キーボード入力のセキュリティを保護 の有効化を設定します。

この API を利用すると、パスワードなどの重要な情報や機密情報を他のプロセスの傍受から防げます。

詳しくは Apple のドキュメントを参照してください。

注意: キーボード入力のセキュリティを保護 は必要なときにのみ有効にし、不要なときには無効にしてください。

`app.setProxy(config)`

config ProxyConfig

戻り値 Promise<void> - プロキシ設定処理が完了すると実行されます。

Session の関連付けなしで行われるネットワークリクエストのプロキシ設定をセットします。現在、これはユーティリティプロセス内の net を用いて行われたリクエストと、ランタイムによって行われる内部リクエスト (例: 地理位置情報クエリ) に影響します。

このメソッドは app が ready になる前でのみ呼び出すことができます。

`app.resolveProxy(url)`

url URL

戻り値 Promise<string> - ユーティリティプロセスで net を用いてリクエストを行うときに使用される url のプロキシ情報で解決します。

`app.setClientCertRequestPasswordHandler(handler)` Linux

handler Function<Promise<string>>
- clientCertRequestParamsオブジェクト
  - hostname string - the hostname of the site requiring a client certificate
  - tokenName string - the token (or slot) name of the cryptographic device
  - isRetry boolean - whether there have been previous failed attempts at prompting the password
Returns Promise<string> - Resolves with the password

The handler is called when a password is needed to unlock a client certificate for hostname.

const { app } = require('electron')

async function passwordPromptUI (text) {
  return new Promise((resolve, reject) => {
    // display UI to prompt user for password
    // ...
    // ...
    resolve('the password')
  })
}

app.setClientCertRequestPasswordHandler(async ({ hostname, tokenName, isRetry }) => {
  const text = `Please sign in to ${tokenName} to authenticate to ${hostname} with your certificate`
  const password = await passwordPromptUI(text)
  return password
})

プロパティ

`app.accessibilitySupportEnabled` macOS Windows

この boolean プロパティは、Chrome のアクセシビリティサポートが有効になっている場合は true、それ以外の場合は false になります。このプロパティは、テキスト読み上げなどのアシスト技術を使っていることが検出された場合、true を返します。手動でこのプロパティを true にセットして Chrome のアクセシビリティサポートを有効にすると、開発者はアプリケーション設定内でユーザにアクセシビリティスイッチを出すことができます。

詳細については Chromium のアクセシビリティドキュメントを参照してください。既定では無効です。

この API は ready イベントが発生した後で呼ばなければいけません。

`app.applicationMenu`

A Menu | null property that returns Menu if one has been set and null otherwise. Users can pass a Menu to set this property.

`app.badgeCount` Linux macOS

Integer 型のプロパティです。現在のアプリのバッジカウントを返します。カウントを 0 に設定するとバッジを非表示にします。

macOS では、ゼロ以外の整数を設定すると、ドックアイコンに表示されます。 Linux では Unity ランチャーでのみ動作します。

注意: Unity ランチャーは動作にあたって .desktop ファイルを必要とします。詳しい情報は、Unity 統合ドキュメントをご参照ください。

注意: macOS でこのプロパティを有効にするには、アプリケーションに通知を表示する権限があるかどうか確認する必要があります。

`app.commandLine` 読み出し専用

A CommandLine object that allows you to read and manipulate the command line arguments that Chromium uses.

`app.dock` macOS Readonly

Dock | undefined 型のオブジェクトです。macOS のユーザーの Dock 内のアプリアイコンにおけるアクションを実行できます。

`app.isPackaged` 読み出し専用

アプリがパッケージされている場合はtrue、それ以外は false を返す boolean プロパティ。多くのアプリケーションでは、このプロパティを用いて開発版の環境と製品版の環境を区別できます。

`app.name`

string 型のプロパティです。現在のアプリケーション名を示します。アプリケーションの package.json ファイル内にある名前になります。

`app.userAgentFallback`

この string は Electron がグローバルフォールバックとして使用するユーザーエージェント文字列です。

これは、webContents または session レベルでユーザーエージェントが設定されていない場合に使用されるユーザーエージェントです。アプリ全体が同じユーザーエージェントを持っていることを確認するのに役立ちます。オーバーライドされた値が確実に使用されるように、アプリの初期化のできるだけ早い段階でカスタム値に設定してください。

`app.runningUnderARM64Translation` Readonly macOS Windows

boolean 型で、trueの場合はアプリが現在 ARM64 変換機 (macOS の Rosetta 変換環境や Windows の WOW など) で動作していることを示します。

このプロパティを使用すれば、Rosetta や WOW 下で x64 版を誤って実行しても、ユーザーに arm64 版アプリケーションをダウンロードするよう促すことができます。

イベント
メソッド
プロパティ

イベント​

イベント: 'will-finish-launching'​

イベント: 'ready'​

イベント: 'window-all-closed'​

イベント: 'before-quit'​

イベント: 'will-quit'​

イベント: 'quit'​

イベント: 'open-file' macOS​

イベント: 'open-url' macOS​

イベント: 'activate' macOS​

イベント: 'did-become-active' macOS​

イベント: 'did-resign-active' macOS​

イベント: 'continue-activity' macOS​

イベント: 'will-continue-activity' macOS​

イベント: 'continue-activity-error' macOS​

イベント: 'activity-was-continued' macOS​

イベント: 'update-activity-state' macOS​

イベント: 'new-window-for-tab' macOS​

イベント: 'browser-window-blur'​

イベント: 'browser-window-focus'​

イベント: 'browser-window-created'​

イベント: 'web-contents-created'​

イベント: 'certificate-error'​

イベント: 'select-client-certificate'​

イベント: 'login'​

イベント: 'gpu-info-update'​

イベント: 'render-process-gone'​

イベント: 'child-process-gone'​

イベント: 'accessibility-support-changed' macOS Windows​

イベント: 'session-created'​

イベント: 'second-instance'​

メソッド​

app.quit()​

app.exit([exitCode])​

app.relaunch([options])​

app.isReady()​

app.whenReady()​

app.focus([options])​

app.hide() macOS​

app.isHidden() macOS​

app.show() macOS​

app.setAppLogsPath([path])​

app.getAppPath()​

app.getPath(name)​

app.getFileIcon(path[, options])​

app.setPath(name, path)​

app.getVersion()​

app.getName()​

app.setName(name)​

app.getLocale()​

app.getLocaleCountryCode()​

app.getSystemLocale()​

app.getPreferredSystemLanguages()​

app.addRecentDocument(path) macOS Windows​

app.clearRecentDocuments() macOS Windows​

app.setAsDefaultProtocolClient(protocol[, path, args])​

app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windows​

app.isDefaultProtocolClient(protocol[, path, args])​

app.getApplicationNameForProtocol(url)​

app.getApplicationInfoForProtocol(url) macOS Windows​

app.setUserTasks(tasks) Windows​

app.getJumpListSettings() Windows​

app.setJumpList(categories) Windows​

app.requestSingleInstanceLock([additionalData])​

app.hasSingleInstanceLock()​

app.releaseSingleInstanceLock()​

app.setUserActivity(type, userInfo[, webpageURL]) macOS​

app.getCurrentActivityType() macOS​

app.invalidateCurrentActivity() macOS​

app.resignCurrentActivity() macOS​

app.updateCurrentActivity(type, userInfo) macOS​

app.setAppUserModelId(id) Windows​

app.setActivationPolicy(policy) macOS​

app.importCertificate(options, callback) Linux​

app.configureHostResolver(options)​

app.disableHardwareAcceleration()​

app.disableDomainBlockingFor3DAPIs()​

app.getAppMetrics()​

app.getGPUFeatureStatus()​

app.getGPUInfo(infoType)​

イベント

イベント: 'will-finish-launching'

イベント: 'ready'

イベント: 'window-all-closed'

イベント: 'before-quit'

イベント: 'will-quit'

イベント: 'quit'

イベント: 'open-file' macOS

イベント: 'open-url' macOS

イベント: 'activate' macOS

イベント: 'did-become-active' macOS

イベント: 'did-resign-active' macOS

イベント: 'continue-activity' macOS

イベント: 'will-continue-activity' macOS

イベント: 'continue-activity-error' macOS

イベント: 'activity-was-continued' macOS

イベント: 'update-activity-state' macOS

イベント: 'new-window-for-tab' macOS

イベント: 'browser-window-blur'

イベント: 'browser-window-focus'

イベント: 'browser-window-created'

イベント: 'web-contents-created'

イベント: 'certificate-error'

イベント: 'select-client-certificate'

イベント: 'login'

イベント: 'gpu-info-update'

イベント: 'render-process-gone'

イベント: 'child-process-gone'

イベント: 'accessibility-support-changed' macOS Windows

イベント: 'session-created'

イベント: 'second-instance'

メソッド

`app.quit()`

`app.exit([exitCode])`

`app.relaunch([options])`

`app.isReady()`

`app.whenReady()`

`app.focus([options])`

`app.hide()` macOS

`app.isHidden()` macOS

`app.show()` macOS

`app.setAppLogsPath([path])`

`app.getAppPath()`

`app.getPath(name)`

`app.getFileIcon(path[, options])`

`app.setPath(name, path)`

`app.getVersion()`

`app.getName()`

`app.setName(name)`

`app.getLocale()`

`app.getLocaleCountryCode()`

`app.getSystemLocale()`

`app.getPreferredSystemLanguages()`

`app.addRecentDocument(path)` macOS Windows

`app.clearRecentDocuments()` macOS Windows

`app.setAsDefaultProtocolClient(protocol[, path, args])`

`app.removeAsDefaultProtocolClient(protocol[, path, args])` macOS Windows

`app.isDefaultProtocolClient(protocol[, path, args])`

`app.getApplicationNameForProtocol(url)`

`app.getApplicationInfoForProtocol(url)` macOS Windows

`app.setUserTasks(tasks)` Windows

`app.getJumpListSettings()` Windows

`app.setJumpList(categories)` Windows

`app.requestSingleInstanceLock([additionalData])`

`app.hasSingleInstanceLock()`

`app.releaseSingleInstanceLock()`

`app.setUserActivity(type, userInfo[, webpageURL])` macOS

`app.getCurrentActivityType()` macOS

`app.invalidateCurrentActivity()` macOS

`app.resignCurrentActivity()` macOS

`app.updateCurrentActivity(type, userInfo)` macOS

`app.setAppUserModelId(id)` Windows

`app.setActivationPolicy(policy)` macOS

`app.importCertificate(options, callback)` Linux

`app.configureHostResolver(options)`

`app.disableHardwareAcceleration()`

`app.disableDomainBlockingFor3DAPIs()`

`app.getAppMetrics()`

`app.getGPUFeatureStatus()`

`app.getGPUInfo(infoType)`