Electron app 模塊

2019-08-14 19:21 更新

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

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

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

事件列表

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

事件：'will-finish-launching'

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

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

事件：'ready'

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

事件：'window-all-closed'

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

這個(gè)時(shí)間僅在應(yīng)用還沒有退出時(shí)才能觸發(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)閉它的窗口的時(shí)候被觸發(fā)。 調(diào)用 event.preventDefault() 將會阻止終止應(yīng)用程序的默認(rèn)行為。

事件：'will-quit'

返回：

  • event Event

當(dāng)所有的窗口已經(jīng)被關(guān)閉，應(yīng)用即將退出時(shí)被觸發(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)用程序正在退出時(shí)觸發(fā)。

事件：'open-file' OS X

返回：

  • event Event
  • path String

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

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

事件：'open-url' OS X

返回：

  • event Event
  • url String

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

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

事件：'activate' OS X

返回：

  • event Event
  • hasVisibleWindows Boolean

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

事件：'browser-window-blur'

返回：

  • event Event
  • window BrowserWindow

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

事件：'browser-window-focus'

返回：

  • event Event
  • window BrowserWindow

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

事件：'browser-window-created'

返回：

  • event Event
  • window BrowserWindow

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

事件：'certificate-error'

返回：

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

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

session.on('certificate-error', function(event, webContents, url, error, certificate, callback) {
  if (url == "https://github.com") {
    // 驗(yàn)證邏輯。
    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)一個(gè)客戶端認(rèn)證被請求的時(shí)候被觸發(fā)。

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

需要通過調(diào)用 event.preventDefault() 來防止應(yīng)用自動(dòng)使用第一個(gè)證書進(jìn)行驗(yà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 登陸驗(yàn)證時(shí)被觸發(fā)。

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

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

事件：'gpu-process-crashed'

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

方法列表

app 對象擁有以下的方法：

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

app.quit()

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

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

app.hide() OS X

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

app.show() OS X

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

app.exit(exitCode)

  • exitCode 整數(shù)

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

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

app.getAppPath()

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

app.getPath(name)

  • name String

返回一個(gè)與 name 參數(shù)相關(guān)的特殊文件夾或文件路徑。當(dāng)失敗時(shí)拋出一個(gè) 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 臨時(shí)文件夾
  • exe 當(dāng)前的可執(zhí)行文件
  • module libchromiumcontent 庫
  • desktop 當(dāng)前用戶的桌面文件夾
  • documents 用戶文檔目錄的路徑
  • downloads 用戶下載目錄的路徑.
  • music 用戶音樂目錄的路徑.
  • pictures 用戶圖片目錄的路徑.
  • videos 用戶視頻目錄的路徑.

app.setPath(name, path)

  • name String
  • path String

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

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

默認(rèn)情況下，網(wǎng)頁的 cookie 和緩存都會儲存在 userData 文件夾。 如果你想要改變這個(gè)位置，你需要在 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 字段是一個(gè)短的小寫字符串。但是應(yīng)用名的完整名稱通常是首字母大寫的，你應(yīng)該單獨(dú)使用一個(gè) productName 字段，用于表示你的應(yīng)用程序的完整名稱。Electron 會優(yōu)先使用這個(gè)字段作為應(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。

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

app.clearRecentDocuments() OS X Windows

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

app.setUserTasks(tasks) Windows

  • tasks [Task] - 一個(gè)由 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í)的命令行參數(shù)。
  • title String - JumpList 中顯示的標(biāo)題。
  • description String - 對這個(gè)任務(wù)的描述。
  • iconPath String - JumpList 中顯示的圖標(biāo)的絕對路徑，可以是一個(gè)任意包含一個(gè)圖標(biāo)的資源文件。通常來說，你可以通過指明 process.execPath 來顯示程序中的圖標(biāo)。
  • iconIndex Integer - 圖標(biāo)文件中的采用的圖標(biāo)位置。如果一個(gè)圖標(biāo)文件包括了多個(gè)圖標(biāo)，就需要設(shè)置這個(gè)值以確定使用的是哪一個(gè)圖標(biāo)。 如果這個(gè)圖標(biāo)文件中只包含一個(gè)圖標(biāo)，那么這個(gè)值為 0。

app.allowNTLMCredentialsForAllDomains(allow)

  • allow Boolean

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

app.makeSingleInstance(callback)

  • callback Function

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

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

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

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

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

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

var myWindow = null;

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

// 這個(gè)實(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) 啟用 了，那么這個(gè)方法會返回 true，否則是 false。你可以用這個(gè)方法來決定是否要開啟透明窗口特效，因?yàn)槿绻脩魶]開啟 DWM，那么透明窗 口特效是無效的。

舉個(gè)例子：

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

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

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

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

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

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

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

app.commandLine.appendArgument(value)

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

注意 這個(gè)方法不會影響 process.argv。

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

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

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

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

這個(gè)方法返回的返回值表示這個(gè)請求的 ID。

app.dock.cancelBounce(id) OS X

  • id Integer

取消這個(gè) 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

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

app.dock.setIcon(image) OS X

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

以上內(nèi)容是否對您有幫助：
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號
微信公眾號

編程獅公眾號