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 初始化时 fulfilled 的 Promise。

注意

ready 事件仅在主进程完成事件循环的第一次 tick 运行后才会触发。如果 Electron API 需要在 ready 事件之前调用，请确保它在主进程的顶层上下文以同步方式调用。

事件：'window-all-closed'

当所有窗口都关闭时发出。

如果您未订阅此事件且所有窗口都已关闭，则默认行为是退出应用程序；但是，如果您订阅，则由您控制应用程序是否退出。如果用户按下 Cmd + Q，或开发者调用 app.quit()，Electron 将首先尝试关闭所有窗口，然后发出 will-quit 事件，在这种情况下，window-all-closed 事件将不会发出。

事件：'before-quit'

event Event

在应用程序开始关闭其窗口之前发出。调用 event.preventDefault() 将阻止默认行为，即终止应用程序。

注意

如果应用程序退出是由 autoUpdater.quitAndInstall() 启动的，则 before-quit 会在所有窗口发出 close 事件并关闭它们之后发出。

注意

在 Windows 上，如果应用程序因系统关闭/重新启动或用户注销而关闭，则不会发出此事件。

事件：'will-quit'

event Event

当所有窗口都关闭且应用程序将退出时发出。调用 event.preventDefault() 将阻止默认行为，即终止应用程序。

请参阅 window-all-closed 事件的描述，了解 will-quit 和 window-all-closed 事件之间的区别。

注意

在 Windows 上，如果应用程序因系统关闭/重新启动或用户注销而关闭，则不会发出此事件。

事件：'quit'

event Event
exitCode Integer

当应用程序退出时发出。

注意

在 Windows 上，如果应用程序因系统关闭/重新启动或用户注销而关闭，则不会发出此事件。

事件：'open-file' macOS

event Event
path string

当用户想要使用应用程序打开文件时发出。open-file 事件通常在应用程序已打开且操作系统想要重用该应用程序打开文件时发出。当文件拖放到 Dock 上且应用程序尚未运行时，也会发出 open-file 事件。请务必在应用程序启动早期（甚至在 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

当应用程序被激活时发出。各种操作都可以触发此事件，例如首次启动应用程序、在应用程序已运行时尝试重新启动应用程序，或单击应用程序的 Dock 或任务栏图标。

事件：'did-become-active' macOS

event Event

当应用程序变为活动状态时发出。这与 activate 事件不同，因为 did-become-active 在应用程序每次变为活动状态时都会发出，而不仅仅是在单击 Dock 图标或重新启动应用程序时。当用户通过 macOS App Switcher 切换到应用程序时，它也会发出。

事件：'did-resign-active' macOS

event Event

当应用程序不再活动且失去焦点时发出。这可能是通过单击另一个应用程序或使用 macOS App Switcher 切换到另一个应用程序来触发的。

事件：'continue-activity' macOS

event Event
type string - 标识活动的字符串。映射到 NSUserActivity.activityType。
userInfo unknown - 包含由另一个设备上的活动存储的特定于应用程序的状态。
details Object
- webpageURL string (可选) - 标识另一个设备上的活动访问的网页 URL 的字符串（如果可用）。

在 Handoff 期间发出，当来自不同设备的活动想要恢复时。如果您想处理此事件，应调用 event.preventDefault()。

用户活动只能在与活动源应用程序具有相同开发者团队 ID 且支持活动类型的应用程序中继续。支持的活动类型在应用程序的 Info.plist 中 NSUserActivityTypes 键下指定。

事件：'will-continue-activity' macOS

event Event
type string - 标识活动的字符串。映射到 NSUserActivity.activityType。

在 Handoff 期间发出，在来自不同设备的活动想要恢复之前。如果您想处理此事件，应调用 event.preventDefault()。

事件：'continue-activity-error' macOS

event Event
type string - 标识活动的字符串。映射到 NSUserActivity.activityType。
error string - 带有错误本地化描述的字符串。

在 Handoff 期间发出，当来自不同设备的活动未能恢复时。

事件：'activity-was-continued' macOS

event Event
type string - 标识活动的字符串。映射到 NSUserActivity.activityType。
userInfo unknown - 包含由活动存储的应用程序特定状态。

在 Handoff 期间发出，当此设备的活动成功在另一个设备上恢复后。

事件：'update-activity-state' macOS

event Event
type string - 标识活动的字符串。映射到 NSUserActivity.activityType。
userInfo unknown - 包含由活动存储的应用程序特定状态。

当 Handoff 即将在另一个设备上恢复时发出。如果您需要更新要传输的状态，应立即调用 event.preventDefault()，构建一个新的 userInfo 字典，并及时调用 app.updateCurrentActivity()。否则，操作将失败，并调用 continue-activity-error。

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

event Event

当用户点击原生 macOS 新标签按钮时发出。新标签按钮仅在当前 BrowserWindow 具有 tabbingIdentifier 时可见。

事件：'browser-window-blur'

event Event
window BrowserWindow

当 browserWindow 失去焦点时发出。

事件：'browser-window-focus'

event Event
window BrowserWindow

当 browserWindow 获得焦点时发出。

事件：'browser-window-created'

event Event
window BrowserWindow

当新的 browserWindow 创建时发出。

事件：'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') {
    // Verification logic.
    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])
})

event 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 或 Utility 进程想要执行基本身份验证时发出。

默认行为是取消所有身份验证。要覆盖此行为，您应使用 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

当渲染器进程意外消失时发出。这通常是因为它崩溃或被终止。

事件：'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 (可选) - 进程的名称。Utility 的示例：Audio Service、Content Decryption Module Service、Network Service、Video Capture 等。

当子进程意外消失时发出。这通常是因为它崩溃或被终止。不包括渲染器进程。

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

event 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 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 用户的 home 目录。
- appData 每个用户的应用程序数据目录，默认指向：
  - Windows 上的 %APPDATA%
  - Linux 上的 $XDG_CONFIG_HOME 或 ~/.config
  - macOS 上的 ~/Library/Application Support
- assets 存储应用程序资产（如 resources.pak）的目录。默认情况下，这与包含 exe 路径的文件夹相同。仅在 Windows 和 Linux 上可用。
- userData 存储应用程序配置文件的目录，默认情况下是 appData 目录附加应用程序名称。根据约定，存储用户数据的文件应写入此目录，不建议在此处写入大文件，因为某些环境可能会将此目录备份到云存储。
- sessionData 存储 Session 生成的数据的目录，例如 localStorage、cookies、磁盘缓存、下载的字典、网络状态、devtools 文件。默认情况下，这指向 userData。Chromium 可能会在此处写入非常大的磁盘缓存，因此如果您的应用程序不依赖浏览器存储（如 localStorage 或 cookies）来保存用户数据，建议将此目录设置为其他位置，以避免污染 userData 目录。
- temp 临时目录。
- exe 当前可执行文件。
- module Chromium 模块的位置。默认情况下，这与 exe 同义。
- desktop 当前用户的桌面目录。
- documents 用户“我的文档”目录。
- downloads 用户下载目录。
- music 用户音乐目录。
- pictures 用户图片目录。
- videos 用户视频目录。
- recent 用户最近文件目录（仅限 Windows）。
- logs 应用程序日志文件夹目录。
- crashDumps 崩溃转储存储目录。

返回 string - 与 name 关联的特殊目录或文件的路径。失败时，将抛出 Error。

如果未先调用 app.setAppLogsPath() 就调用 app.getPath('logs')，将创建一个默认日志目录，相当于不带 path 参数调用 app.setAppLogsPath()。

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

path string
options Object (可选)
- size string
  - small - 16x16
  - normal - 32x32
  - large - Linux 上为 48x48，Windows 上为 32x32，macOS 上不支持。

返回 Promise<NativeImage> - 应用程序图标（一个 NativeImage）的 fulfilled Promise。

获取路径关联的图标。

在 Windows 上，有两种图标：

与某些文件扩展名关联的图标，例如 .mp3、.png 等。
文件内部的图标，例如 .exe、.dll、.ico。

在 Linux 和 macOS 上，图标取决于与文件 MIME 类型关联的应用程序。

`app.setPath(name, path)`

name string
path string

覆盖与 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 库获取。可能的返回值在此处 https://source.chromium.org/chromium/chromium/src/+/main:ui/base/l10n/l10n_util.cc 有记录。

要设置区域设置，您需要在应用程序启动时使用命令行开关，可以在此处找到。

注意

分发打包的应用程序时，您还必须附带 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 可用于选择日历应用程序中日期和时间的呈现格式等目的，特别是当开发人员希望格式与操作系统保持一致时。

注意

此 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 string

将 path 添加到最近文档列表。

此列表由操作系统管理。在 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 方案）的默认处理程序。它允许您将应用程序更深入地集成到操作系统中。注册后，所有带有 your-protocol:// 的链接都将使用当前可执行文件打开。整个链接，包括协议，将作为参数传递给您的应用程序。

注意

在 macOS 上，您只能注册已添加到应用程序 info.plist 的协议，该文件在运行时无法修改。但是，您可以在构建时通过 Electron Forge、Electron Packager 或使用文本编辑器编辑 info.plist 来更改文件。请参阅 Apple 的文档了解详细信息。

注意

在 Windows Store 环境中（当打包为 appx 时），此 API 将对所有调用返回 true，但它设置的注册表项将无法被其他应用程序访问。为了将您的 Windows Store 应用程序注册为默认协议处理程序，您必须在您的清单中声明协议。

该 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 方案）的默认处理程序。

注意

在 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)` macOS Windows

url string - 包含要检查的协议名称的 URL。与此家族中的其他方法不同，此方法接受整个 URL，至少包括 ://（例如 https://）。

返回 Promise<Object> - 以包含以下内容的对象解析：

icon NativeImage - 处理协议的应用程序的显示图标。
path string - 处理协议的应用程序的安装路径。
name string - 处理协议的应用程序的显示名称。

此方法返回一个 Promise，其中包含 URL 协议（又名 URI 方案）的默认处理程序的应用程序名称、图标和路径。

`app.setUserTasks(tasks)` Windows

tasks Task[] - Task 对象的数组

将 tasks 添加到 Windows Jump List 的 Tasks 类别。

tasks 是 Task 对象的数组。

返回 boolean - 调用是否成功。

注意

如果您想更进一步自定义 Jump List，请使用 app.setJumpList(categories) 代替。

`app.getJumpListSettings()` Windows

返回 Object

minItems Integer - Jump List 中将显示的项目最少数量（有关此值的更详细描述，请参阅 MSDN 文档）。
removedItems JumpListItem[] - JumpListItem 对象数组，对应于用户已从 Jump List 中的自定义类别中明确删除的项目。这些项目在下次调用 app.setJumpList() 时不得重新添加到 Jump List，Windows 将不显示包含任何已删除项目的任何自定义类别。

`app.setJumpList(categories)` Windows

categories JumpListCategory[] | null - JumpListCategory 对象的数组。

返回 string

为应用程序设置或移除自定义 Jump List，并返回以下字符串之一：

ok - 没有问题。
error - 发生一个或多个错误，启用运行时日志以找出可能的原因。
invalidSeparatorError - 尝试向 Jump List 的自定义类别添加分隔符。分隔符仅允许在标准 Tasks 类别中。
fileTypeRegistrationError - 尝试向 Jump List 添加应用程序未注册处理的文件类型的链接。
customCategoryAccessDeniedError - 由于用户隐私或组策略设置，无法将自定义类别添加到 Jump List。

如果 categories 为 null，则先前设置的自定义 Jump List（如果有）将被应用程序的标准 Jump List（由 Windows 管理）替换。

注意

如果 JumpListCategory 对象既没有设置 type 属性也没有设置 name 属性，则其 type 被假定为 tasks。如果设置了 name 属性但省略了 type 属性，则 type 被假定为 custom。

注意

用户可以从自定义类别中删除项目，并且 Windows 将不允许在下次成功调用 app.setJumpList(categories) 之前将已删除的项目重新添加回自定义类别。任何在此之前尝试将已删除项目重新添加到自定义类别的操作都将导致整个自定义类别从 Jump List 中省略。已删除项目列表可以通过 app.getJumpListSettings() 获取。

注意

Jump List 项目的 description 属性的最大长度为 260 个字符。超过此限制，该项目将不会添加到 Jump List 中，也不会显示。

以下是创建自定义 Jump List 的一个非常简单的示例：

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.js.cn')
  })
}

`app.hasSingleInstanceLock()`

返回 boolean

此方法返回应用程序的此实例是否当前持有单实例锁。您可以使用 app.requestSingleInstanceLock() 请求锁，并使用 app.releaseSingleInstanceLock() 释放锁。

`app.releaseSingleInstanceLock()`

释放所有由 requestSingleInstanceLock 创建的锁。这将允许应用程序的多个实例再次并排运行。

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

type string - 唯一标识活动。映射到 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 - 唯一标识活动。映射到 NSUserActivity.activityType。
userInfo any - 应用程序特定的状态，用于存储以供其他设备使用。

如果当前活动的类型与 type 匹配，则更新当前活动，并将 userInfo 中的条目合并到其当前的 userInfo 字典中。

`app.setAppUserModelId(id)` Windows

id string

将应用程序用户模型 ID 更改为 id。

`app.setActivationPolicy(policy)` macOS

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

设置给定应用程序的激活策略。

激活策略类型：

'regular' - 应用程序是普通应用程序，出现在 Dock 中，可能具有用户界面。
'accessory' - 应用程序不出现在 Dock 中，也没有菜单栏，但可以通过编程或单击其窗口之一来激活。
'prohibited' - 应用程序不出现在 Dock 中，可能无法创建窗口或被激活。

`app.importCertificate(options, callback)` Linux

options Object
- certificate string - pkcs12 文件的路径。
- password string - 证书的密码。
callback Function
- result Integer - 导入结果。

将 pkcs12 格式的证书导入平台证书存储。callback 会以导入操作的 result 调用，值为 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' 或 '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 (可选) - 控制是否允许除了传统的 A 和 AAAA 查询之外的额外 DNS 查询类型，例如 HTTPS (DNS type 65)，当通过不安全 DNS 发出请求时。对总是允许额外类型的安全 DNS 没有影响。默认为 true。

配置主机解析（DNS 和 DNS-over-HTTPS）。默认情况下，将按顺序使用以下解析器：

如果 DNS 提供商支持，则使用 DNS-over-HTTPS，然后是
内置解析器（默认仅在 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'
    ]
  })
})

此 API 必须在 ready 事件发出后调用。

`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 string - 可以是 basic 或 complete。

返回 Promise<unknown>

对于 infoType 等于 complete：Promise 以包含所有 GPU 信息的 Object 填充，如 chromium 的 GPUInfo 对象中所示。这包括 chrome://gpu 页面上显示的版本和驱动程序信息。

对于 infoType 等于 basic：Promise 以包含比 complete 请求时更少属性的 Object 填充。以下是基本响应的示例：

{
  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 Integer (可选) - 如果提供了值，则将徽章设置为提供的值；否则，在 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 string (可选) macOS - 可以是 mainAppService、agentService、daemonService 或 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。这表示应用程序在启动时不应打开任何窗口。此设置在 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 string (可选) 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，您需要将启动路径设置为可执行文件的名称，但要设置为上一级目录，这是一个由 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: [
    // You might want to pass a parameter here indicating that this
    // app was launched via login, but you don't have to
  ]
})

有关在 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 布尔值 - 启用或禁用辅助功能树渲染

手动启用 Chrome 的辅助功能支持，允许在应用程序设置中向用户公开辅助功能开关。有关详细信息，请参阅 Chromium 的辅助功能文档。默认禁用。

此 API 必须在 ready 事件发出后调用。

注意

渲染辅助功能树可能会显著影响应用程序的性能。默认情况下不应启用它。调用此方法将启用以下辅助功能支持：nativeAPIs、webContents、inlineTextBoxes 和 extendedProperties。

`app.getAccessibilitySupportFeatures()` macOS Windows

返回 string[] - 字符串数组，表示当前已启用的辅助功能支持组件的名称。可能的值

nativeAPIs - 已启用原生操作系统辅助功能 API 集成。
webContents - 已启用 Web 内容辅助功能树公开。
inlineTextBoxes - 已启用行内文本框 (字符边界框)。
extendedProperties - 已启用扩展辅助功能属性。
screenReader - 已启用屏幕阅读器特定模式。
html - 已启用 HTML 辅助功能树构造。
labelImages - 自动图像注释的辅助功能支持。
pdfPrinting - 已启用 PDF 打印的辅助功能支持。

备注

如果未激活任何辅助功能模式，则数组可能为空。
对于旧版布尔值检查，请使用 app.isAccessibilitySupportEnabled()；对于精细诊断或遥测，请优先使用此方法。

示例

const { app } = require('electron')

app.whenReady().then(() => {
  if (app.getAccessibilitySupportFeatures().includes('screenReader')) {
    // Change some app UI to better work with Screen Readers.
  }
})

`app.setAccessibilitySupportFeatures(features)` macOS Windows

features string[] - 要启用的辅助功能数组。

可能的值是

nativeAPIs - 已启用原生操作系统辅助功能 API 集成。
webContents - 已启用 Web 内容辅助功能树公开。
inlineTextBoxes - 已启用行内文本框 (字符边界框)。
extendedProperties - 已启用扩展辅助功能属性。
screenReader - 已启用屏幕阅读器特定模式。
html - 已启用 HTML 辅助功能树构造。
labelImages - 自动图像注释的辅助功能支持。
pdfPrinting - 已启用 PDF 打印的辅助功能支持。

要禁用所有支持的功能，请传递空数组 []。

示例

const { app } = require('electron')

app.whenReady().then(() => {
  // Enable a subset of features:
  app.setAccessibilitySupportFeatures([
    'screenReader',
    'pdfPrinting',
    'webContents'
  ])

  // Other logic

  // Some time later, disable all features:
  app.setAccessibilitySupportFeatures([])
})

`app.showAboutPanel()`

显示应用程序的关于面板选项。这些选项可以通过 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 上，将以 64x64 像素显示，同时保持宽高比。在 Windows 上，48x48 PNG 将获得最佳视觉质量。

设置“关于”面板选项。这将覆盖 macOS 上应用程序 .plist 文件中定义的值。有关详细信息，请参阅 Apple 文档。在 Linux 上，必须设置值才能显示；没有默认值。

如果您未设置 credits 但仍希望在应用程序中显示它们，AppKit 将按“Credits.html”、“Credits.rtf”和“Credits.rtfd”的顺序，在 NSBundle 类方法 main 返回的包中查找名为“Credits.html”的文件。找到的第一个文件将被使用，如果未找到任何文件，则信息区域将留空。有关详细信息，请参阅 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 布尔值 - 启用或禁用 安全键盘输入

设置在您的应用程序中启用 安全键盘输入。

使用此 API，可以防止密码和其他敏感信息等重要信息被其他进程拦截。

有关详细信息，请参阅 Apple 文档。

注意

仅在需要时启用 安全键盘输入，并在不再需要时禁用它。

`app.setProxy(config)`

config ProxyConfig

返回 Promise<void> - 在代理设置过程完成时解决。

设置没有关联 Session 的网络请求的代理设置。目前，这将影响在实用程序进程中使用 Net 发出的请求以及运行时发出的内部请求 (例如：地理位置查询)。

此方法只能在应用程序准备好后调用。

`app.resolveProxy(url)`

url URL

返回 Promise<string> - 解析为 url 的代理信息，该信息将在尝试使用 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 的辅助功能文档。默认禁用。

此 API 必须在 ready 事件发出后调用。

注意

渲染辅助功能树可能会显著影响应用程序的性能。默认情况下不应启用它。

`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，所有其他平台为 undefined)，允许您对用户停靠栏中的应用程序图标执行操作。

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

您可以使用此属性提示用户下载应用程序的 arm64 版本，当他们错误地在 Rosetta 或 WOW 下运行 x64 版本时。

事件
方法
属性

事件​

事件：'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.getRecentDocuments() 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()​

事件

事件：'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.getRecentDocuments()` 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()`