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 事件
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.preventDefault() 將會防止預設行為，也就是終止應用程式。

注意： 如果應用程式結束是由 autoUpdater.quitAndInstall() 啟動的，則會在所有視窗上發出 close 事件並關閉它們之後發出 before-quit。

注意： 在 Windows 上，如果應用程式因系統關機/重新啟動或使用者登出而關閉，則不會發出此事件。

事件：'will-quit'

回傳

event 事件

當所有視窗都已關閉，且應用程式將要結束時發出。呼叫 event.preventDefault() 將會防止預設行為，也就是終止應用程式。

如需 will-quit 和 window-all-closed 事件之間差異的說明，請參閱 window-all-closed 事件的描述。

注意： 在 Windows 上，如果應用程式因系統關機/重新啟動或使用者登出而關閉，則不會發出此事件。

事件：'quit'

回傳

event 事件
exitCode 整數

當應用程式正在結束時發出。

注意： 在 Windows 上，如果應用程式因系統關機/重新啟動或使用者登出而關閉，則不會發出此事件。

事件：'open-file' macOS

回傳

event 事件
path 字串

當使用者想要使用應用程式開啟檔案時發出。當應用程式已開啟且作業系統想要重複使用應用程式來開啟檔案時，通常會發出 open-file 事件。當檔案被拖放到 Dock 上且應用程式尚未執行時，也會發出 open-file。請確保在應用程式啟動的早期偵聽 open-file 事件，以處理這種情況（甚至在發出 ready 事件之前）。

如果您想要處理此事件，則應呼叫 event.preventDefault()。

在 Windows 上，您必須剖析 process.argv (在主程序中) 以取得檔案路徑。

事件：'open-url' macOS

回傳

event 事件
url 字串

當使用者想要使用應用程式開啟 URL 時發出。您的應用程式的 Info.plist 檔案必須在 CFBundleURLTypes 金鑰內定義 URL 配置，並將 NSPrincipalClass 設定為 AtomApplication。

與 open-file 事件一樣，請務必在應用程式啟動的早期註冊 open-url 事件的監聽器，以偵測應用程式是否正在開啟以處理 URL。如果您在回應 ready 事件時註冊監聽器，您將會錯過觸發應用程式啟動的 URL。

事件：'activate' macOS

回傳

event 事件
hasVisibleWindows 布林值

當應用程式啟動時發出。各種動作可能會觸發此事件，例如第一次啟動應用程式、嘗試在應用程式已在執行時重新啟動應用程式，或按一下應用程式的 Dock 或工作列圖示。

事件：'did-become-active' macOS

回傳

event 事件

當應用程式變成啟用狀態時發出。這與 activate 事件的不同之處在於，did-become-active 會在應用程式每次變成啟用狀態時發出，而不僅僅是在按一下 Dock 圖示或重新啟動應用程式時發出。當使用者透過 macOS 應用程式切換器切換至應用程式時，也會發出此事件。

事件：'did-resign-active' macOS

回傳

event 事件

當應用程式不再啟用且沒有焦點時發出。例如，按一下另一個應用程式或使用 macOS 應用程式切換器切換到另一個應用程式，可能會觸發此事件。

事件：'continue-activity' macOS

回傳

event 事件
type 字串 - 識別活動的字串。對應至 NSUserActivity.activityType。
userInfo 未知 - 包含由其他裝置上的活動儲存的應用程式特定狀態。
details 物件
- webpageURL 字串（選用） - 識別其他裝置上的活動所存取網頁 URL 的字串（如果有的話）。

當來自不同裝置的活動想要恢復時，在 Handoff 期間發出。如果您想要處理此事件，則應呼叫 event.preventDefault()。

使用者活動只能在具有與活動來源應用程式相同的開發人員團隊 ID，且支援活動類型的應用程式中繼續。支援的活動類型是在應用程式的 Info.plist 中，在 NSUserActivityTypes 金鑰下指定的。

事件：'will-continue-activity' macOS

回傳

event 事件
type 字串 - 識別活動的字串。對應至 NSUserActivity.activityType。

當來自不同裝置的活動想要恢復之前，在 Handoff 期間發出。如果您想要處理此事件，則應呼叫 event.preventDefault()。

事件：'continue-activity-error' macOS

回傳

event 事件
type 字串 - 識別活動的字串。對應至 NSUserActivity.activityType。
error 字串 - 包含錯誤本地化描述的字串。

當來自不同裝置的活動無法恢復時，在 Handoff 期間發出。

事件：'activity-was-continued' macOS

回傳

event 事件
type 字串 - 識別活動的字串。對應至 NSUserActivity.activityType。
userInfo 未知 - 包含由活動儲存的應用程式特定狀態。

在接力 (Handoff) 功能中，當此裝置上的活動成功在其他裝置上恢復後發出。

事件：'update-activity-state' macOS

回傳

event 事件
type 字串 - 識別活動的字串。對應至 NSUserActivity.activityType。
userInfo 未知 - 包含由活動儲存的應用程式特定狀態。

當接力 (Handoff) 即將在其他裝置上恢復時發出。如果您需要更新要傳輸的狀態，您應該立即呼叫 event.preventDefault()，建構一個新的 userInfo 字典，並及時呼叫 app.updateCurrentActivity()。否則，操作將會失敗，並會呼叫 continue-activity-error。

事件：'new-window-for-tab' macOS

回傳

event 事件

當使用者點擊 macOS 原生的新分頁按鈕時發出。只有在目前的 BrowserWindow 具有 tabbingIdentifier 時，才會顯示新分頁按鈕。

事件：'browser-window-blur'

回傳

event 事件
window BrowserWindow

當 browserWindow 失去焦點時發出。

事件：'browser-window-focus'

回傳

event 事件
window BrowserWindow

當 browserWindow 取得焦點時發出。

事件：'browser-window-created'

回傳

event 事件
window BrowserWindow

當建立新的 browserWindow 時發出。

事件：'web-contents-created'

回傳

event 事件
webContents WebContents

當建立新的 webContents 時發出。

事件：'certificate-error'

回傳

event 事件
webContents WebContents
url 字串
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') {
    // Verification logic.
    event.preventDefault()
    callback(true)
  } else {
    callback(false)
  }
})

事件：'select-client-certificate'

回傳

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])
})

回傳

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

當 webContents 或工具程序想要執行基本驗證時發出。

預設行為是取消所有驗證。若要覆寫此行為，您應該使用 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 事件
webContents WebContents
details RenderProcessGoneDetails

當渲染程序意外消失時發出。這通常是因為它崩潰或被終止。

事件：'child-process-gone'

回傳

event 事件
details 物件
- 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 - 程序的結束代碼（例如，如果是在 POSIX 上，則為 waitpid 的狀態；在 Windows 上，則為 GetExitCodeProcess）。
- serviceName string (選用) - 程序的非本地化名稱。
- name string (選用) - 程序的名稱。工具程式的範例：Audio Service、Content Decryption Module Service、Network Service、Video Capture 等。

當子程序意外消失時發出。這通常是因為它崩潰或被終止。它不包含渲染程序。

事件：'accessibility-support-changed' macOS Windows

回傳

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 事件
argv string[] - 第二個執行個體的命令列引數陣列
workingDirectory string - 第二個執行個體的工作目錄
additionalData unknown - 從第二個執行個體傳遞的額外資料 JSON 物件

當第二個執行個體已執行並呼叫 app.requestSingleInstanceLock() 時，此事件將會在您的應用程式的主要執行個體內發出。

argv 是第二個執行個體的命令列引數陣列，而 workingDirectory 是其目前的工作目錄。應用程式通常會藉由讓其主要視窗取得焦點且不縮小來回應此事件。

注意：argv 不會與傳遞給第二個執行個體的引數清單完全相同。順序可能會變更，而且可能會附加其他引數。如果您需要維護完全相同的引數，建議您改用 additionalData。

注意：如果第二個執行個體是由與第一個執行個體不同的使用者啟動，則 argv 陣列不會包含引數。

保證會在發出 app 的 ready 事件後發出此事件。

注意： Chromium 可能會新增額外的命令列引數，例如 --original-process-start-time。

方法

app 物件具有下列方法

注意：某些方法僅在特定作業系統上可用，並已標示為此。

`app.quit()`

嘗試關閉所有視窗。會先發出 before-quit 事件。如果所有視窗都成功關閉，則會發出 will-quit 事件，且依預設，應用程式將會終止。

此方法保證所有 beforeunload 和 unload 事件處理常式都會正確執行。視窗可能會藉由在 beforeunload 事件處理常式中傳回 false 來取消關閉。

`app.exit([exitCode])`

exitCode Integer (選用)

立即以 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()`

返回 Promise<void> - 當 Electron 初始化完成時會 fulfilled。如果應用程式尚未就緒，它可以作為檢查 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/YourAppName，在 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 用於儲存 Session 產生的資料的目錄，例如 localStorage、cookie、磁碟快取、下載的字典、網路狀態、devtools 檔案。預設情況下，此目錄指向 userData。Chromium 可能會在此處寫入非常大的磁碟快取，因此如果您的應用程式不依賴像 localStorage 或 cookie 之類的瀏覽器儲存來儲存使用者資料，建議將此目錄設定到其他位置，以避免污染 userData 目錄。
- temp 暫存目錄。
- exe 目前的可執行檔。
- module libchromiumcontent 程式庫。
- desktop 目前使用者的桌面目錄。
- documents 使用者「我的文件」的目錄。
- downloads 使用者的下載目錄。
- music 使用者的音樂目錄。
- pictures 使用者的圖片目錄。
- videos 使用者的影片目錄。
- recent 使用者最近使用的檔案目錄 (僅限 Windows)。
- logs 您的應用程式日誌資料夾的目錄。
- crashDumps 儲存當機傾印的目錄。

返回 string - 與 name 關聯的特殊目錄或檔案的路徑。如果失敗，則會拋出 Error。

如果先呼叫 app.getPath('logs') 而沒有先呼叫 app.setAppLogsPath()，則會建立一個預設的日誌目錄，等同於在沒有 path 參數的情況下呼叫 app.setAppLogsPath()。

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

path 字串
options Object (選用)
- size string
  - small - 16x16
  - normal - 32x32
  - large - 在 Linux 上為 48x48，在 Windows 上為 32x32，在 macOS 上不支援。

返回 Promise<NativeImage> - 以應用程式圖示 fulfilled，它是一個 NativeImage。

擷取與路徑關聯的圖示。

在 Windows 上，有 2 種圖示

與某些檔案副檔名關聯的圖示，例如 .mp3、.png 等。
檔案本身的圖示，例如 .exe、.dll、.ico。

在 Linux 和 macOS 上，圖示取決於與檔案 MIME 類型關聯的應用程式。

`app.setPath(name, path)`

name string
path 字串

覆寫與 name 關聯的特殊目錄或檔案的 path。如果路徑指定的目錄不存在，則會拋出 Error。在這種情況下，應使用 fs.mkdirSync 或類似的方法建立目錄。

您只能覆寫在 app.getPath 中定義的 name 的路徑。

預設情況下，網頁的 cookie 和快取將儲存在 sessionData 目錄下。如果您想變更此位置，則必須在發出 app 模組的 ready 事件之前覆寫 sessionData 路徑。

`app.getVersion()`

返回 string - 已載入應用程式的版本。如果在應用程式的 package.json 檔案中找不到版本，則會返回目前套件或可執行檔的版本。

`app.getName()`

返回 string - 目前應用程式的名稱，它是應用程式的 package.json 檔案中的名稱。

通常，根據 npm 模組規範，package.json 的 name 欄位是簡短的小寫名稱。您通常也應該指定一個 productName 欄位，它是您的應用程式的完整大寫名稱，並且 Electron 將優先於 name 使用它。

`app.setName(name)`

name string

覆寫目前應用程式的名稱。

注意：此函式會覆寫 Electron 內部使用的名稱；它不會影響作業系統使用的名稱。

`app.getLocale()`

返回 string - 目前應用程式的語言環境，使用 Chromium 的 l10n_util 程式庫擷取。可能的返回值記錄在此處。

若要設定語言環境，您需要在應用程式啟動時使用命令列開關，可以在此處找到。

注意：當您發布打包的應用程式時，您還必須運送 locales 資料夾。

注意：此 API 必須在發出 ready 事件後呼叫。

注意：若要查看此 API 與其他語言環境和語言 API 比較的返回值的範例，請參閱app.getPreferredSystemLanguages()。

`app.getLocaleCountryCode()`

返回 string - 使用者作業系統的語言環境的雙字母 ISO 3166 國家/地區代碼。該值取自原生 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 上透過「語言與地區」設定修改和新增此清單。

API 在 Windows 上使用 GlobalizationPreferences（並回退到 GetSystemPreferredUILanguages），在 macOS 上使用 [NSLocale preferredLanguages]，在 Linux 上使用 g_get_language_names。

此 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']

這兩個作業系統之間的可用語言和地區以及可能的返回值都不同。

如以上範例所示，在 Windows 上，偏好的系統語言可能沒有國家/地區代碼，並且其中一種偏好的系統語言與用於地區格式的語言對應。在 macOS 上，地區更像是預設的國家/地區代碼：使用者不需要將芬蘭語設為偏好語言即可使用芬蘭作為地區，並且 FI 國家/地區代碼會用作語言名稱中沒有關聯國家/地區的偏好系統語言的國家/地區代碼。

`app.addRecentDocument(path)` macOS Windows

path 字串

將 path 新增至最近使用的文件清單。

此清單由作業系統管理。在 Windows 上，您可以從工作列存取該清單，在 macOS 上，您可以從 Dock 選單存取該清單。

`app.clearRecentDocuments()` macOS Windows

清除最近的文件列表。

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

protocol 字串 - 您的協定名稱，不包含 ://。例如，如果您希望您的應用程式處理 electron:// 連結，請使用 electron 作為參數呼叫此方法。
path 字串 (選用) Windows - Electron 可執行檔的路徑。預設為 process.execPath。
args 字串陣列 (選用) Windows - 傳遞給可執行檔的參數。預設為空陣列。

傳回 boolean - 呼叫是否成功。

將目前的可執行檔設定為協定（又稱 URI 方案）的預設處理常式。它允許您將您的應用程式更深入地整合到作業系統中。註冊後，所有具有 your-protocol:// 的連結都將使用目前的可執行檔開啟。整個連結，包括協定，將作為參數傳遞給您的應用程式。

注意： 在 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 字串 - 您的協定名稱，不包含 ://。
path 字串 (選用) Windows - 預設為 process.execPath。
args 字串陣列 (選用) Windows - 預設為空陣列。

傳回 boolean - 呼叫是否成功。

此方法檢查目前的可執行檔是否為協定（又稱 URI 方案）的預設處理常式。如果是，它將移除該應用程式作為預設處理常式。

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

protocol 字串 - 您的協定名稱，不包含 ://。
path 字串 (選用) Windows - 預設為 process.execPath。
args 字串陣列 (選用) Windows - 預設為空陣列。

傳回 boolean - 目前的可執行檔是否為協定（又稱 URI 方案）的預設處理常式。

注意： 在 macOS 上，您可以使用此方法來檢查應用程式是否已註冊為協定的預設協定處理常式。您也可以透過檢查 macOS 電腦上的 ~/Library/Preferences/com.apple.LaunchServices.plist 來驗證這一點。請參閱 Apple 的文件以了解詳細資訊。

API 在內部使用 Windows 登錄和 LSCopyDefaultHandlerForURLScheme。

`app.getApplicationNameForProtocol(url)`

url 字串 - 具有要檢查的協定名稱的 URL。與此系列中的其他方法不同，此方法接受整個 URL，至少包括 ://（例如 https://）。

傳回 string - 處理協定的應用程式名稱，如果沒有處理常式，則傳回空字串。例如，如果 Electron 是 URL 的預設處理常式，則在 Windows 和 Mac 上可能是 Electron。但是，不要依賴確切的格式，因為它不能保證保持不變。在 Linux 上可能會看到不同的格式，可能帶有 .desktop 後綴。

此方法傳回 URL 的協定（又稱 URI 方案）的預設處理常式的應用程式名稱。

`app.getApplicationInfoForProtocol(url)` macOS Windows

url 字串 - 具有要檢查的協定名稱的 URL。與此系列中的其他方法不同，此方法接受整個 URL，至少包括 ://（例如 https://）。

傳回 Promise<Object> - 解析為包含以下內容的物件

icon NativeImage - 處理協定的應用程式的顯示圖示。
path 字串 - 處理協定的應用程式的安裝路徑。
name 字串 - 處理協定的應用程式的顯示名稱。

此方法傳回一個 Promise，其中包含 URL 的協定（又稱 URI 方案）的預設處理常式的應用程式名稱、圖示和路徑。

`app.setUserTasks(tasks)` Windows

tasks Task[] - Task 物件的陣列

將 tasks 新增至 Windows 上跳躍列表的 Tasks 類別。

tasks 是 Task 物件的陣列。

傳回 boolean - 呼叫是否成功。

注意： 如果您想要更進一步自訂跳躍列表，請改用 app.setJumpList(categories)。

`app.getJumpListSettings()` Windows

傳回 Object

minItems 整數 - 將在跳躍列表中顯示的最小項目數（有關此值的更詳細說明，請參閱 MSDN 文件）。
removedItems JumpListItem[] - JumpListItem 物件的陣列，對應於使用者已從跳躍列表中的自訂類別中明確移除的項目。這些項目不得在下一次呼叫 app.setJumpList() 時重新新增到跳躍列表，Windows 將不會顯示任何包含任何已移除項目的自訂類別。

`app.setJumpList(categories)` Windows

categories JumpListCategory[] | null - JumpListCategory 物件的陣列。

傳回 string

設定或移除應用程式的自訂跳躍列表，並傳回下列其中一個字串

ok - 一切正常。
error - 發生一個或多個錯誤，請啟用執行階段記錄以找出可能的原因。
invalidSeparatorError - 嘗試將分隔符號新增至跳躍列表中的自訂類別。分隔符號僅允許在標準 Tasks 類別中使用。
fileTypeRegistrationError - 嘗試將檔案連結新增至跳躍列表中應用程式未註冊處理的檔案類型。
customCategoryAccessDeniedError - 由於使用者隱私或群組原則設定，無法將自訂類別新增至跳躍列表。

如果 categories 為 null，則先前設定的自訂跳躍列表（如果有的話）將被應用程式的標準跳躍列表取代（由 Windows 管理）。

注意： 如果 JumpListCategory 物件既未設定 type 屬性也未設定 name 屬性，則其 type 會假設為 tasks。如果設定了 name 屬性但省略了 type 屬性，則 type 會假設為 custom。

注意： 使用者可以從自訂類別中移除項目，並且在下一次成功呼叫 app.setJumpList(categories) 之後，Windows 不允許將移除的項目新增回自訂類別中。任何試圖在之前將移除的項目重新新增到自訂類別中的操作都將導致整個自訂類別從跳躍列表中省略。可以使用 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' }
    ]
  },
  { // has a name so `type` is assumed to be "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' },
  { // has no name and no type so `type` is assumed to be "tasks"
    items: [
      {
        type: 'task',
        title: 'New Project',
        program: process.execPath,
        args: '--new-project',
        description: 'Create a new project.'
      },
      { type: 'separator' },
      {
        type: 'task',
        title: 'Recover Project',
        program: process.execPath,
        args: '--recover-project',
        description: 'Recover Project'
      }
    ]
  }
])

`app.requestSingleInstanceLock([additionalData])`

additionalData Record<any, any> (選用) - 包含要傳送給第一個執行個體的其他資料的 JSON 物件。

傳回 boolean

此方法的傳回值表示您的應用程式的此執行個體是否成功取得鎖定。如果它未能取得鎖定，您可以假設您的應用程式的另一個執行個體已在執行並具有鎖定，並立即退出。

也就是說，如果您的進程是應用程式的主要執行個體，並且您的應用程式應該繼續載入，則此方法傳回 true。如果您的進程應該立即退出，因為它已將其參數傳送給另一個已取得鎖定的執行個體，則此方法傳回 false。

在 macOS 上，當使用者嘗試在 Finder 中開啟您的應用程式的第二個執行個體時，系統會自動強制執行單一執行個體，並且會為該執行個體發出 open-file 和 open-url 事件。但是，當使用者在命令列中啟動您的應用程式時，系統的單一執行個體機制將被繞過，您必須使用此方法來確保單一執行個體。

以下範例說明當第二個執行個體啟動時如何啟用主要執行個體的視窗

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) => {
    // Print out data received from the second instance.
    console.log(additionalData)

    // Someone tried to run a second instance, we should focus our window.
    if (myWindow) {
      if (myWindow.isMinimized()) myWindow.restore()
      myWindow.focus()
    }
  })

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

`app.hasSingleInstanceLock()`

傳回 boolean

此方法傳回您的應用程式的此執行個體目前是否持有單一執行個體鎖定。您可以使用 app.requestSingleInstanceLock() 要求鎖定，並使用 app.releaseSingleInstanceLock() 釋放鎖定

`app.releaseSingleInstanceLock()`

釋放由 requestSingleInstanceLock 建立的所有鎖定。這將允許應用程式的多個執行個體再次並排執行。

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

type 字串 - 唯一識別活動。對應到 NSUserActivity.activityType。
userInfo 任意型別 - 要儲存供其他裝置使用的應用程式特定狀態。
webpageURL 字串 (選用) - 如果在恢復裝置上未安裝合適的應用程式，則要在瀏覽器中載入的網頁。配置必須為 http 或 https。

建立一個 NSUserActivity 並將其設定為目前的活動。該活動之後可透過接力 (Handoff) 傳遞到其他裝置。

`app.getCurrentActivityType()` macOS

回傳 string - 目前正在執行的活動類型。

`app.invalidateCurrentActivity()` macOS

使目前的接力 (Handoff) 使用者活動失效。

`app.resignCurrentActivity()` macOS

將目前的接力 (Handoff) 使用者活動標示為非使用中，但不使其失效。

`app.updateCurrentActivity(type, userInfo)` macOS

type 字串 - 唯一識別活動。對應到 NSUserActivity.activityType。
userInfo 任意型別 - 要儲存供其他裝置使用的應用程式特定狀態。

如果目前活動的類型與 type 相符，則更新目前活動，並將 userInfo 中的項目合併到其目前的 userInfo 字典中。

`app.setAppUserModelId(id)` Windows

id 字串

將應用程式使用者模型 ID 變更為 id。

`app.setActivationPolicy(policy)` macOS

policy 字串 - 可以是 'regular'、'accessory' 或 'prohibited'。

設定指定應用程式的啟用原則。

啟用原則類型

'regular' - 應用程式是一個普通的應用程式，會出現在 Dock 中，並且可能具有使用者介面。
'accessory' - 應用程式不會出現在 Dock 中，也沒有選單列，但可以透過程式設計或點擊其視窗之一來啟動。
'prohibited' - 應用程式不會出現在 Dock 中，並且無法建立視窗或啟動。

`app.importCertificate(options, callback)` Linux

options 物件
- certificate 字串 - pkcs12 檔案的路徑。
- password 字串 - 憑證的密碼。
callback Function
- result 整數 - 匯入結果。

將 pkcs12 格式的憑證匯入平台憑證存放區。callback 會以匯入操作的 result 呼叫，值為 0 表示成功，而任何其他值則表示失敗，這根據 Chromium 的 net_error_list。

`app.configureHostResolver(options)`

options 物件
- enableBuiltInResolver 布林值 (選用) - 是否優先使用內建的主機解析器，而非 getaddrinfo。啟用時，內建解析器會嘗試使用系統的 DNS 設定來自行執行 DNS 查詢。在 macOS 上預設啟用，在 Windows 和 Linux 上預設停用。
- secureDnsMode 字串 (選用) - 可以是 'off'、'automatic' 或 'secure'。設定 DNS over HTTP 模式。當為 'off' 時，不會執行任何 DoH 查詢。當為 'automatic' 時，如果 DoH 可用，則會先執行 DoH 查詢，並執行不安全的 DNS 查詢作為備用。當為 'secure' 時，只會執行 DoH 查詢。預設值為 'automatic'。
- secureDnsServers 字串陣列 (選用) - DNS over HTTP 伺服器範本的清單。有關範本格式的詳細資訊，請參閱 RFC8484 § 3。大多數伺服器都支援 POST 方法；此類伺服器的範本只是一個 URI。請注意，對於某些 DNS 提供者，除非明確停用 DoH，否則解析器會自動升級到 DoH，即使此清單中未提供任何 DoH 伺服器也是如此。
- enableAdditionalDnsQueryTypes 布林值 (選用) - 控制除了傳統的 A 和 AAAA 查詢之外，是否允許其他 DNS 查詢類型，例如 HTTPS (DNS 類型 65)，當透過不安全的 DNS 發出請求時。對安全 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 over HTTPS 伺服器清單，以防使用者的 DNS 設定不包含支援 DoH 的提供者。

const { app } = require('electron')

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

必須在發出 ready 事件之後呼叫此 API。

`app.disableHardwareAcceleration()`

停用目前應用程式的硬體加速。

此方法只能在應用程式準備就緒之前呼叫。

`app.disableDomainBlockingFor3DAPIs()`

依預設，如果 GPU 程序過於頻繁地崩潰，Chromium 會停用 3D API (例如 WebGL)，直到重新啟動，這是以網域為基礎的。此函式會停用該行為。

此方法只能在應用程式準備就緒之前呼叫。

`app.getAppMetrics()`

回傳 ProcessMetric[]：與應用程式相關聯的所有程序的記憶體和 CPU 使用統計資訊相對應的 ProcessMetric 物件陣列。

`app.getGPUFeatureStatus()`

回傳 GPUFeatureStatus - 來自 chrome://gpu/ 的圖形功能狀態。

注意：此資訊僅在發出 gpu-info-update 事件後才可使用。

`app.getGPUInfo(infoType)`

infoType 字串 - 可以是 basic 或 complete。

回傳 Promise<unknown>

對於 infoType 等於 complete：Promise 會使用 Object 完成，其中包含 chromium 的 GPUInfo 物件中所有 GPU 資訊。這包括 chrome://gpu 頁面上顯示的版本和驅動程式資訊。

對於 infoType 等於 basic：Promise 會使用 Object 完成，其中包含比使用 complete 要求時更少的屬性。以下是基本回應的範例

{
  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 整數 (選用) - 如果提供值，則將標記設定為提供的值，否則在 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 字串 (選用) macOS - 可以是 mainAppService、agentService、daemonService 或 loginItemService 其中之一。預設值為 mainAppService。僅適用於 macOS 13 及更高版本。有關每種類型的詳細資訊，請參閱 app.setLoginItemSettings。
- serviceName 字串 (選用) macOS - 服務的名稱。如果 type 為非預設值，則為必要項。僅適用於 macOS 13 及更高版本。
- path 字串 (選用) Windows - 要與之比較的執行檔路徑。預設值為 process.execPath。
- args 字串陣列 (選用) Windows - 要與之比較的命令列引數。預設值為空陣列。

如果您為 app.setLoginItemSettings 提供了 path 和 args 選項，則您需要在此處傳遞相同的引數，以正確設定 openAtLogin。

傳回 Object

openAtLogin 布林值 - 如果應用程式設定為在登入時開啟，則為 true。
openAsHidden 布林值 macOS 已過時 - 如果應用程式設定為在登入時隱藏開啟，則為 true。這在 macOS 13 及更高版本上不起作用。
wasOpenedAtLogin 布林值 macOS - 如果應用程式在登入時自動開啟，則為 true。
wasOpenedAsHidden 布林值 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 選項，如果指定的執行檔會以任何引數在登入時啟動，此屬性將為 true。
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 字串 (選用) macOS - 服務的名稱。如果 type 為非預設值，則為必要項。僅適用於 macOS 13 及更高版本。
- path string (選用) Windows - 要在登入時啟動的執行檔。預設值為 process.execPath。
- args string[] (選用) Windows - 傳遞給執行檔的命令列引數。預設值為空陣列。請注意將路徑括在引號中。
- enabled boolean (選用) Windows - true 將會變更已核准啟動的登錄金鑰，並在工作管理員和 Windows 設定中啟用/停用應用程式。預設值為 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 的協助工具文件。預設為停用。

必須在發出 ready 事件之後呼叫此 API。

注意：轉譯協助工具樹狀結構可能會顯著影響應用程式的效能。預設不應啟用。

`app.showAboutPanel()`

顯示應用程式的「關於」面板選項。這些選項可以使用 app.setAboutPanelOptions(options) 覆寫。此函式會以非同步方式執行。

`app.setAboutPanelOptions(options)`

options 物件
- 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 上，將會顯示為 64x64 像素，同時保留長寬比。在 Windows 上，48x48 PNG 將會產生最佳的視覺品質。

設定「關於」面板選項。這將會覆寫 macOS 上應用程式的 .plist 檔案中定義的值。如需詳細資訊，請參閱 Apple 文件。在 Linux 上，必須設定值才能顯示；沒有預設值。

如果您未設定 credits，但仍希望在您的應用程式中顯示它們，AppKit 將會在 NSBundle 類別方法 main 傳回的套件中，依序尋找名為 "Credits.html"、"Credits.rtf" 和 "Credits.rtfd" 的檔案。會使用找到的第一個檔案，如果找不到任何檔案，資訊區域會保留空白。如需詳細資訊，請參閱 Apple 文件。

`app.isEmojiPanelSupported()`

傳回 boolean - 目前的作業系統版本是否允許使用原生表情符號選擇器。

`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)
})

// ... restart app ...

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

開始存取安全範圍資源。透過此方法，針對 Mac App Store 打包的 Electron 應用程式可以到達其沙箱外部，以存取使用者選擇的檔案。如需有關此系統如何運作的說明，請參閱 Apple 的文件。

`app.enableSandbox()`

在應用程式上啟用完整沙箱模式。這表示所有轉譯器都將以沙箱模式啟動，無論 WebPreferences 中的 sandbox 旗標的值為何。

此方法只能在應用程式準備就緒之前呼叫。

`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> - 當 Proxy 設定程序完成時解析。

為未關聯 Session 的網路請求設定 Proxy 設定。目前這會影響在公用程式程序中使用 Net 發出的請求，以及執行階段發出的內部請求 (例如：地理定位查詢)。

此方法只能在應用程式準備就緒後呼叫。

`app.resolveProxy(url)`

url URL

傳回 Promise<string> - 解析為 url 的 Proxy 資訊，這些資訊將在嘗試使用 Net 在公用程式程序中發出請求時使用。

`app.setClientCertRequestPasswordHandler(handler)` Linux

handler Function<Promise<string>>
- clientCertRequestParams Object
  - hostname string - 需要用戶端憑證的網站主機名稱
  - tokenName string - 加密裝置的權杖 (或插槽) 名稱
  - isRetry boolean - 先前提示密碼的嘗試是否失敗
傳回 Promise<string> - 解析為密碼

當需要密碼來解鎖 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 的輔助功能文件以取得更多詳細資訊。預設為停用。

必須在發出 ready 事件之後呼叫此 API。

注意：轉譯協助工具樹狀結構可能會顯著影響應用程式的效能。預設不應啟用。

`app.applicationMenu`

一個 Menu | null 屬性，如果已設定則傳回 Menu，否則傳回 null。使用者可以傳遞 Menu 來設定此屬性。

`app.badgeCount` Linux macOS

一個 Integer 屬性，傳回目前應用程式的徽章計數。將計數設定為 0 將會隱藏徽章。

在 macOS 上，將此設定為任何非零整數都會顯示在 Dock 圖示上。在 Linux 上，此屬性僅適用於 Unity 啟動器。

注意： Unity 啟動器需要一個 .desktop 檔案才能運作。如需更多資訊，請參閱 Unity 整合文件。

注意： 在 macOS 上，您需要確保您的應用程式具有顯示通知的權限，此屬性才會生效。

`app.commandLine` 唯讀

一個 CommandLine 物件，可讓您讀取和操作 Chromium 使用的命令列引數。

`app.dock` macOS 唯讀

一個 Dock | undefined 物件，可讓您在 macOS 上對使用者 Dock 中的應用程式圖示執行動作。

`app.isPackaged` 唯讀

一個 boolean 屬性，如果應用程式已封裝則傳回 true，否則傳回 false。對於許多應用程式，此屬性可用於區分開發和生產環境。

`app.name`

一個 string 屬性，表示目前應用程式的名稱，也就是應用程式 package.json 檔案中的名稱。

`app.userAgentFallback`

一個 string，它是 Electron 將用作全域後援的使用者代理程式字串。

這是當在 webContents 或 session 層級未設定使用者代理程式時將使用的使用者代理程式。這對於確保您的整個應用程式具有相同的使用者代理程式很有用。盡可能在應用程式初始化時設定為自訂值，以確保使用您的覆寫值。

`app.runningUnderARM64Translation` 唯讀 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)`