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 或 UNNotificationResponse 的 userInfo。您还可以调用 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()。

只有具有与活动源应用程序相同的开发者 Team 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 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 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 - true 当 Chrome 的辅助功能支持启用时，否则为 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 初始化后完成。如果应用程序尚未准备好，可以用作检查 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 每个用户的应用程序数据目录，默认情况下指向
  - %APPDATA% 在 Windows 上
  - $XDG_CONFIG_HOME 或 ~/.config 在 Linux 上
  - ~/Library/Application Support 在 macOS 上
- 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。

获取路径关联的图标。

在 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 的路径。

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

`app.getVersion()`

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

`app.getName()`

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

通常，package.json 的 name 字段是一个简短的小写名称，符合 npm 模块规范。通常也应指定一个 productName 字段，即您的应用程序的完整大写名称，Electron 将优先使用 productName 而不是 name。

`app.setName(name)`

name string

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

注意

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

`app.getLocale()`

返回 string - 当前应用程序区域设置，使用 Chromium 的 l10n_util 库获取。可能的返回值记录此处。

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

注意

在分发打包的应用程序时，您还必须运送 locales 文件夹。

注意

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

注意

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

`app.getLocaleCountryCode()`

返回 string - 用户操作系统区域设置的两位字母 ISO 3166 国家/地区代码。该值来自本机操作系统 API。

注意

如果无法检测到区域设置国家/地区代码，则返回空字符串。

`app.getSystemLocale()`

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

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

Windows 11 使用区域格式来设置数字、日期和时间。
macOS Monterey 使用区域设置来设置数字、日期、时间的格式，以及选择要使用的货币符号。

因此，此 API 可用于诸如在日历应用程序中选择日期和时间呈现格式之类的目的，尤其是在开发人员希望格式与操作系统一致时。

注意

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

注意

要查看此 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 (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 Store 环境中（打包为 appx 时），此 API 将对所有调用返回 true，但它设置的注册表键将无法被其他应用程序访问。为了将您的 Windows Store 应用程序注册为默认协议处理程序，您必须在您的清单中声明协议。

该 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 类别。

tasks 是 Task 对象的数组。

Returns 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 对象的数组。

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 中打开应用程序的第二个实例时，系统会自动强制单实例。但是，当用户在命令行中启动您的应用程序时，系统的单实例机制将被绕过，您必须使用此方法来确保单实例。

当第二个实例启动时激活主实例窗口的示例

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 并将其设置为当前活动。之后，该活动有资格进行接力到另一台设备。

`app.getCurrentActivityType()` macOS

返回 string - 当前正在运行的活动的类型。

`app.invalidateCurrentActivity()` macOS

使当前接力用户活动失效。

`app.resignCurrentActivity()` macOS

将当前接力用户活动标记为非活动状态，而不使其失效。

`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，值为 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 进行请求时是否允许额外的 DNS 查询类型，例如 HTTPS (DNS 类型 65)，除了传统的 A 和 AAAA 查询之外。对 Secure DNS 没有影响，Secure 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.isHardwareAccelerationEnabled()`

返回 boolean - 当前是否启用了硬件加速。

注意

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

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

Returns boolean - 调用是否成功。

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

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

注意

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

注意

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

`app.getBadgeCount()` Linux macOS

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

`app.isUnityRunning()` Linux

返回 boolean - 当前桌面环境是否为 Unity launcher。

`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 - true 表示应用程序注册表键已启动批准，因此在任务管理器和 Windows 设置中显示为 enabled。

`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 boolean - 启用或禁用辅助功能树渲染

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

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

注意

渲染辅助功能树会显著影响应用程序的性能。不应默认启用它。调用此方法将启用以下辅助功能支持功能：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 (optional) Linux Windows - 应用图标的路径，JPEG 或 PNG 格式。在 Linux 上，将显示为 64x64 像素，同时保留纵横比。在 Windows 上，48x48 PNG 将产生最佳的视觉质量。

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

如果您没有设置 credits（鸣谢），但仍然希望在您的应用中显示它们，AppKit 将查找名为 "Credits.html"、"Credits.rtf" 和 "Credits.rtfd" 的文件，按此顺序，在 NSBundle 类方法 main 返回的 bundle 中。找到的第一个文件将被使用，如果未找到任何文件，信息区域将保持空白。有关更多信息，请参阅 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> (optional) - 移动失败时的处理程序。
  - 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> - 解析为将用于尝试使用 Net 在实用程序进程中进行请求的 url 的代理信息。

`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，则返回 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` 只读 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.isHardwareAccelerationEnabled()​

app.disableDomainBlockingFor3DAPIs()​

app.getAppMetrics()​

事件

事件: '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.isHardwareAccelerationEnabled()`

`app.disableDomainBlockingFor3DAPIs()`

`app.getAppMetrics()`