app

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

プロセス: メイン

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

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 を取得したりできます。

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

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

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

イベント: 'before-quit'​

戻り値:

• event Event

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

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

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

イベント: 'will-quit'​

戻り値:

• event Event

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

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

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

イベント: 'quit'​

戻り値:

• event Event
• exitCode Integer

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

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

イベント: '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

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

イベント: '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 - アクティビティを識別する文字列。 Maps to NSUserActivity.activityType.
• userInfo unknown - 別のデバイスのアクティビティによって保存されたアプリ固有の情報が含まれています。
• details Object
  • webpageURL string (任意) - 利用可能な場合、別デバイス上の操作でアクセスしたウェブページの URL を特定する文字列になります。

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

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

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

戻り値:

• event Event
• type string - アクティビティを識別する文字列。 Maps to NSUserActivity.activityType.

Handoff 中に、異なるデバイスでアクティビティが再開される前に発生します。 このイベントを処理する場合、event.preventDefault() を呼び出す必要があります。

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

戻り値:

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

Handoff 中に、異なるデバイスでアクティビティの再開に失敗したときに発生します。

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

戻り値:

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

Handoff 中、別のデバイスでアクティビティが正常に再開された後に発生します。

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

戻り値:

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

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

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

戻り値:

• event Event

ユーザーが macOS ネイティブの新規タブボタンをクリックすると発生します。 The new tab button is only visible if the current BrowserWindow has a tabbingIdentifier.

You must create a window in this handler in order for macOS tabbing to work as expected.

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

戻り値:

• event Event
• window BrowserWindow

browserWindow のフォーカスが外れたときに発生します。

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

戻り値:

• event Event
• window BrowserWindow

browserWindow がフォーカスされたときに発生します。

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

戻り値:

• event Event
• window BrowserWindow

新しく browserWinodow が生成されたときに発生します。

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

戻り値:

• event Event
• webContents WebContents

新しく webContents が作成されたときに発生します。

イベント: '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 (任意)

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

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

const { app } = require('electron')

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

イベント: 'login'​

戻り値:

• event Event
• webContents WebContents (任意)
• authenticationResponseDetails Object
  • url URL
  • pid number
  • isRequestForNavigation boolean - Indicates whether the request is for a navigation.
  • firstAuthAttempt boolean - Indicates whether this is the first authentication attempt.
  • responseHeaders Record<string, string | string[]> (optional) - The headers returned in the response.
• 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 コードの整合性チェックに失敗した
    • memory-eviction - 将来のメモリ不足（OOM）を防ぐため、事前にプロセスを終了した
  • exitCode number - プロセスの終了コード。（例: posix では waitpid から、Windows では GetExitCodeProcess からのステータス）
  • serviceName string (任意) - そのプロセスのローカライズされていない名前。
  • name string (任意) - そのプロセスの名前。 ユーティリティの例: Audio Service, Content Decryption Module Service, Network Service, Video Captureなど

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

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

戻り値:

• event Event
• accessibilitySupportEnabled boolean - true when Chromium's accessibility support is enabled, false otherwise.

Emitted when Chromium's accessibility support changes. このイベントはスクリーンリーダーのような支援技術が有効にされたり、無効にされたりしたときに発火します。 詳細については、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番目のウインドウにフォーカスを当て、最小化しないように対応します。

[!NOTE] 2 番目のインスタンスを最初のインスタンスと別のユーザーが起動した場合、 argv 配列には引数が含まれません。

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

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

メソッド​

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

[!NOTE] いくつかのメソッドは特定のオペレーティングシステムでのみ利用可能で、そのように注記がつけられています。

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 - 他のアプリがアクティブな状態でも、レシーバのアプリをアクティブにします。

macOS では、アプリケーションがアクティブになります。 Windows では、アプリケーションの最初のウィンドウにフォーカスします。 Linux では、最初の表示されているウインドウにフォーカスするか (X11)、フォーカスを要求するかその代わりに通知の表示やアプリアイコンの点滅を行います (Wayland)。

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

app.isActive() macOS​

Returns boolean - true if the application is active (i.e. focused).

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
  • assets アプリケーションのアセット (resources.pak など) が格納されているディレクトリ。 デフォルトでは、これは exe パスを含むフォルダと同じです。 Windows と Linux で利用できます。
  • userData アプリの設定ファイルが保存されるディレクトリで、既定ではアプリ名が加えられた appData のディレクトリ。 慣習上ユーザーデータを保存するファイルはこのディレクトリに書き込まれるはずですが、環境によってはこのディレクトリをクラウドストレージにバックアップすることもあるため、大きなファイルをここに書き込むことは非推奨です。 It is recommended to store app-specific files within a subdirectory of userData (e.g., path.join(app.getPath('userData'), 'my-app-data')) rather than directly in userData itself, to avoid naming conflicts with Chromium's own subdirectories (such as Cache, GPUCache, and Local Storage).
  • sessionData The directory for storing data generated by Session, such as localStorage, cookies, disk cache, downloaded dictionaries, network state, DevTools files. 既定ではこれは userData を指します。 Chromium はここに非常に大きなディスクキャッシュを書き込む可能性があるため、ユーザーデータの保存を localStorage や Cookie などのブラウザストレージに依存しないアプリの場合、userData ディレクトリを汚染しないよう、このディレクトリを他の場所に設定することが推奨されます。
  • temp 一時ディレクトリ。
  • exe 現在の実行ファイル。
  • module Chromiumモジュールの場所。 デフォルトでは、これは exe と同義です。
  • desktop 現在のユーザのデスクトップディレクトリ。
  • documents ユーザの"マイドキュメント"のディレクトリ。
  • downloads ユーザのダウンロードのディレクトリ。
  • music ユーザのミュージックのディレクトリ。
  • pictures ユーザのピクチャのディレクトリ。
  • videos ユーザのビデオのディレクトリ。
  • recent ユーザーが最近開いたファイルのディレクトリ (Windows のみ)。
  • logs アプリのログフォルダのディレクトリ。
  • crashDumps クラッシュダンプを格納するディレクトリ。

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

If app.getPath('logs') is called without calling app.setAppLogsPath() being called first, a default log directory will be created equivalent to calling app.setAppLogsPath() without a path parameter.

app.getFileIcon(path[, options])​

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

戻り値 Promise<NativeImage> - アプリのアイコンで解決され、これは 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

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

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

app.setDesktopName(name) Linux​

• name string - The .desktop filename (e.g. 'my-app.desktop').

Sets the .desktop filename on Linux. This should match the base filename of the app's installed .desktop file. The .desktop suffix is optional.

This value is used to determine the default XDG application ID on Wayland and WM_CLASS on X11. If it is not set, Electron will attempt to infer a name, but it may not match the packaged app's actual .desktop file. This could result in the app showing a generic icon or failing to respond to global keyboard shortcuts.

This API must be called before the ready event. The value can also be set using desktopName in package.json.

app.getLocale()​

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

ロケールを設定するには、アプリケーションの起動時にコマンドラインスイッチを使用する必要があります。これについては、こちら を参照してください。

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

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

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

app.getLocaleCountryCode()​

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

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

app.getSystemLocale()​

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

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

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

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

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

[!NOTE] この 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 つがリージョンのフォーマットに使用されている言語と一致することがあります。 On macOS, the region serves more as a default country code: the user doesn't need to have Finnish as a preferred language to use Finland as the region, and the country code FI is used as the country code for preferred system languages that do not have associated countries in the language name.

app.addRecentDocument(path) macOS Windows​

• path string

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

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

app.clearRecentDocuments() macOS Windows​

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

app.getRecentDocuments() macOS Windows​

戻り値 string[] - 最近使ったドキュメントのリストを取得します。

const { app } = require('electron')

const path = require('node:path')

const file = path.join(app.getPath('desktop'), 'foo.txt')
app.addRecentDocument(file)

const recents = app.getRecentDocuments()
console.log(recents) // ['/path/to/desktop/foo.txt'}

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

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

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

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

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

[!NOTE] 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 スキーム) の既定のハンドラーかどうか。

[!NOTE] 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)​

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

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

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

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

app.setUserTasks(tasks) Windows​

• tasks Task[] - Taskオブジェクトの配列

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

tasks は Task オブジェクトの配列です。

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

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

app.getJumpListSettings() Windows​

戻り値 Object:

• minItems Integer - The minimum number of items that will be shown in the Jump List (for a more detailed description of this value see the MSDN docs).
• removedItems JumpListItem[] - JumpListItem オブジェクトの配列。ユーザが明示的に、ジャンプリストのカスタムカテゴリから削除したアイテムに対応します。 これらのアイテムを直後の app.setJumpList() の呼び出しでジャンプリストに再度追加してはいけません。Windowsは削除されたアイテムを含むいかなるカスタムカテゴリも表示することはできません。

app.setJumpList(categories) Windows​

• categories JumpListCategory[] | null - JumpListCategory オブジェクトの配列。

戻り値 string

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

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

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

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

[!NOTE] ジャンプリストのアイテムの 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 - アクティビティを一意に識別します。 Maps to 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 - アクティビティを一意に識別します。 Maps to NSUserActivity.activityType.
• userInfo any - 別のデバイスで使用するために保存されたアプリ固有の情報。

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

app.setAppUserModelId(id) Windows​

• id string

Application User Model ID を id に変更します。

app.setToastActivatorCLSID(id) Windows​

• id string

Changes the Toast Activator CLSID to id. If one is not set via this method, it will be randomly generated for the app.

• The value must be a valid GUID/CLSID in one of the following forms:
  • Canonical brace-wrapped: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} (preferred)
  • Canonical without braces: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX (braces will be added automatically)
• Hex digits are case-insensitive.

This method should be called early (before showing notifications) so the value is baked into the registration/shortcut. Supplying an empty string or an unparsable value throws and leaves the existing (or generated) CLSID unchanged. If this method is never called, a random CLSID is generated once per run and exposed via app.toastActivatorCLSID.

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 ではデフォルトで無効になっています。
  • enableHappyEyeballs boolean (任意) - Happy Eyeballs V3 アルゴリズムを ネットワーク接続の作成に使用するかどうか。 有効にすると、複数の IP アドレスへのホスト名の解決が並行して試みられ、接続の確立をより高速に行います。
  • 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) を設定します。 デフォルトでは、以下のリゾルバがこの順番で使用されます。

1. DNS-over-HTTPS、DNS プロバイダがサポートしている 場合
2. 組み込みリゾルバ (macOS のみデフォルトで有効)
3. システムのリゾルバ (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.configureWebAuthn(options) macOS​

• options Object
  • touchID Object (optional) - Enables the Touch ID / Secure Enclave platform authenticator for Web Authentication requests.
    • keychainAccessGroup string - The keychain access group that WebAuthn credentials will be stored under. This value must also be present in your app's keychain-access-groups code-signing entitlement, and is typically of the form <TEAM_ID>.<BUNDLE_ID>.webauthn.
    • promptReason string (optional) - Customizes the reason text shown in the macOS Touch ID prompt. macOS renders the prompt as "<App Name>" is trying to <promptReason>, so the value should be a lowercase sentence fragment. An optional $1 placeholder is replaced with the relying party ID (e.g. example.com) of the request being authenticated. Defaults to verify your identity on $1.

Configures platform authenticators for the Web Authentication API (navigator.credentials.create() / navigator.credentials.get()). Until this is called, PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() resolves to false and platform-authenticator requests are not serviced.

When touchID is provided, WebAuthn credentials are stored in the macOS keychain and bound to this device's Secure Enclave. Electron automatically generates and persists a per-session metadata secret so that credentials created in one partition are not visible to another.

const { app } = require('electron')

app.configureWebAuthn({
  touchID: {
    keychainAccessGroup: 'A1B2C3D4E5.com.example.app.webauthn',
    promptReason: 'sign in to $1'
  }
})

With the matching entitlement in your app's entitlements.plist:

<key>keychain-access-groups</key>
<array>
  <string>A1B2C3D4E5.com.example.app.webauthn</string>
</array>

[!NOTE] Touch ID WebAuthn credentials are device-bound and are not synced via iCloud Keychain. They are only available on Macs with a Secure Enclave (Apple silicon, or Intel Macs with a T2 chip).

app.disableHardwareAcceleration()​

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

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

app.isHardwareAccelerationEnabled()​

戻り値 boolean - ハードウェアアクセラレーションが現在有効かどうか。

[!NOTE] この情報は gpu-info-update イベントが発生した後にのみ利用できます。

app.disableDomainBlockingFor3DAPIs()​

By default, Chromium disables 3D APIs (e.g. WebGL) until restart on a per domain basis if the GPU process crashes too frequently. この関数はその振る舞いを無効にします。

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

app.getAppMetrics()​

戻り値 ProcessMetric[]: ProcessMetric オブジェクトの配列で、アプリに関連付けられたすべてのプロセスのメモリや CPU 使用率の統計情報に対応しています。

app.getGPUFeatureStatus()​

戻り値 GPUFeatureStatus - chrome://gpu/ から取得したグラフィックス機能のステータス。

[!NOTE] この情報は 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 を用いることが好ましいです。

Promise is rejected if the GPU is completely disabled, i.e. no hardware and software implementations are available.

app.setBadgeCount([count]) Linux macOS​

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

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

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

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

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

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

app.getBadgeCount() Linux macOS​

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

app.isUnityRunning() Linux​

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

app.getLoginItemSettings([options]) macOS Windows​

• options Object (任意)
  • type string (optional) macOS - Can be mainAppService, agentService, daemonService, or 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 です。 これは、アプリが起動時に何もウインドウを開いてはいけないことを示します。 This setting is not available on MAS builds or on macOS 13 and up.
• restoreState boolean macOS 非推奨 - 以前のセッションから状態を復元すべきログイン項目としてアプリが開かれた場合は、true です。 これは、最後に閉じたときに開いていたウインドウをアプリが復元すべきことを示します。 This setting is not available on MAS builds or on macOS 13 and up.
• status string macOS - can be not-registered, enabled, requires-approval, or not-found.
• executableWillLaunchAtLogin boolean Windows - アプリがログイン時に開くように設定されており、その実行キーが無効化されていない場合、true です。 openAtLoginはargs オプションを無視する点が異なっています。与えられた実行ファイルがログイン時なんらかの引数が与えれた場合にこのプロパティは 真 になります。
• launchItems Object[] Windows
  • name string Windows - レジストリエントリの名前の値。
  • path string Windows - レジストリエントリに対応するアプリの実行形式。
  • args string[] Windows - 実行形式に渡すコマンドライン引数。
  • scope string Windows - can be user or 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 をアプリが開かれたときに確認するようにしてください。 This setting is not available on MAS builds or on macOS 13 and up.
  • 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 を使用している場合、起動パスを実行ファイル名から1階層上に設定する必要があります。これは Squirrel が自動的にスタブアプリケーションを作成し、自動的に最新バージョンのアプリケーションを起動するからです。

const { app } = require('electron')

const path = require('node:path')

const appFolder = path.dirname(process.execPath)
const ourExeName = path.basename(process.execPath)
const stubLauncher = path.resolve(appFolder, '..', ourExeName)

app.setLoginItemSettings({
  openAtLogin: true,
  path: stubLauncher,
  args: [
    // ここに、このアプリがログインによって起動されることを示す
    // パラメータを渡すことはできますが、必須ではありません
  ]
})

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

app.isAccessibilitySupportEnabled() macOS Windows​

Returns boolean - true if Chromium's accessibility support is enabled, false otherwise. このAPIは、スクリーンリーダーなどの支援技術を使っていることが検出された場合、true を返します。 詳細については、https://www.chromium.org/developers/design-documents/accessibility を参照してください。

app.setAccessibilitySupportEnabled(enabled) macOS Windows​

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

Manually enables Chromium's accessibility support, allowing to expose accessibility switch to users in application settings. 詳細は Chromium のアクセシビリティドキュメント をご覧ください。 既定では無効です。

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

[!NOTE] アクセシビリティツリーをレンダリングすると、アプリのパフォーマンスに顕著な影響を与える可能性があります。 既定で有効にすべきではありません。 このメソッドを呼び出すと、次のアクセシビリティ支援機能が有効になります: nativeAPIs、webContents、inlineTextBoxes、extendedProperties。

app.getAccessibilitySupportFeatures() macOS Windows​

戻り値 string[] - 現在有効なアクセシビリティ支援要素の名前を示す文字列の配列。 取りうる値:

• nativeAPIs - ネイティブ OS のアクセシビリティ API 統合が有効。
• webContents - ウェブコンテンツのアクセシビリティツリーの公開が有効。
• inlineTextBoxes - インラインテキストのボックス (文字範囲のボックス) が有効。
• extendedProperties - 拡張アクセシビリティプロパティが有効。
• screenReader - スクリーンリーダー用のモードが有効。
• html - HTML アクセシビリティツリーの構築が有効。
• labelImages - 自動画像注釈のアクセシビリティ支援。
• pdfPrinting - PDF 印刷のアクセシビリティ支援が有効。

注釈:

• アクセシビリティモードが有効でない場合、この配列は空になります。
• 従来の真偽値のチェックには app.isAccessibilitySupportEnabled() を使用してください。このメソッドは詳細な診断やテレメトリに使用することを推奨します。

サンプル:

const { app } = require('electron')

app.whenReady().then(() => {
  if (app.getAccessibilitySupportFeatures().includes('screenReader')) {
    // スクリーンリーダーでの動作を改善するために、一部のアプリ UI を変更します。
  }
})

app.setAccessibilitySupportFeatures(features) macOS Windows​

• features string[] - 有効にするアクセシビリティ機能の配列。

以下は取りうる値です。

• nativeAPIs - ネイティブ OS のアクセシビリティ API 統合が有効。
• webContents - ウェブコンテンツのアクセシビリティツリーの公開が有効。
• inlineTextBoxes - インラインテキストのボックス (文字範囲のボックス) が有効。
• extendedProperties - 拡張アクセシビリティプロパティが有効。
• screenReader - スクリーンリーダー用のモードが有効。
• html - HTML アクセシビリティツリーの構築が有効。
• labelImages - 自動画像注釈のアクセシビリティ支援。
• pdfPrinting - PDF 印刷のアクセシビリティ支援が有効。

サポートされている全機能を無効化するには、空の配列 [] を渡してください。

サンプル:

const { app } = require('electron')

app.whenReady().then(() => {
  // 機能のサブセットを有効化:
  app.setAccessibilitySupportFeatures([
    'screenReader',
    'pdfPrinting',
    'webContents'
  ])

  // 他のロジック

  // しばらくしてから、全機能を無効に:
  app.setAccessibilitySupportFeatures([])
})

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()

セキュリティスコープ付きリソースへのアクセスを開始します。 With this method, Electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. この機能の動作については、 Appleのドキュメント を参照してください。

app.enableSandbox()​

アプリで完全サンドボックスモードを有効にします。 これは、WebPreferences の sandbox フラグの値に関係なく、すべてのレンダラーがサンドボックスで起動されることを意味します。

このメソッドはアプリが 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 - クライアント証明書を必要とするサイトのホスト名
    • tokenName string - 暗号化デバイスのトークン (またはスロット) 名
    • isRetry boolean - パスワードの試行で以前に失敗した試行があったかどうか

  戻り値 Promise<string> - Resolve はパスワードで解決されます。

クライアント証明書を hostname でロックを解除するためにパスワードが必要な場合にハンドラが呼ばれます。

const { app } = require('electron')

async function passwordPromptUI (text) {
  return new Promise((resolve, reject) => {
    // パスワードを入力する画面を表示
    // ...
    // ...
    resolve('パスワード')
  })
}

app.setClientCertRequestPasswordHandler(async ({ hostname, tokenName, isRetry }) => {
  const text = `${hostname}の証明書を認証するため、${tokenName}へログインしてください。`
  const password = await passwordPromptUI(text)
  return password
})

プロパティ​

app.accessibilitySupportEnabled macOS Windows​

A boolean property that's true if Chromium's accessibility support is enabled, false otherwise. このプロパティは、テキスト読み上げなどのアシスト技術を使っていることが検出された場合、true を返します。 Setting this property to true manually enables Chromium's accessibility support, allowing developers to expose accessibility switch to users in application settings.

詳細は Chromium のアクセシビリティドキュメント をご覧ください。 既定では無効です。

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

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

app.applicationMenu​

Menu | null 型のプロパティです。設定されていれば Menu を、されていなければ null を返します。 ユーザはこのプロパティに Menu を渡すことができます。

app.badgeCount Linux macOS​

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

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

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

[!NOTE] macOS でこのプロパティが効果を発揮するには、アプリケーションに通知を表示する権限があることを確かめてください。

app.commandLine 読み出し専用​

CommandLine オブジェクトです。Chromium が使用するコマンドライン引数の読み取りと操作ができます。

app.dock macOS 読み出し専用​

Dock | undefined 型のプロパティです。(macOS では Dock 、その他のプラットフォームでは undefined になります。) ユーザーのDockにあるアプリアイコンに対して操作を実行できます。

app.isPackaged 読み出し専用​

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

app.toastActivatorCLSID Windows Readonly​

A string property that returns the app's Toast Activator CLSID.

app.name​

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

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

app.userAgentFallback​

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

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

app.runningUnderARM64Translation Readonly macOS Windows​

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

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