Electron app 模塊

app 模塊是為了控制整個應(yīng)用的生命周期設(shè)計的。

下面的這個例子將會展示如何在最后一個窗口被關(guān)閉時退出應(yīng)用：

var app = require('app');
app.on('window-all-closed', function() {
  app.quit();
});

事件列表

app 對象會觸發(fā)以下的事件：

事件：'will-finish-launching'

當(dāng)應(yīng)用程序完成基礎(chǔ)的啟動的時候被觸發(fā)。在 Windows 和 Linux 中， will-finish-launching 事件與 ready 事件是相同的； 在 OS X 中， 這個時間相當(dāng)于 NSApplication 中的 applicationWillFinishLaunching 提示。 你應(yīng)該經(jīng)常在這里為 open-file 和 open-url 設(shè)置監(jiān)聽器，并啟動崩潰報告和自動更新。

在大多數(shù)的情況下，你應(yīng)該只在 ready 事件處理器中完成所有的業(yè)務(wù)。

事件：'ready'

當(dāng) Electron 完成初始化時被觸發(fā)。

事件：'window-all-closed'

當(dāng)所有的窗口都被關(guān)閉時觸發(fā)。

這個時間僅在應(yīng)用還沒有退出時才能觸發(fā)。 如果用戶按下了 Cmd + Q， 或者開發(fā)者調(diào)用了 app.quit() ，Electron 將會先嘗試關(guān)閉所有的窗口再觸發(fā) will-quit 事件， 在這種情況下 window-all-closed 不會被觸發(fā)。

事件：'before-quit'

返回：

• event Event

在應(yīng)用程序開始關(guān)閉它的窗口的時候被觸發(fā)。 調(diào)用 event.preventDefault() 將會阻止終止應(yīng)用程序的默認(rèn)行為。

事件：'will-quit'

返回：

• event Event

當(dāng)所有的窗口已經(jīng)被關(guān)閉，應(yīng)用即將退出時被觸發(fā)。 調(diào)用 event.preventDefault() 將會阻止終止應(yīng)用程序的默認(rèn)行為。

你可以在 window-all-closed 事件的描述中看到 will-quit 事件 和 window-all-closed 事件的區(qū)別。

事件：'quit'

返回：

• event Event
• exitCode Integer

當(dāng)應(yīng)用程序正在退出時觸發(fā)。

事件：'open-file' OS X

返回：

• event Event
• path String

當(dāng)用戶想要在應(yīng)用中打開一個文件時觸發(fā)。open-file 事件常常在應(yīng)用已經(jīng)打開并且系統(tǒng)想要再次使用應(yīng)用打開文件時被觸發(fā)。 open-file 也會在一個文件被拖入 dock 且應(yīng)用還沒有運(yùn)行的時候被觸發(fā)。 請確認(rèn)在應(yīng)用啟動的時候（甚至在 ready 事件被觸發(fā)前）就對 open-file 事件進(jìn)行監(jiān)聽，以處理這種情況。

如果你想處理這個事件，你應(yīng)該調(diào)用 event.preventDefault() 。 在 Windows系統(tǒng)中，你需要通過解析 process.argv 來獲取文件路徑。

事件：'open-url' OS X

返回：

• event Event
• url String

當(dāng)用戶想要在應(yīng)用中打開一個url的時候被觸發(fā)。URL格式必須要提前標(biāo)識才能被你的應(yīng)用打開。

如果你想處理這個事件，你應(yīng)該調(diào)用 event.preventDefault() 。

事件：'activate' OS X

返回：

• event Event
• hasVisibleWindows Boolean

當(dāng)應(yīng)用被激活時觸發(fā)，常用于點(diǎn)擊應(yīng)用的 dock 圖標(biāo)的時候。

事件：'browser-window-blur'

返回：

• event Event
• window BrowserWindow

當(dāng)一個 BrowserWindow 失去焦點(diǎn)的時候觸發(fā)。

事件：'browser-window-focus'

返回：

• event Event
• window BrowserWindow

當(dāng)一個 BrowserWindow 獲得焦點(diǎn)的時候觸發(fā)。

事件：'browser-window-created'

返回：

• event Event
• window BrowserWindow

當(dāng)一個 BrowserWindow 被創(chuàng)建的時候觸發(fā)。

事件：'certificate-error'

返回：

• event Event
• webContents WebContents
• url String - URL 地址
• error String - 錯誤碼
• certificate Object
• data Buffer - PEM 編碼數(shù)據(jù)
• issuerName String - 發(fā)行者的公有名稱
• callback Function

當(dāng)對 url 驗證 certificate 證書失敗的時候觸發(fā)，如果需要信任這個證書，你需要阻止默認(rèn)行為 event.preventDefault() 并且 調(diào)用 callback(true)。

session.on('certificate-error', function(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 String - URL 地址
• certificateList [Object]
• data Buffer - PEM 編碼數(shù)據(jù)
• issuerName String - 發(fā)行者的公有名稱
• callback Function

當(dāng)一個客戶端認(rèn)證被請求的時候被觸發(fā)。

url 指的是請求客戶端認(rèn)證的網(wǎng)頁地址，調(diào)用 callback 時需要傳入一個證書列表中的證書。

需要通過調(diào)用 event.preventDefault() 來防止應(yīng)用自動使用第一個證書進(jìn)行驗證。如下所示：

app.on('select-certificate', function(event, host, url, list, callback) {
  event.preventDefault();
  callback(list[0]);
})

事件: 'login'

返回：

• event Event
• webContents WebContents
• request Object
  • method String
  • url URL
  • referrer URL
• authInfo Object
  • isProxy Boolean
  • scheme String
  • host String
  • port Integer
  • realm String
• callback Function

當(dāng) webContents 要做進(jìn)行一次 HTTP 登陸驗證時被觸發(fā)。

默認(rèn)情況下，Electron 會取消所有的驗證行為，如果需要重寫這個行為，你需要用 event.preventDefault() 來阻止默認(rèn)行為，并且 用 callback(username, password) 來進(jìn)行驗證。

app.on('login', function(event, webContents, request, authInfo, callback) {
  event.preventDefault();
  callback('username', 'secret');
})

事件：'gpu-process-crashed'

當(dāng) GPU 進(jìn)程崩潰時觸發(fā)。

方法列表

app 對象擁有以下的方法：

請注意 有的方法只能用于特定的操作系統(tǒng)。

app.quit()

試圖關(guān)掉所有的窗口。before-quit 事件將會最先被觸發(fā)。如果所有的窗口都被成功關(guān)閉了， will-quit事件將會被觸發(fā)，默認(rèn)下應(yīng)用將會被關(guān)閉。

這個方法保證了所有的 beforeunload 和 unload 事件處理器被正確執(zhí)行。假如一個窗口的 beforeunload事件處理器返回 false，那么整個應(yīng)用可能會取消退出。

app.hide() OS X

隱藏所有的應(yīng)用窗口，不是最小化.

app.show() OS X

隱藏后重新顯示所有的窗口，不會自動選中他們。

app.exit(exitCode)

• exitCode 整數(shù)

帶著exitCode退出應(yīng)用.

所有的窗口會被立刻關(guān)閉，不會詢問用戶。before-quit 和 will-quit 這2個事件不會被觸發(fā)

app.getAppPath()

返回當(dāng)前應(yīng)用所在的文件路徑。

app.getPath(name)

• name String

返回一個與 name 參數(shù)相關(guān)的特殊文件夾或文件路徑。當(dāng)失敗時拋出一個 Error 。

你可以通過名稱請求以下的路徑：

• home 用戶的 home 文件夾（主目錄）
• appData 當(dāng)前用戶的應(yīng)用數(shù)據(jù)文件夾，默認(rèn)對應(yīng)：
  • %APPDATA% Windows 中
  • $XDG_CONFIG_HOME or ~/.config Linux 中
  • ~/Library/Application Support OS X 中
• userData 儲存你應(yīng)用程序設(shè)置文件的文件夾，默認(rèn)是 appData 文件夾附加應(yīng)用的名稱
• temp 臨時文件夾
• exe 當(dāng)前的可執(zhí)行文件
• module libchromiumcontent 庫
• desktop 當(dāng)前用戶的桌面文件夾
• documents 用戶文檔目錄的路徑
• downloads 用戶下載目錄的路徑.
• music 用戶音樂目錄的路徑.
• pictures 用戶圖片目錄的路徑.
• videos 用戶視頻目錄的路徑.

app.setPath(name, path)

• name String
• path String

重寫某個 name 的路徑為 path，path 可以是一個文件夾或者一個文件，這個和 name 的類型有關(guān)。 如果這個路徑指向的文件夾不存在，這個文件夾將會被這個方法創(chuàng)建。 如果錯誤則會拋出 Error。

name 參數(shù)只能使用 app.getPath 中定義過 name。

默認(rèn)情況下，網(wǎng)頁的 cookie 和緩存都會儲存在 userData 文件夾。 如果你想要改變這個位置，你需要在 app 模塊中的 ready 事件被觸發(fā)之前重寫 userData 的路徑。

app.getVersion()

返回加載應(yīng)用程序的版本。如果應(yīng)用程序的 package.json 文件中沒有寫版本號， 將會返回當(dāng)前包或者可執(zhí)行文件的版本。

app.getName()

返回當(dāng)前應(yīng)用程序的 package.json 文件中的名稱。

由于 npm 的命名規(guī)則，通常 name 字段是一個短的小寫字符串。但是應(yīng)用名的完整名稱通常是首字母大寫的，你應(yīng)該單獨(dú)使用一個 productName 字段，用于表示你的應(yīng)用程序的完整名稱。Electron 會優(yōu)先使用這個字段作為應(yīng)用名。

app.setName(name)

• name String

重寫當(dāng)前應(yīng)用的名字

app.getLocale()

返回當(dāng)前應(yīng)用程序的語言。

app.addRecentDocument(path) OS X Windows

• path String

在最近訪問的文檔列表中添加 path。

這個列表由操作系統(tǒng)進(jìn)行管理。在 Windows 中您可以通過任務(wù)條進(jìn)行訪問，在 OS X 中你可以通過 dock 菜單進(jìn)行訪問。

app.clearRecentDocuments() OS X Windows

清除最近訪問的文檔列表。

app.setUserTasks(tasks) Windows

• tasks [Task] - 一個由 Task 對象構(gòu)成的數(shù)組

將 tasks 添加到 Windows 中 JumpList 功能的 Tasks 分類中。

tasks 中的 Task 對象格式如下：

Task Object

• program String - 執(zhí)行程序的路徑，通常你應(yīng)該說明當(dāng)前程序的路徑為 process.execPath 字段。
• arguments String - 當(dāng) program 執(zhí)行時的命令行參數(shù)。
• title String - JumpList 中顯示的標(biāo)題。
• description String - 對這個任務(wù)的描述。
• iconPath String - JumpList 中顯示的圖標(biāo)的絕對路徑，可以是一個任意包含一個圖標(biāo)的資源文件。通常來說，你可以通過指明 process.execPath 來顯示程序中的圖標(biāo)。
• iconIndex Integer - 圖標(biāo)文件中的采用的圖標(biāo)位置。如果一個圖標(biāo)文件包括了多個圖標(biāo)，就需要設(shè)置這個值以確定使用的是哪一個圖標(biāo)。 如果這個圖標(biāo)文件中只包含一個圖標(biāo)，那么這個值為 0。

app.allowNTLMCredentialsForAllDomains(allow)

• allow Boolean

動態(tài)設(shè)置是否總是為 HTTP NTLM 或 Negotiate 認(rèn)證發(fā)送證書。通常來說，Electron 只會對本地網(wǎng)絡(luò)（比如和你處在一個域中的計算機(jī)）發(fā) 送 NTLM / Kerberos 證書。但是假如網(wǎng)絡(luò)設(shè)置得不太好，可能這個自動探測會失效，所以你可以通過這個接口自定義 Electron 對所有 URL 的行為。

app.makeSingleInstance(callback)

• callback Function

這個方法可以讓你的應(yīng)用在同一時刻最多只會有一個實(shí)例，否則你的應(yīng)用可以被運(yùn)行多次并產(chǎn)生多個實(shí)例。你可以利用這個接口保證只有一個實(shí)例正 常運(yùn)行，其余的實(shí)例全部會被終止并退出。

如果多個實(shí)例同時運(yùn)行，那么第一個被運(yùn)行的實(shí)例中 callback 會以 callback(argv, workingDirectory)的形式被調(diào)用。其余的實(shí)例 會被終止。 argv 是一個包含了這個實(shí)例的命令行參數(shù)列表的數(shù)組，workingDirectory 是這個實(shí)例目前的運(yùn)行目錄。通常來說，我們會用通過將應(yīng)用在 主屏幕上激活，并且取消最小化，來提醒用戶這個應(yīng)用已經(jīng)被打開了。

在 app 的 ready 事件后，callback 才有可能被調(diào)用。

如果當(dāng)前實(shí)例為第一個實(shí)例，那么在這個方法將會返回 false 來保證它繼續(xù)運(yùn)行。否則將會返回 true 來讓它立刻退出。

在 OS X 中，如果用戶通過 Finder、open-file 或者 open-url 打開應(yīng)用，系統(tǒng)會強(qiáng)制確保只有一個實(shí)例在運(yùn)行。但是如果用戶是通過 命令行打開，這個系統(tǒng)機(jī)制會被忽略，所以你仍然需要靠這個方法來保證應(yīng)用為單實(shí)例運(yùn)行的。

下面是一個簡單的例子。我們可以通過這個例子了解如何確保應(yīng)用為單實(shí)例運(yùn)行狀態(tài)。

var myWindow = null;

var shouldQuit = app.makeSingleInstance(function(commandLine, workingDirectory) {
  // 當(dāng)另一個實(shí)例運(yùn)行的時候，這里將會被調(diào)用，我們需要激活應(yīng)用的窗口
  if (myWindow) {
    if (myWindow.isMinimized()) myWindow.restore();
    myWindow.focus();
  }
  return true;
});

// 這個實(shí)例是多余的實(shí)例，需要退出
if (shouldQuit) {
  app.quit();
  return;
}

// 創(chuàng)建窗口、繼續(xù)加載應(yīng)用、應(yīng)用邏輯等……
app.on('ready', function() {
});

app.setAppUserModelId(id) Windows

• id String

改變當(dāng)前應(yīng)用的 Application User Model ID 為 id.

app.isAeroGlassEnabled() Windows

如果 DWM composition(Aero Glass) 啟用 了，那么這個方法會返回 true，否則是 false。你可以用這個方法來決定是否要開啟透明窗口特效，因為如果用戶沒開啟 DWM，那么透明窗 口特效是無效的。

舉個例子：

let browserOptions = {width: 1000, height: 800};

// 只有平臺支持的時候才使用透明窗口
if (process.platform !== 'win32' || app.isAeroGlassEnabled()) {
  browserOptions.transparent = true;
  browserOptions.frame = false;
}

// 創(chuàng)建窗口
win = new BrowserWindow(browserOptions);

// 轉(zhuǎn)到某個網(wǎng)頁
if (browserOptions.transparent) {
  win.loadURL('file://' + __dirname + '/index.html');
} else {
  // 沒有透明特效，我們應(yīng)該用某個只包含基本樣式的替代解決方案。
  win.loadURL('file://' + __dirname + '/fallback.html');
}

app.commandLine.appendSwitch(switch[, value])

通過可選的參數(shù) value 給 Chromium 中添加一個命令行開關(guān)。

注意 這個方法不會影響 process.argv，我們通常用這個方法控制一些底層 Chromium 行為。

app.commandLine.appendArgument(value)

給 Chromium 中直接添加一個命令行參數(shù)，這個參數(shù) value 的引號和格式必須正確。

注意 這個方法不會影響 process.argv。

app.dock.bounce([type]) OS X

• type String - 可選參數(shù)，可以是 critical 或 informational。默認(rèn)為 informational。

當(dāng)傳入的是 critical 時，dock 中的應(yīng)用將會開始彈跳，直到這個應(yīng)用被激活或者這個請求被取消。

當(dāng)傳入的是 informational 時，dock 中的圖標(biāo)只會彈跳一秒鐘。但是，這個請求仍然會激活，直到應(yīng)用被激活或者請求被取消。

這個方法返回的返回值表示這個請求的 ID。

app.dock.cancelBounce(id) OS X

• id Integer

取消這個 id 對應(yīng)的請求。

app.dock.setBadge(text) OS X

• text String

設(shè)置應(yīng)用在 dock 中顯示的字符串。

app.dock.getBadge() OS X

返回應(yīng)用在 dock 中顯示的字符串。

app.dock.hide() OS X

隱藏應(yīng)用在 dock 中的圖標(biāo)。

app.dock.show() OS X

顯示應(yīng)用在 dock 中的圖標(biāo)。

app.dock.setMenu(menu) OS X

• menu Menu

設(shè)置應(yīng)用的 dock 菜單.

app.dock.setIcon(image) OS X

• image NativeImage

設(shè)置應(yīng)用在 dock 中顯示的圖標(biāo)。