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

注意

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

事件：'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() 将阻止默认行为，即终止应用程序。

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

注意

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

事件：'quit'

返回值

event Event
exitCode Integer

在应用程序正在退出时发出。

注意

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

事件：'open-file' macOS

返回值

event Event
path string

当用户希望使用应用程序打开文件时发出。open-file 事件通常在应用程序已打开且操作系统希望重用该应用程序打开文件时发出。当文件拖放到 Dock 上且应用程序尚未运行时，也会发出 open-file 事件。请确保在应用程序启动的早期监听 open-file 事件，以处理此情况 (甚至在 ready 事件发出之前)。

如果你想处理此事件，应该调用 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 应用程序切换器切换到应用程序时，此事件也会发出。

事件：'did-resign-active' macOS

返回值

event Event

在应用程序不再活跃且不再聚焦时发出。例如，可以通过点击另一个应用程序或使用 macOS 应用程序切换器切换到另一个应用程序来触发此事件。

事件：'continue-activity' macOS

返回值

event Event
type string - 标识活动的字符串。映射到 NSUserActivity.activityType。
userInfo unknown - 包含活动在另一设备上存储的特定于应用程序的状态。
details Object
- webpageURL string (optional) - 标识活动在另一设备上访问的网页 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 (optional)

当请求客户端证书时发出。

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 (optional)
authenticationResponseDetails Object
- url URL
- pid number
authInfo Object
- isProxy boolean
- scheme string
- host string
- port Integer
- realm string
callback Function
- username string (optional)
- password string (optional)

当 webContents 或 Utility process 想要执行基本认证时发出。

默认行为是取消所有认证。要覆盖此行为，你应该用 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 插件
  - Pepper 插件经纪人
  - 未知
- reason string - 子进程消失的原因。可能的值
  - clean-exit - 进程以零退出代码退出
  - abnormal-exit - 进程以非零退出代码退出
  - killed - 进程被发送 SIGTERM 或以其他方式被外部终止
  - crashed - 进程崩溃
  - oom - 进程内存不足
  - launch-failed - 进程从未成功启动
  - integrity-failure - Windows 代码完整性检查失败
- exitCode number - 进程的退出代码 (例如，如果是在 POSIX 上，则来自 waitpid 的状态；在 Windows 上则来自 GetExitCodeProcess)。
- serviceName string (optional) - 进程的非本地化名称。
- name string (optional) - 进程名称。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 (optional)

立即以 exitCode 退出。exitCode 默认为 0。

所有窗口将立即关闭，不询问用户，并且 before-quit 和 will-quit 事件将不会发出。

`app.relaunch([options])`

options Object (optional)
- args string[] (optional)
- execPath string (optional)

当当前实例退出时重新启动应用程序。

默认情况下，新实例将使用与当前实例相同的工作目录和命令行参数。当指定 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()`

Returns boolean - 如果 Electron 完成初始化则为 true，否则为 false。另请参阅 app.whenReady()。

`app.whenReady()`

Returns Promise<void> - 在 Electron 初始化时完成。如果应用程序尚未准备就绪，此方法可作为检查 app.isReady() 并订阅 ready 事件的便捷替代方案。

`app.focus([options])`

options Object (optional)
- steal boolean macOS - 即使另一个应用程序当前处于活动状态，也使接收者成为活动应用程序。

在 Linux 上，聚焦于第一个可见窗口。在 macOS 上，使应用程序成为活动应用程序。在 Windows 上，聚焦于应用程序的第一个窗口。

你应该尽量少使用 steal 选项。

`app.hide()` macOS

隐藏所有应用程序窗口而不最小化它们。

`app.isHidden()` macOS

Returns boolean - 如果应用程序 (包括其所有窗口) 被隐藏 (例如通过 Command-H)，则为 true，否则为 false。

`app.show()` macOS

在应用程序窗口被隐藏后显示它们。不会自动聚焦它们。

`app.setAppLogsPath([path])`

path string (optional) - 自定义日志路径。必须是绝对路径。

设置或创建应用程序日志的目录，然后可以使用 app.getPath() 或 app.setPath(pathName, newPath) 进行操作。

不带 path 参数调用 app.setAppLogsPath() 将导致此目录在 macOS 上被设置为 ~/Library/Logs/YourAppName，在 Linux 和 Windows 上则为 userData 目录内。

`app.getAppPath()`

Returns string - 当前应用程序目录。

`app.getPath(name)`

name string - 你可以通过名称请求以下路径
- home 用户主目录。
- appData 每个用户的应用程序数据目录，默认指向
  - Windows 上的 %APPDATA%
  - Linux 上的 $XDG_CONFIG_HOME 或 ~/.config
  - macOS 上的 ~/Library/Application Support
- userData 存储应用程序配置文件的目录，默认情况下是 appData 目录后附加应用程序名称。按照惯例，存储用户数据的文件应该写入此目录，不建议在此写入大型文件，因为某些环境可能会将此目录备份到云存储。
- sessionData 存储 Session 生成数据的目录，例如 localStorage、cookies、磁盘缓存、下载的词典、网络状态、开发者工具文件。默认指向 userData。Chromium 可能会在此写入非常大的磁盘缓存，因此如果你的应用程序不依赖浏览器存储 (如 localStorage 或 cookies) 来保存用户数据，建议将此目录设置为其他位置以避免污染 userData 目录。
- temp 临时目录。
- exe 当前可执行文件。
- module libchromiumcontent 库。
- desktop 当前用户桌面目录。
- documents 用户“我的文档”目录。
- downloads 用户下载目录。
- music 用户音乐目录。
- pictures 用户图片目录。
- videos 用户视频目录。
- recent 用户最近文件目录 (仅限 Windows)。
- logs 应用程序日志文件夹目录。
- crashDumps 崩溃转储存储目录。

Returns string - 与 name 关联的特殊目录或文件的路径。如果失败，则抛出 Error。

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

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

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

Returns Promise<NativeImage> - 以应用程序图标 (一个 NativeImage) 完成。

获取路径关联的图标。

在 Windows 上，有 2 种图标

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

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

`app.setPath(name, path)`

name string
path string

覆盖与 name 关联的特殊目录或文件的 path。如果路径指定了一个不存在的目录，则抛出 Error。在这种情况下，应该使用 fs.mkdirSync 或类似方法创建该目录。

你只能覆盖在 app.getPath 中定义的 name 的路径。

默认情况下，网页的 cookies 和缓存将存储在 sessionData 目录下。如果你想更改此位置，你必须在 app 模块的 ready 事件发出之前覆盖 sessionData 路径。

`app.getVersion()`

Returns string - 加载的应用程序的版本。如果在应用程序的 package.json 文件中未找到版本，则返回当前捆绑包或可执行文件的版本。

`app.getName()`

Returns string - 当前应用程序的名称，即应用程序 package.json 文件中的名称。

通常，package.json 的 name 字段是一个简短的小写名称，符合 npm 模块规范。你通常还应该指定一个 productName 字段，它是应用程序的完整大写名称，并且 Electron 将优先使用它而非 name。

`app.setName(name)`

name string

覆盖当前应用程序的名称。

注意

此函数覆盖 Electron 内部使用的名称；它不影响操作系统使用的名称。

`app.getLocale()`

Returns string - 当前应用程序的区域设置，使用 Chromium 的 l10n_util 库获取。可能返回的值在此处有文档说明：here。

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

注意

分发打包的应用程序时，你还必须附带 locales 文件夹。

注意

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

注意

要查看此 API 与其他区域设置和语言 API 的示例返回值，请参阅 app.getPreferredSystemLanguages()。

`app.getLocaleCountryCode()`

Returns string - 用户操作系统的区域设置两位数 ISO 3166 国家代码。该值取自原生操作系统 API。

注意

当无法检测到区域设置国家代码时，它返回空字符串。

`app.getSystemLocale()`

Returns string - 当前系统区域设置。在 Windows 和 Linux 上，它使用 Chromium 的 i18n 库获取。在 macOS 上，而是使用 [NSLocale currentLocale]。要获取用户当前的系统语言 (它不总是与区域设置相同)，最好使用 app.getPreferredSystemLanguages()。

不同的操作系统对区域数据的使用方式也不同

Windows 11 使用区域格式来显示数字、日期和时间。
macOS Monterey 使用区域来格式化数字、日期、时间，并用于选择要使用的货币符号。

因此，此 API 可用于诸如在日历应用程序中选择日期和时间的渲染格式等目的，特别是当开发者希望格式与操作系统保持一致时。

注意

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

注意

要查看此 API 与其他区域设置和语言 API 的示例返回值，请参阅 app.getPreferredSystemLanguages()。

`app.getPreferredSystemLanguages()`

Returns 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.setAsDefaultProtocolClient(protocol[, path, args])`

protocol string - 你的协议名称，不带 ://。例如，如果你希望你的应用程序处理 electron:// 链接，请将 electron 作为参数调用此方法。
path string (optional) Windows - Electron 可执行文件的路径。默认为 process.execPath
args string[] (optional) Windows - 传递给可执行文件的参数。默认为一个空数组

Returns 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 string - 你的协议名称，不带 ://。
path string (optional) Windows - 默认为 process.execPath
args string[] (optional) Windows - 默认为一个空数组

Returns boolean - 调用是否成功。

此方法检查当前可执行文件是否为协议 (也称为 URI 方案) 的默认处理程序。如果是，它将删除应用程序的默认处理程序身份。

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

protocol string - 你的协议名称，不带 ://。
path string (optional) Windows - 默认为 process.execPath
args string[] (optional) Windows - 默认为一个空数组

Returns boolean - 当前可执行文件是否为协议 (也称为 URI 方案) 的默认处理程序。

注意

在 macOS 上，你可以使用此方法检查应用程序是否已注册为协议的默认协议处理程序。你还可以通过检查 macOS 机器上的 ~/Library/Preferences/com.apple.LaunchServices.plist 来验证这一点。有关详细信息，请参阅 Apple 的文档。

此 API 内部使用 Windows 注册表和 LSCopyDefaultHandlerForURLScheme。

`app.getApplicationNameForProtocol(url)`

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

Returns string - 处理该协议的应用程序名称，如果没有处理程序则为空字符串。例如，如果 Electron 是 URL 的默认处理程序，这在 Windows 和 Mac 上可能是 Electron。但是，不要依赖精确的格式，它不保证保持不变。在 Linux 上，格式可能会有所不同，可能带有 .desktop 后缀。

此方法返回 URL 协议 (也称为 URI 方案) 默认处理程序的应用程序名称。

`app.getApplicationInfoForProtocol(url)` macOS Windows

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

Returns Promise<Object> - 解析为一个包含以下内容的对象

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

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

`app.setUserTasks(tasks)` Windows

tasks Task[] - Task 对象数组

将 tasks 添加到 Windows Jump List 的任务类别中。

tasks 是一个 Task 对象数组。

Returns boolean - 调用是否成功。

注意

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

`app.getJumpListSettings()` Windows

Returns Object

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

`app.setJumpList(categories)` Windows

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

Returns 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> (optional) - 一个包含要发送给第一实例的附加数据的 JSON 对象。

Returns 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()`

Returns boolean

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

`app.releaseSingleInstanceLock()`

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

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

type string - 唯一标识活动。映射到 NSUserActivity.activityType。
userInfo any - 供其他设备使用的特定于应用程序的状态。
webpageURL string (optional) - 如果恢复设备上没有安装合适的应用程序，则在浏览器中加载的网页。方案必须是 http 或 https。

创建一个 NSUserActivity 并将其设置为当前活动。该活动随后有资格进行 Handoff 到另一设备。

`app.getCurrentActivityType()` macOS

Returns 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 (optional) - 是否优先使用内置主机解析器而不是 getaddrinfo。启用时，内置解析器将尝试使用系统的 DNS 设置进行 DNS 查找。macOS 上默认启用，Windows 和 Linux 上默认禁用。
- enableHappyEyeballs boolean (optional) - 在创建网络连接时是否应使用 Happy Eyeballs V3 算法。启用时，解析到多个 IP 地址的主机名将并行尝试，以更快地建立连接。
- secureDnsMode string (optional) - 可以是 'off'、'automatic' 或 'secure'。配置 DNS-over-HTTP 模式。当设置为 'off' 时，将不执行任何 DoH 查找。当设置为 'automatic' 时，如果 DoH 可用，将首先执行 DoH 查找，不安全的 DNS 查找将作为回退执行。当设置为 'secure' 时，将只执行 DoH 查找。默认为 'automatic'。
- secureDnsServers string[] (optional) - DNS-over-HTTP 服务器模板列表。有关模板格式的详细信息，请参阅 RFC8484 § 3。大多数服务器支持 POST 方法；此类服务器的模板只是一个 URI。请注意，对于某些 DNS 提供商，解析器将自动升级到 DoH，除非 DoH 被明确禁用，即使此列表中未提供任何 DoH 服务器。
- enableAdditionalDnsQueryTypes boolean (optional) - 控制当通过不安全 DNS 发出请求时，除了传统的 A 和 AAAA 查询之外，是否允许额外的 DNS 查询类型 (例如 HTTPS (DNS 类型 65))。对安全 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'
    ]
  })
})

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

`app.disableHardwareAcceleration()`

禁用当前应用程序的硬件加速。

此方法只能在应用程序准备就绪之前调用。

`app.disableDomainBlockingFor3DAPIs()`

默认情况下，如果 GPU 进程崩溃过于频繁，Chromium 会在每个域的基础上禁用 3D API (例如 WebGL)，直到重启。此函数禁用该行为。

此方法只能在应用程序准备就绪之前调用。

`app.getAppMetrics()`

Returns ProcessMetric[]: ProcessMetric 对象数组，对应于与应用程序关联的所有进程的内存和 CPU 使用情况统计信息。

`app.getGPUFeatureStatus()`

Returns GPUFeatureStatus - 来自 chrome://gpu/ 的图形功能状态。

注意

此信息只能在 gpu-info-update 事件发出后使用。

`app.getGPUInfo(infoType)`

infoType string - 可以是 basic 或 complete。

Returns 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 (optional) - 如果提供值，则将徽章设置为提供的值，否则，在 macOS 上显示一个纯白色圆点 (例如，未知数量的通知)。在 Linux 上，如果未提供值，则徽章将不显示。

Returns boolean - 调用是否成功。

为当前应用程序设置计数器徽章。将计数设置为 0 将隐藏徽章。

在 macOS 上，它显示在 Dock 图标上。在 Linux 上，它仅适用于 Unity 启动器。

注意

Unity 启动器需要一个 .desktop 文件才能工作。有关更多信息，请阅读 Unity 集成文档。

注意

在 macOS 上，你需要确保应用程序具有显示通知的权限才能使此方法工作。

`app.getBadgeCount()` Linux macOS

Returns Integer - 计数器徽章中显示的当前值。

`app.isUnityRunning()` Linux

Returns boolean - 当前桌面环境是否为 Unity 启动器。

`app.getLoginItemSettings([options])` macOS Windows

options Object (optional)
- type string (optional) macOS - 可以是 mainAppService、agentService、daemonService 或 loginItemService 之一。默认为 mainAppService。仅在 macOS 13 及更高版本上可用。有关每种类型的更多信息，请参阅 app.setLoginItemSettings。
- serviceName string (optional) macOS - 服务名称。如果 type 非默认，则必需。仅在 macOS 13 及更高版本上可用。
- path string (optional) Windows - 用于比较的可执行文件路径。默认为 process.execPath。
- args string[] (optional) Windows - 用于比较的命令行参数。默认为一个空数组。

如果你为 app.setLoginItemSettings 提供了 path 和 args 选项，那么你需要在此处传递相同的参数，以便正确设置 openAtLogin。

Returns Object

openAtLogin boolean - 如果应用程序设置为登录时打开则为 true。
openAsHidden boolean macOS Deprecated - 如果应用程序设置为在登录时以隐藏方式打开，则为true。此功能在 macOS 13 及更高版本上不起作用。
wasOpenedAtLogin boolean macOS - 如果应用程序在登录时自动打开，则为true。
wasOpenedAsHidden boolean macOS Deprecated - 如果应用程序作为隐藏的登录项打开，则为true。这表示应用程序在启动时不应打开任何窗口。此设置不适用于 MAS 构建版本或 macOS 13 及更高版本。
restoreState boolean macOS Deprecated - 如果应用程序作为登录项打开，并且应恢复上次会话的状态，则为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 Deprecated - 设置为 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 (optional) 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 boolean - 启用或禁用可访问性树渲染。

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

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

注意

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

`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 将按此顺序在 NSBundle 类方法 main 返回的 bundle 中查找名为 "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 (optional)
- 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> - 当代理设置过程完成时解析。

为未关联 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` Readonly

一个 CommandLine 对象，允许您读取和操作 Chromium 使用的命令行参数。

`app.dock` macOS Readonly

一个 Dock | undefined 属性（在 macOS 上是 Dock，在所有其他平台上是 undefined），允许您在用户的 Dock 中对应用程序图标执行操作。

`app.isPackaged` Readonly

一个 boolean 属性，如果应用程序已打包，则返回 true，否则返回 false。对于许多应用程序，此属性可用于区分开发和生产环境。

`app.name`

一个 string 属性，指示当前应用程序的名称，即应用程序 package.json 文件中的名称。

`app.userAgentFallback`

一个 string，它是 Electron 将用作全局回退的用户代理字符串。

当 webContents 或 session 级别未设置用户代理时，将使用此用户代理。它有助于确保您的整个应用程序具有相同的用户代理。在应用程序初始化时尽早将其设置为自定义值，以确保使用您的覆盖值。

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