app
app
モジュールは、アプリケーションのライフサイクルコントロールを担います。
次の例は、最後のウィンドウが閉じたときにアプリケーションを終了させる方法を示しています。
const app = require('electron').app
app.on('window-all-closed', function () {
app.quit()
})
イベント
app
オブジェクトは次のイベントを出力します。
イベント: 'will-finish-launching'
アプリケーションの基礎起動が終わったときに出力されます。Windows と Linuxでは、 will-finish-launching
イベントとready
イベントは同じです。macOSでは、NSApplication
の applicationWillFinishLaunching
通知をに相当します。通常、open-file
とopen-url
用のリスナーの設定、クラッシュレポートの開始、自動アップデートをします。
ほとんどの場合、 ready
イベントハンドラーですべてをするべきです。
イベント: 'ready'
Electronの初期化が終わった時に出力します。
イベント: 'window-all-closed'
全てのウィンドウを閉じたときに出力します。
このイベントは、アプリケーションが終了する予定ではないときのみ出力します。ユーザーが Cmd + Q
を押したり、開発者がapp.quit()
をコールすると、Electronは最初にすべてのウィンドウをクローズしようとし、will-quit
イベントを出力します。この場合、window-all-closed
イベントは出力されません。
イベント: 'before-quit'
戻り値:
event
Event
アプリケーションがウィンドウをクローズし始める前に出力します。event.preventDefault()
をコールすると、アプリケーションを終了させる既定の挙動を止めることができます。
イベント: 'will-quit'
戻り値:
event
Event
全てのウィンドウが閉じて、アプリケーションを終了するときに出力します。event.preventDefault()
をコールすると、アプリケーションを終了させる既定の挙動を止めることができます。
詳細は、will-quit
イベント と window-all-closed
イベントの違いは、window-all-closed
イベントの説明を見てください。
イベント: 'quit'
戻り値:
event
EventexitCode
Integer
アプリケーションが終了したときに出力されます。
イベント: 'open-file' macOS
戻り値:
event
Eventpath
String
アプリケーションでファイルを開こうとしたときに出力します。アプリケーションがすでに起動し、OSがファイルを開くアプリケーションを再使用したいとき、open-file
イベントは出力します。ファイルがdockにドロップアウトされ、アプリケーションがまだ起動していないときにもopen-file
は出力します。このケースを処理するために、アプリケーションの起動のかなり早い段階で、open-file
イベントをリッスンして確認します(まだ ready
イベントが出力する前に)。
このイベントをハンドルしたいときには event.preventDefault()
をコールすべきです。
Windowsでは、ファイルパスを取得するために、 process.argv
をパースする必要があります。
イベント: 'open-url' macOS
戻り値:
event
Eventurl
String
アプリケーションでURLを開こうとしたときに出力されます。URLスキーマーは、アプリケーションが開くように登録しなければなりません。
このイベントをハンドルしたい場合は、event.preventDefault()
をコールすべきです。
イベント: 'activate' macOS
戻り値:
event
EventhasVisibleWindows
Boolean
アプリケーションがアクティブになったときに出力されます。通常は、アプリケーションのドックアイコンをクリックしたときに発生します。
イベント: 'browser-window-blur'
戻り値:
event
Eventwindow
BrowserWindow
browserWindow からフォーカスが外れたときに出力されます。
イベント: 'browser-window-focus'
戻り値:
event
Eventwindow
BrowserWindow
browserWindow にフォーカスが当たったとき出力されます。
イベント: 'browser-window-created'
戻り値:
event
Eventwindow
BrowserWindow
新しい browserWindow が作成されたときに出力されます。
イベント: 'certificate-error'
戻り値:
event
EventwebContents
WebContentsurl
URLerror
String - The error codecertificate
Objectdata
Buffer - PEM encoded dataissuerName
String
callback
Functionurl
のcertificate
検証に失敗したときに発生します。証明書を信頼するためにevent.preventDefault()
とcallback(true)
をコールして既定の動作を止める必要があります。
session.on('certificate-error', function (event, webContents, url, error, certificate, callback) {
if (url === 'https://github.com') {
// Verification logic.
event.preventDefault()
callback(true)
} else {
callback(false)
}
})
イベント: 'select-client-certificate'
戻り値:
event
EventwebContents
WebContentsurl
URLcertificateList
[Objects]data
Buffer - PEM encoded dataissuerName
String - Issuer's Common Name
callback
Function
クライアント証明書が要求されたときに出力されます。
url
は、クライアント証明書を要求するナビゲーションエントリーに対応し、callback
リストからエントリをフィルターしてコールするのに必要です。event.preventDefault()
を使用して、アプリケーションの証明書ストアから最初の証明書を使用するのを止めることができます。
app.on('select-client-certificate', function (event, webContents, url, list, callback) {
event.preventDefault()
callback(list[0])
})
イベント: 'login'
Returns:
event
EventwebContents
WebContentsrequest
Objectmethod
Stringurl
URLreferrer
URL
authInfo
ObjectisProxy
Booleanscheme
Stringhost
Stringport
Integerrealm
String
callback
Function
webContents
がベーシック認証をしようとしたときに出力されます。
既定の動作ではすべての認証をキャンセルしたり、event.preventDefault()
と callback(username, password)
とを証明書でコールし既定の動作をとめてオーバーライドします。
app.on('login', function (event, webContents, request, authInfo, callback) {
event.preventDefault()
callback('username', 'secret')
})
イベント: 'gpu-process-crashed'
gpu プロセスがクラッシュしたときに出力されます。
メソッド
app
オブジェクトは次のメソッドを持ちます。
Note: いくつかのメソッドは、特定のオペレーティングシステム向けに提供され、そのようにラベルで表示します。
app.quit()
全てのウィンドウを閉じようとします。before-quit
イベントは、最初に出力されます。すべてのウィンドウを閉じることに成功したら、will-quit
イベントが出力され、既定では、アプリケーションが終了します。
このメソッドは、全てのbeforeunload
とunload
イベントハンドラは正確に発生することを保証されます。beforeunload
イベントハンドラで、false
を返すことでウィンドウの終了をキャンセルすることができます。
app.exit(exitCode)
exitCode
Integer
exitCode
で今すぐ終了します。
全てのウィンドウは、ユーザーに確認することなく、すぐに閉じ、before-quit
とwill-quit
イベントは出力されません。
app.getAppPath()
減殺のアプリケーションディレクトリを戻します。
app.getPath(name)
name
String
name
に関連した特定のディレクトリやファイルへのパスを返します。失敗したら、Error
をスローします。
name
で次のパスをリクエストできます。
home
ユーザーのホームディレクトリappData
既定で示すユーザーごとのアプリケーションディレクトリ%APPDATA%
Windows上$XDG_CONFIG_HOME
or~/.config
Linux上~/Library/Application Support
macOS上
userData
アプリの設定ファイルを格納するディレクトリで、既定ではappData
ディレクトリ配下のアプリ名ディレクトリですtemp
一時ディレクトリexe
現在の実行ファイルmodule
libchromiumcontent
ライブラリdesktop
現在のユーザーのデスクトップディレクトリdocuments
ユーザーの "My Documents"用ディレクトリdownloads
ユーザーのダウンロード用ディレクトリmusic
ユーザーのミュージック用ディレクトリpictures
ユーザーのピクチャー用ディレクトリvideos
ユーザーのビデオ用ディレクトリ
app.setPath(name, path)
name
Stringpath
String
name
に関連した特定のディレクトリやファイルへのpath
を上書きします。存在しないパスを指定した場合、このメソッドがディレクトリを作成します。失敗したら、Error
をスローします。
app.getPath
で、name
で定義されたパスを上書きできます。
既定では、webページのクッキーとキャッシュはuserData
ディレクトリ配下に格納できます。ロケーションを変更したい場合、 app
モジュールの ready
イベントが出力される前にuserData
パスを上書きする必要があります。
app.getVersion()
ロードしたアプリケーションのバージョンを戻します。アプリケーションの package.json
ファイルにversionが無ければ、現在のバンドルまたは実行ファイルのバージョンになります。
app.getName()
現在のアプリケーション名を戻し、package.json
ファイルのnameです。
通常、 package.json
のname
フィールドは、短い小文字名で、npm module spec と一致します。通常、productName
で、アプリケーションの大文字正式名を指定し、Electronではname
をそれで上書きます。
app.getLocale()
現在のアプリケーションのロケールを戻します。
app.addRecentDocument(path)
macOS Windows
path
String
最近のドキュメント一覧にpath
を追加します。
この一覧はOSが管理しています。Windowsではタスクバーからこの一覧を見れ、macOSではdockメニューから見れます。
app.clearRecentDocuments()
macOS Windows
最近のドキュメント一覧をクリアします。
app.setUserTasks(tasks)
Windows
tasks
Array -Task
オブジェクトの配列
WindowsのジャンプリストのTasksカテゴリにtasks
を追加します。
tasks
はTask
オブジェクトの配列で、次のフォーマットになります。
Task
Object:
program
String - 実行するプログラムのパスで、通常はプログラムが開くprocess.execPath
を指定しますarguments
String -program
を実行するときのコマンドライン引数ですtitle
String - ジャンプリストに表示される文字列ですdescription
String - タスクの説明iconPath
String - ジャンプリストに表示するアイコンの絶対パスで、アイコンを含む任意のリソースファイルです。通常、プログラムのアイコンを表示するprocess.execPath
を指定します。iconIndex
Integer - アイコンファイルのアイコンインデックスです。アイコンファイルに2つ以上のアイコンが含まれている場合、この値でアイコンを指定します。1つしかアイコンファイルに含まれていない場合は、この値は0です。
app.allowNTLMCredentialsForAllDomains(allow)
allow
Boolean
HTTP NTLMまたはNegotiate認証用の照明を常に送信するかどうかを動的に設定できます。通常、Electronはローカルインターネットサイト(例えば、あなたと同じドメイン名のとき)に該当するURL用のNTLM/Kerberos証明書のみ送信します。しかし、この検知はコーポレートネットワークの設定が悪いときには、頻繁に失敗するので、この挙動を共通に行うことを選べば、全てのURLで有効にできます。
app.makeSingleInstance(callback)
callback
Function
このメソッドは、アプリケーションをシングルインスタンスアプリケーションにします。アプリの実行を複数のインスタンスで実行することを許可せず、アプリケーション実行をシングルインスタンスのみにすることを保証し、ほかのインスタンスにはこのインスタンスの存在を知らせ終了さえます。
2つ目のインスタンスが起動したとき、callback
は、callback(argv, workingDirectory)
でコールします。argv
は、2つ目のインスタンスのコマンドライン引数の配列で、workingDirectory
は現在のワーキングディレクトリです。通常、アプリケーションはメインのウィンドウにフォーカスをあて最小化させないことで対応します。
The callback
は、 app
のready
イベントの出力後に実行することを保証します。
プロセスがアプリケーションのプライマリインスタンスでアプリがロードし続けるなら、このメソッドは false
を戻します。プロセスがほかのインスタンスにパラメーターを送信し、true
を戻すと、直ちに終了します。
macOSは、ユーザーがFinderで2つ目のアプリインスタンスを開いたり、open-file
、 open-url
イベントが出力しようとすると、システムが自動的にシングルインスタンスを強制します。しかし、コマンドラインでアプリを開始するとシステムのシングルインスタンスメカニズムは無視されるので、シングルインスタンスを強制するためには、このメソッドを使う必要があります。
2つ目のインスタンスを起動するとき、メインのインスタンスのウィンドウをアクティブにする例
var myWindow = null
var shouldQuit = app.makeSingleInstance(function (commandLine, workingDirectory) {
// Someone tried to run a second instance, we should focus our window
if (myWindow) {
if (myWindow.isMinimized()) myWindow.restore()
myWindow.focus()
}
return true
})
if (shouldQuit) {
app.quit()
}
app.on('ready', function () {
// Create myWindow, load the rest of the app, etc...
})
app.setAppUserModelId(id)
Windows
id
String
Application User Model ID を id
に変更します。
app.isAeroGlassEnabled()
Windows
DWM composition(Aero Glass) が有効なら、このメソッドはtrue
を戻し、有効でなければfalse
を戻します。透明なウィンドウを作成する必要があるか、またはできないとき(DWM compositionが無効なとき用明なウィンドウは正しく動作しません)、このAPIを使うことができます。
使用例:
let browserOptions = {width: 1000, height: 800}
// Make the window transparent only if the platform supports it.
if (process.platform !== 'win32' || app.isAeroGlassEnabled()) {
browserOptions.transparent = true
browserOptions.frame = false
}
// Create the window.
win = new BrowserWindow(browserOptions)
// Navigate.
if (browserOptions.transparent) {
win.loadURL(`file://${__dirname}/index.html`)
} else {
// No transparency, so we load a fallback that uses basic styles.
win.loadURL(`file://${__dirname}/fallback.html`)
}
app.commandLine.appendSwitch(switch[, value])
Chromiumのコマンドラインにスイッチ( value
をオプションにし)を追加します。
Note: これは、process.argv
に影響せず、開発者が、Chromiumのローレベルな挙動をコントロールするのに使用します。
app.commandLine.appendArgument(value)
Chromiumのコマンドダインに引数を追加します。引数は正しく引用符で囲まれます。
Note: process.argv
に影響しません。
app.dock.bounce([type])
macOS
type
String (optional) -critical
またはinformational
を指定できます。既定では、informational
です。
critical
を渡すと、アプリケーションがアクティブ、もしくはリクエストがキャンセルされるまでは、dockアイコンは、バウンスします。
informational
を渡すと、1秒dockアイコンはバウンスします。しかし、アプリケーションがアクティブ、もしくはリクエストがキャンセルされるまでは、リクエストは残ります。
リクエストを示すIDを戻します。
app.dock.cancelBounce(id)
macOS
id
Integer
id
のバウンスをキャンセルします。
app.dock.setBadge(text)
macOS
text
String
dockのバッジエリアで表示する文字列を設定します。
app.dock.getBadge()
macOS
dockのバッジ文字列を戻します。
app.dock.hide()
macOS
dock アイコンを隠します。
app.dock.show()
macOS
dock アイコンを表示します。
app.dock.setMenu(menu)
macOS
menu
Menu
アプリケーションのdock menuを設定します。
app.dock.setIcon(image)
macOS
image
NativeImage
dock アイコンに紐づいたimage
を設定します。