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。

[!NOTE] ready 事件只有在主进程完成事件循环的第一个 tick 之后才会触发。如果需要在 ready 事件之前调用某个 Electron API，请确保在主进程的顶层上下文中同步调用它。

事件：'window-all-closed'¶

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

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

事件：'before-quit'¶

返回：

• event Event

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

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

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

事件：'will-quit'¶

返回：

• event Event

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

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

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

事件：'quit'¶

返回：

• event Event
• exitCode Integer

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

[!NOTE] 在 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（可选）- 如果可用，标识该活动在另一台设备上访问的网页 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 时，新标签按钮才可见。

必须在此处理程序中创建一个窗口，才能使 macOS 标签页功能按预期工作。

事件：'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 | null
• url URL
• certificateList Certificate[]
• callback Function
• certificate Certificate（可选）

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

url 对应请求客户端证书的导航条目，callback 可以使用从列表中筛选出的条目调用。使用 event.preventDefault() 可阻止应用使用证书存储中的第一个证书。

webContents 在请求不源自渲染进程时为 null，例如在主进程中使用 net.request 或 net.fetch，或源自使用 respondToAuthRequestsFromMainProcess: true 创建的 utility process。对于未使用该标志创建的 utility process，net 请求将继续而不使用客户端证书，并且不会发出此事件。

const { app } = require('electron')

app.on('select-client-certificate', (event, webContents, url, list, callback) => {
  event.preventDefault()
  callback(list[0])
})

事件：'login'¶

返回值：

• event Event
• webContents WebContents | null
• authenticationResponseDetails Object
• url URL
• pid number
• isRequestForNavigation boolean - 指示请求是否用于导航。
• firstAuthAttempt boolean - 指示这是否是第一次身份验证尝试。
• responseHeaders Record\<string, string | string[]>（可选）- 响应中返回的标头。
• 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 (optional) - 进程的非本地化名称。
• name string (optional) - 进程的名称。 utility 的示例：Audio Service、Content Decryption Module Service、Network Service、Video Capture 等。

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

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

返回值：

• event Event
• accessibilitySupportEnabled boolean - 当 Chromium 的辅助功能支持启用时为 true，否则为 false。

当 Chromium 的辅助功能支持发生变化时发出。当辅助技术（例如屏幕阅读器）启用或禁用时，此事件会触发。 有关更多详细信息，请参阅 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 是其当前工作目录。通常， 应用程序会通过使其主窗口获得焦点且未最小化来响应此操作。

[!NOTE] argv 不会与传递给第二个实例的参数列表完全相同。 顺序可能会改变，并且可能会追加额外参数。 如果需要保持完全相同的参数，建议使用 additionalData。

[!NOTE] 如果第二个实例由与第一个实例不同的用户启动，则 argv 数组将不包含这些参数。

保证在 app 的 ready 事件发出后发出此事件。

[!NOTE] Chromium 可能会添加额外的命令行参数， 例如 --original-process-start-time。

方法¶

app 对象具有以下方法：

[!NOTE] 某些方法仅在特定操作系统上可用，并会相应标注。

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()¶

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

app.whenReady()¶

返回 Promise<void> - 当 Electron 初始化完成时完成。 如果应用尚未就绪，可作为检查 app.isReady() 并订阅 ready 事件的便捷替代方式。

app.focus([options])¶

• options Object（可选）
• steal boolean macOS - 即使当前有另一个应用处于活动状态，也强制该应用成为活动应用。

在 macOS 上，使应用成为活动应用。在 Windows 上，聚焦到应用的第一个窗口。在 Linux 上，要么聚焦到第一个可见窗口（X11），要么请求焦点，但也可能改为显示通知或闪烁应用图标（Wayland）。

应尽可能少地使用 steal 选项。

app.isActive() macOS¶

返回 boolean - 如果应用处于活动状态（即已聚焦），则为 true。

app.hide() macOS¶

隐藏所有应用窗口，但不将它们最小化。

app.isHidden() macOS¶

返回 boolean - 如果应用（包括其所有窗口）已被隐藏（例如通过 Command-H），则为 true，否则为 false。

app.show() macOS¶

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

app.setAppLogsPath([path])¶

• path string（可选）- 日志的自定义路径。必须是绝对路径。

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

在不提供 path 参数的情况下调用 app.setAppLogsPath()，会将该目录设置为 macOS 上的 ~/Library/Logs/YourAppName，以及 Linux 和 Windows 上 userData 目录内的位置。

app.getAppPath()¶

返回 string - 当前应用目录。

app.getPath(name)¶

• name string - 可以通过以下名称请求相应路径：
• home 用户主目录。
• appData 每个用户的应用数据目录，默认指向：
  • Windows 上的 %APPDATA%
  • Linux 上的 $XDG_CONFIG_HOME 或 ~/.config
  • macOS 上的 ~/Library/Application Support
• assets 存储应用资源（如 resources.pak）的目录。默认与包含 exe 路径的文件夹相同。仅在 Windows 和 Linux 上可用。
• userData 用于存储应用配置文件的目录，默认是在 appData 目录后附加应用名称。按照惯例，存储用户数据的文件应写入此目录，但不建议在此写入大文件，因为某些环境可能会将此目录备份到云存储。建议将应用特定文件存储在 userData 的子目录中（例如 path.join(app.getPath('userData'), 'my-app-data')），而不是直接存储在 userData 本身中，以避免与 Chromium 自身的子目录（如 Cache、GPUCache 和 Local Storage）发生命名冲突。
• sessionData 用于存储由 Session 生成的数据的目录，例如 localStorage、cookies、磁盘缓存、已下载的词典、网络状态、DevTools 文件。默认指向 userData。Chromium 可能会在此写入非常大的磁盘缓存，因此如果你的应用不依赖 localStorage 或 cookies 等浏览器存储来保存用户数据，建议将此目录设置为其他位置，以避免污染 userData 目录。
• temp 临时目录。
• exe 当前可执行文件。
• module Chromium 模块的位置。默认与 exe 同义。
• desktop 当前用户的桌面目录。
• documents 用户的 “My 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 上，有 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()¶

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

app.getName()¶

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

通常，根据 npm 模块规范，package.json 的 name 字段是一个简短的小写名称。通常还应指定 productName 字段，它是应用的完整大写名称，并且 Electron 会优先使用它而不是 name。

app.setName(name)¶

• name string

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

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

app.setDesktopName(name) Linux¶

• name string - .desktop 文件名（例如 'com.example.MyApp.desktop'）。

在 Linux 上设置 .desktop 文件名。 它必须与应用程序已安装的 .desktop 文件的基础文件名匹配。.desktop 后缀是可选的。

名称（不含 .desktop 后缀）是应用程序在 Linux 桌面集成中的标识。 它应遵循桌面条目命名约定，采用反向 DNS 风格的 ID，例如 com.example.MyApp。 此值用作：

• Wayland 上的 XDG 应用程序 ID（app_id）以及 X11 上的 WM_CLASS，用于匹配应用程序图标和窗口分组。
• xdg-desktop-portal 向门户后端（例如 GlobalShortcuts）报告的应用程序 ID。

门户越来越多地强制要求此标识。如果名称不是有效的反向 DNS ID，或与已安装的 .desktop 文件不匹配：

• GNOME 50.0/50.1（Ubuntu 26.04）会以 org.freedesktop.portal.Error.NotAllowed 拒绝 globalShortcut 绑定，并且不会向应用程序暴露错误（参见 #52218）。
• xdg-desktop-portal 1.21 及更高版本会拒绝无法解析到 .desktop 文件的应用程序 ID 的门户会话。

如果未设置此值，且 package.json 中不存在 desktopName，Electron 会回退到应用程序名称的小写连字符 slug（例如 My App → my-app.desktop），这不太可能成为有效的门户标识——打包的应用程序应始终显式设置它。

此 API 必须在 ready 事件之前调用。也可以使用 package.json 中的 desktopName 设置该值。

app.getLocale()¶

返回 string - 当前应用程序的语言环境，使用 Chromium 的 l10n_util 库获取。 可能的返回值记录在此处。

若要设置语言环境，需要在应用程序启动时使用命令行开关，可在此处找到。

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

[!NOTE] 此 API 必须在 ready 事件发出后调用。

[!NOTE] 若要查看此 API 与其他语言环境和语言 API 相比的示例返回值，请参见 app.getPreferredSystemLanguages()。

app.getLocaleCountryCode()¶

返回 string - 用户操作系统的语言环境两位 ISO 3166 国家/地区代码。该值取自原生操作系统 API。

[!NOTE] 当无法检测语言环境国家/地区代码时，返回空字符串。

app.getSystemLocale()¶

返回 string - 当前系统语言环境。在 Windows 和 Linux 上，使用 Chromium 的 i18n 库获取。在 macOS 上，则使用 [NSLocale currentLocale]。若要获取用户当前的系统语言（它并不总是与语言环境相同），最好使用 app.getPreferredSystemLanguages()。

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

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

因此，此 API 可用于选择日历应用中渲染日期和时间的格式等用途，尤其是在开发者希望格式与操作系统保持一致时。

[!NOTE] 此 API 必须在 ready 事件发出后调用。

[!NOTE] 若要查看此 API 与其他语言环境和语言 API 相比的示例返回值，请参见 app.getPreferredSystemLanguages()。

app.getPreferredSystemLanguages()¶

返回 string[] - 用户首选的系统语言，按从最偏好到最不偏好的顺序排列，如适用则包含国家/地区代码。用户可以在 Windows 或 macOS 上通过“语言与区域”设置修改和添加此列表。

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

此 API 可用于决定以何种语言呈现应用程序等用途。

以下是不同配置下各种语言和语言环境 API 返回值的一些示例：

在 Windows 上，假设应用程序语言环境为德语，区域格式为芬兰语（芬兰），首选系统语言从最偏好到最不偏好依次为法语（加拿大）、英语（美国）、简体中文（中国）、芬兰语和西班牙语（拉丁美洲）：

app.getLocale() // 'de'
app.getSystemLocale() // 'fi-FI'
app.getPreferredSystemLanguages() // ['fr-CA', 'en-US', 'zh-Hans-CN', 'fi', 'es-419']

在 macOS 上，假设应用程序语言环境为德语，区域为芬兰，首选系统语言从最偏好到最不偏好依次为法语（加拿大）、英语（美国）、简体中文和西班牙语（拉丁美洲）：

app.getLocale() // 'de'
app.getSystemLocale() // 'fr-FI'
app.getPreferredSystemLanguages() // ['fr-CA', 'en-US', 'zh-Hans-FI', 'es-419']

两种操作系统可用的语言和区域以及可能的返回值均有所不同。

如上例所示，在 Windows 上，首选系统语言可能没有国家/地区代码，并且其中一个首选系统语言可能与用于区域格式的语言相对应。在 macOS 上，区域更多充当默认国家/地区代码：用户无需将芬兰语设为首选语言即可使用芬兰作为区域，并且国家/地区代码 FI 会被用作语言名称中未关联国家/地区的首选系统语言的国家/地区代码。

app.addRecentDocument(path) macOS Windows¶

• path 字符串

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

此列表由操作系统管理。在 Windows 上，你可以从任务栏访问该列表；在 macOS 上，你可以从 Dock 菜单访问它。

app.clearRecentDocuments() macOS Windows¶

清除最近文档列表。

app.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 字符串 - 你的协议名称，不包含 ://。例如， 如果你想让你的应用处理 electron:// 链接，请调用此方法并传入 electron 作为参数。
• path 字符串（可选） Windows - Electron 可执行文件的路径。 默认为 process.execPath
• args 字符串数组（可选） Windows - 传递给可执行文件的参数。 默认为空数组

返回 boolean - 调用是否成功。

将当前可执行文件设置为协议（也称为 URI scheme）的默认处理程序。它允许你将应用更深入地集成到操作系统中。 注册后，所有带有 your-protocol:// 的链接都将使用当前可执行文件打开。 整个链接，包括协议，将作为参数传递给你的应用程序。

[!NOTE] 在 macOS 上，你只能注册已添加到 你的应用的 info.plist 中的协议，该文件无法在运行时修改。但是，你可以在 构建时通过 Electron Forge、 Electron Packager 或使用文本编辑器编辑 info.plist 来更改该文件。 详情请参阅 Apple 的文档。

[!NOTE] 在 Windows Store 环境中（当打包为 appx 时），此 API 对所有调用都会返回 true，但它设置的注册表项对其他应用程序不可访问。 要将你的 Windows Store 应用注册为默认协议处理程序，你必须在清单中声明协议。

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

app.removeAsDefaultProtocolClient(protocol[, path, args]) macOS Windows¶

• protocol 字符串 - 你的协议名称，不包含 ://。
• path 字符串（可选） Windows - 默认为 process.execPath
• args 字符串数组（可选） Windows - 默认为空数组

返回 boolean - 调用是否成功。

此方法检查当前可执行文件是否为协议（也称为 URI scheme）的默认处理程序。 如果是，它将移除该应用作为默认处理程序的设置。

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

• protocol 字符串 - 你的协议名称，不包含 ://。
• path 字符串（可选） Windows - 默认为 process.execPath
• args 字符串数组（可选） Windows - 默认为空数组

返回 boolean - 当前可执行文件是否为协议（也称为 URI scheme）的默认处理程序。

[!NOTE] 在 macOS 上，你可以使用此方法检查应用是否已 注册为某个协议的默认协议处理程序。你还可以通过检查 macOS 机器上的 ~/Library/Preferences/com.apple.LaunchServices.plist 来验证 此设置。详情请参阅 Apple 的文档。

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

app.getApplicationNameForProtocol(url)¶

• url 字符串 - 一个包含要检查的协议名称的 URL。与 此系列中的其他方法不同，此方法接受完整的 URL，至少包含 :// （例如 https://）。

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

此方法返回 URL 的协议（也称为 URI scheme）默认处理程序的应用程序名称。

app.getApplicationInfoForProtocol(url)¶

• url 字符串 - 一个包含要检查的协议名称的 URL。与 此系列中的其他方法不同，此方法接受完整的 URL，至少包含 :// （例如 https://）。

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

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

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

app.setUserTasks(tasks) Windows¶

• tasks Task[] - Task 对象数组

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

tasks 是 Task 对象数组。

返回 boolean - 调用是否成功。

[!NOTE] 如果你想进一步自定义 Jump List，请改用 app.setJumpList(categories)。

app.getJumpListSettings() Windows¶

返回 Object：

• minItems 整数 - 将在 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 管理）替换。

[!NOTE] 如果 JumpListCategory 对象既未设置 type 属性，也未设置 name 属性，则假定其 type 为 tasks。如果设置了 name 属性但省略了 type 属性，则假定 type 为 custom。

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

[!NOTE] 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 事件。但是，当用户通过命令行启动你的应用程序时，系统的单实例机制会被绕过，你必须使用此方法来确保单实例。

[!NOTE] 在 macOS 和 Linux 上，第二个实例的命令行参数和 additionalData 会在一条限制为 32 MB 的消息中发送到主要实例。更大的消息会被丢弃：此方法仍会返回 false，但主要实例不会发出 second-instance。

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

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://electronjs.org')
  })
}

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

将 Application User Model ID 更改为 id。

app.setToastActivatorCLSID(id) Windows¶

• id string

将 Toast Activator CLSID 更改为 id。如果未通过此方法设置，则会为应用随机生成一个。

• 该值必须是以下形式之一的有效 GUID/CLSID：
• 带花括号的规范形式：{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}（推荐）
• 不带花括号的规范形式：XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX（将自动添加花括号）
• 十六进制数字不区分大小写。

应尽早调用此方法（在显示通知之前），以便将该值固化到注册/快捷方式中。提供空字符串或无法解析的值会抛出异常，并保持现有（或生成的）CLSID 不变。如果从未调用此方法，则每次运行会生成一个随机 CLSID，并通过 app.toastActivatorCLSID 暴露。

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（可选） - 控制当通过不安全 DNS 发出请求时，是否允许除传统 A 和 AAAA 查询之外的其他 DNS 查询类型，例如 HTTPS（DNS 类型 65）。对 Secure DNS 没有影响，Secure DNS 始终允许其他类型。默认为 true。

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

1. DNS-over-HTTPS（如果 DNS 提供商支持它），然后
2. 内置解析器（默认仅在 macOS 上启用），然后
3. 系统解析器（例如 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.configureWebAuthn(options) macOS¶

[!IMPORTANT] 在 macOS 上，你的应用应经过代码签名和公证，登录项设置才能可靠工作。当应用未打包、代码签名和公证时，openAtLogin 可能会静默地无法生效。

• settings Object
• openAtLogin boolean (optional) - true 表示在登录时打开应用，false 表示将应用从登录项中移除。默认为 false。
• type string (optional) macOS - 要作为登录项添加的服务类型。默认为 mainAppService。
  • mainAppService - 主应用程序。
  • agentService - 启动代理（launch agent）的属性列表名称。该名称必须与应用 Contents/Library/LaunchAgents 目录中的某个属性列表对应。
  • daemonService string (optional) macOS - 启动守护程序（launch daemon）的属性列表名称。该名称必须与应用 Contents/Library/LaunchDaemons 目录中的某个属性列表对应。
  • loginItemService string (optional) macOS - 登录项服务的属性列表名称。该名称必须与应用 Contents/Library/LoginItems 目录中的某个属性列表对应。
• serviceName string (optional) macOS - 服务的名称。如果 type 不是默认值，则为必填项。
• path string (optional) Windows - 登录时要启动的可执行文件。默认为 process.execPath。
• args string[] (optional) Windows - 要传递给可执行文件的命令行参数。默认为空数组。注意将路径用引号括起来。
• enabled boolean (optional) Windows - true 将更改启动批准的注册表项，并在任务管理器和 Windows 设置中 enable / disable 应用。默认为 true。
• name string (optional) Windows - 要写入注册表的值名称。默认为应用的 AppUserModelId()。

设置应用的登录项设置。

为了在 Windows 上与 Electron 的 autoUpdater（使用 Squirrel）配合使用，你需要将启动路径设置为可执行文件的名称，但位于其上一级目录；该位置是 Squirrel 自动生成的存根（stub）应用程序，它会自动启动最新版本。

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 上将不同服务设置为登录项的更多信息，请参阅 SMAppService。

app.isAccessibilitySupportEnabled() macOS Windows¶

返回 boolean - 如果 Chromium 的辅助功能支持已启用，则为 true，否则为 false。如果检测到使用了辅助技术（例如屏幕阅读器），此 API 将返回 true。更多详情请参阅 https://www.chromium.org/developers/design-documents/accessibility。

app.setAccessibilitySupportEnabled(enabled) macOS Windows¶

• enabled boolean - 启用或禁用辅助功能树渲染

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

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

[!NOTE] 渲染辅助功能树可能会显著影响应用性能。默认不应启用。调用此方法将启用以下辅助功能支持特性：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 将按照顺序在 NSBundle 类方法 main 返回的包中查找名为 "Credits.html"、"Credits.rtf" 和 "Credits.rtfd" 的文件。将使用找到的第一个文件；如果未找到任何文件，则信息区域将保持空白。有关更多信息，请参阅 Apple 文档。

app.isEmojiPanelSupported()¶

返回 boolean - 当前操作系统版本是否允许使用原生表情符号选择器。

app.showEmojiPanel() macOS Windows¶

显示平台的原生表情符号选择器。

app.startAccessingSecurityScopedResource(bookmarkData) mas¶

• bookmarkData string - 由 dialog.showOpenDialog 或 dialog.showSaveDialog 方法返回的 base64 编码的安全作用域书签数据。

返回 Function - 完成访问安全作用域文件后，必须调用此函数。如果你忘记停止访问书签，内核资源将会泄漏，并且你的应用程序将完全失去访问沙盒外部的能力，直到应用程序重启。

const { app, dialog } = require('electron')

const fs = require('node:fs')

let filepath
let bookmark

dialog.showOpenDialog(null, { securityScopedBookmarks: true }).then(({ filePaths, bookmarks }) => {
  filepath = filePaths[0]
  bookmark = bookmarks[0]
  fs.readFileSync(filepath)
})

// ... restart app ...

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

开始访问安全作用域资源。使用此方法，为 Mac App Store 打包的 Electron 应用程序可以访问沙盒外部，以访问用户选择的文件。有关此系统工作原理的说明，请参阅 Apple 文档。

app.enableSandbox()¶

在应用程序上启用完整沙盒模式。这意味着所有渲染器都将以沙盒方式启动，无论 WebPreferences 中 sandbox 标志的值如何。

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

app.isInApplicationsFolder() macOS¶

返回 boolean - 应用程序当前是否正在从系统的“应用程序”文件夹中运行。与 app.moveToApplicationsFolder() 结合使用。

app.moveToApplicationsFolder([options]) macOS¶

• options Object（可选）
• conflictHandler Function\（可选）- 用于处理移动失败时潜在冲突的处理程序。
  • conflictType string - 处理程序遇到的移动冲突类型；可以是 exists 或 existsAndRunning，其中 exists 表示应用程序目录中已存在同名应用程序，existsAndRunning 表示该应用程序既已存在又正在运行。

返回 boolean - 移动是否成功。请注意，如果移动成功，你的应用程序将退出并重新启动。

默认情况下不会显示确认对话框。如果你希望允许用户确认该操作，可以使用 dialog API 来实现。

注意： 如果移动失败是由用户以外的原因造成的，此方法会抛出错误。例如，如果用户取消授权对话框，此方法返回 false。如果无法执行复制，则此方法会抛出错误。错误中的消息应提供信息，并准确告知出了什么问题。

默认情况下，如果 Applications 目录中已经存在一个与正在移动的应用同名的应用，并且 未 在运行，现有应用将被移到废纸篓，活动应用将被移动到其位置。如果它 正在 运行，先前正在运行的应用将获得焦点，之前活动的应用将自行退出。可以通过提供可选的冲突处理程序来更改此行为，其中处理程序返回的布尔值决定移动冲突是否以默认行为解决。即返回 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 - 是否启用了 Secure Keyboard Entry。

默认情况下，此 API 将返回 false。

app.setSecureKeyboardEntryEnabled(enabled) macOS¶

• enabled boolean - 启用或禁用 Secure Keyboard Entry

在您的应用程序中设置是否启用 Secure Keyboard Entry。

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

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

[!NOTE] 仅在需要时启用 Secure Keyboard Entry，并在不再需要时禁用它。

app.setProxy(config)¶

• config ProxyConfig

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

为没有关联 Session 的网络请求设置代理设置。 目前，这将影响在 utility process 中使用 Net 发出的请求，以及运行时发出的内部请求（例如：地理位置查询）。

此方法只能在 app 就绪后调用。

app.resolveProxy(url)¶

• url URL

返回 Promise<string> - 解析为 url 的代理信息，该信息将在尝试使用 utility process 中的 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 属性，如果启用了 Chromium 的无障碍支持，则为 true，否则为 false。如果检测到使用了辅助技术（例如屏幕阅读器），此属性将为 true。将此属性设置为 true 可手动启用 Chromium 的无障碍支持，使开发者能够在应用设置中向用户暴露无障碍开关。

有关更多详细信息，请参阅 Chromium 的无障碍文档。默认禁用。

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

[!NOTE] 渲染无障碍树可能会显著影响应用的性能。不应默认启用它。

app.applicationMenu¶

一个 Menu | null 属性，如果已设置则返回 Menu，否则返回 null。 用户可以传入 Menu 来设置此属性。

app.badgeCount Linux macOS¶

一个 Integer 属性，返回当前应用的徽章计数。将计数设置为 0 会隐藏徽章。使用任何非零整数设置此属性会在 macOS 的 Dock 图标或 Linux 的启动器上显示计数。

[!NOTE] 在 macOS 上，你需要确保应用具有显示通知的权限，此属性才能生效。

app.commandLine Readonly¶

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

app.dock macOS Readonly¶

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

app.isPackaged Readonly¶

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

app.toastActivatorCLSID Windows 只读¶

一个 string 属性，返回应用的 Toast Activator CLSID。

app.name¶

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

通常，package.json 中的 name 字段是一个简短的小写名称，遵循 npm 模块规范。通常还应指定 productName 字段，它是应用程序的完整大写名称，Electron 会优先使用它而不是 name。

app.userAgentFallback¶

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

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

app.runningUnderARM64Translation 只读 macOS Windows¶

一个 boolean，当为 true 时，表示应用当前正在 ARM64 翻译器下运行（例如 macOS 的 Rosetta Translator Environment 或 Windows 的 WOW）。

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