app

控制应用程序的事件生命周期。

进程：主进程

下面的这个例子将会展示如何在最后一个窗口被关闭时退出应用：

  1. const { app } = require('electron')
  2. app.on('window-all-closed', () => {
  3.   app.quit()
  4. })

事件

app 对象会发出以下事件:

事件: ‘will-finish-launching’

当应用程序完成基础的启动的时候被触发。 在 Windows 和 Linux 中, will-finish-launching 事件与 ready 事件是相同的; 在 macOS 中，这个事件相当于 NSApplication 中的 applicationWillFinishLaunching 提示。 通常会在这里为 open-file 和 open-url 设置监听器，并启动崩溃报告和自动更新。

绝大部分情况下，你必须在ready事件句柄中处理所有事务。

事件: ‘ready’

返回:

当 Electron 完成初始化时，发出一次。 On macOS, launchInfo holds the userInfo of the NSUserNotification or information from UNNotificationResponse that was used to open the application, if it was launched from Notification Center. You can also call app.isReady() to check if this event has already fired and app.whenReady() to get a Promise that is fulfilled when Electron is initialized.

事件: ‘window-all-closed’

当所有的窗口都被关闭时触发。

如果你没有监听此事件并且所有窗口都关闭了，默认的行为是控制退出程序；但如果你监听了此事件，你可以控制是否退出程序。 如果用户按下了 Cmd + Q，或者开发者调用了 app.quit()，Electron 会首先关闭所有的窗口然后触发 will-quit 事件，在这种情况下 window-all-closed 事件不会被触发。

事件：’before-quit’

返回:

  • event Event

在程序关闭窗口前发信号。 Calling event.preventDefault() will prevent the default behavior, which is terminating the application.

注意： 如果由 autoUpdater.quitAndInstal() 退出应用程序 ，那么在所有窗口触发 close 之后 才会触发 before-quit 并关闭所有窗口。

注:在 Windows 系统中，如果应用程序因系统关机/重启或用户注销而关闭，那么这个事件不会被触发。

事件: ‘will-quit’

返回:

  • event Event

Emitted when all windows have been closed and the application will quit. Calling event.preventDefault() will prevent the default behavior, which is terminating the application.

关于 window-all-closed 和 will-quit 事件之间的差异, 请参见 window-all-closed 事件的说明。

注:在 Windows 系统中，如果应用程序因系统关机/重启或用户注销而关闭，那么这个事件不会被触发。

事件: ‘quit’

返回:

  • event Event
  • exitCode Integer

在应用程序退出时发出。

注:在 Windows 系统中，如果应用程序因系统关机/重启或用户注销而关闭，那么这个事件不会被触发。

事件: ‘open-file’ macOS

返回:

  • event Event
  • path String

当用户想要在应用中打开一个文件时发出。 open-file 事件通常在应用已经打开，并且系统要再次使用该应用打开文件时发出。 open-file也会在一个文件被拖到 dock 并且还没有运行的时候发出。 请确认在应用启动的时候(甚至在 ready 事件发出前) 就对 open-file 事件进行监听。

如果你想处理这个事件，你应该调用 event.preventDefault() 。

在 Windows 系统中，你需要解析 process.argv (在主进程中) 来获取文件路径

事件: ‘open-url’ macOS

返回:

  • event Event
  • url String

当用户想要在应用中打开一个 URL 时发出。 Your application’s Info.plist file must define the URL scheme within the CFBundleURLTypes key, and set NSPrincipalClass to AtomApplication.

如果你想处理这个事件，你应该调用 event.preventDefault() 。

事件: ‘activate’ macOS

返回:

  • event Event
  • hasVisibleWindows Boolean

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

事件: ‘did-groupe-active’ macOS

返回:

  • event Event

当应用被激活时发出。 与 activate 事件的不同是应用，程序激活时都会触发 did-become-active ，而不仅仅在 Dock 图标被点击或应用程序被重新启动的时候。

事件: ‘continue-activity’ macOS

返回:

  • event Event
  • typeString-标识活动的字符串。 映射到 NSUserActivity. activityType。
  • userInfo unknown - Contains app-specific state stored by the activity on another device.

当来自不同设备的活动通过 Handoff 想要恢复时触发。 如果你想处理这个事件，你应该调用 event.preventDefault() 。

只有具有支持相应的活动类型并且相同的开发团队 ID 作为启动程序时，用户行为才会进行。 所支持活动类型已在应用的 Info.plist 中的 NSUserActivityTypes 里明确定义。

事件: ‘will-continue-activity’ macOS

返回:

当来自不同设备的活动通过 Handoff 恢复之前触发。 如果你想处理这个事件，你应该调用 event.preventDefault() 。

事件: ‘continue-activity-error’ macOS

返回:

当来自不同设备的活动通过 Handoff 恢复失败时触发。

事件: ‘activity-was-continued’ macOS

返回:

  • event Event
  • typeString-标识活动的字符串。 映射到 NSUserActivity. activityType。
  • userInfo unknown - Contains app-specific state stored by the activity.

当来自不同设备的活动通过 Handoff 成功恢复后触发。

事件: ‘update-activity-state’ macOS

返回:

  • event Event
  • typeString-标识活动的字符串。 映射到 NSUserActivity. activityType。
  • userInfo unknown - Contains app-specific state stored by the activity.

当 Handoff 即将通过另一个设备恢复时触发。 If you need to update the state to be transferred, you should call event.preventDefault() immediately, construct a new userInfo dictionary and call app.updateCurrentActivity() in a timely manner. 否则，操作会失败，并且触发 continue-activity-error

事件: ‘new-window-for-tab’ macOS

返回:

  • event Event

Emitted when the user clicks the native macOS new tab button. The new tab button is only visible if the current BrowserWindow has a tabbingIdentifier

事件: ‘browser-window-blur’

返回:

在 browserWindow 失去焦点时发出。

事件: ‘browser-window-focus’

返回:

在 browserWindow 获得焦点时发出。

事件: ‘browser-window-created’

返回:

在创建新的 browserWindow 时发出。

事件: ‘web-contents-created’

返回:

在创建新的 webContents 时发出。

事件: ‘certificate-error’

返回:

  • event Event
  • webContents WebContents
  • url String
  • error String - 错误码
  • certificate 证书
  • callback Function
    • isTrustedBoolean-是否将证书视为可信的

当对 url 的 certificate 证书验证失败的时候发出。如果需要信任这个证书，你需要阻止默认行为 event.preventDefault() 并且调用 callback(true)。

  1. const { app } = require('electron')
  3. app.on('certificate-error', (event, webContents, url, error, certificate, callback) => {
  4.   if (url === 'https://github.com') {
  5.     // Verification logic.
  6.     event.preventDefault()
  7.     callback(true)
  8.   } else {
  9.     callback(false)
  10.   }
  11. })

事件: ‘select-client-certificate’

返回:

当一个客户证书被请求的时候发出。

url 指的是请求客户端认证的网页地址，调用 callback 时需要传入一个证书列表中的证书。 需要通过调用 event.preventDefault() 来防止应用自动使用第一个证书进行验证。

  1. const { app } = require('electron')
  3. app.on('select-client-certificate', (event, webContents, url, list, callback) => {
  4.   event.preventDefault()
  5.   callback(list[0])
  6. })

事件: “login”

返回:

  • event Event
  • webContents WebContents
  • authenticationResponseDetails Object
    • url URL
  • authInfo Object
    • isProxy Boolean
    • scheme String
    • host String
    • port Integer
    • realm String
  • callback Function
    • username String (optional)
    • password String (optional)

当 webContents 要进行基本身份验证时触发。

默认行为是取消所有身份验证。 默认行为是取消所有的验证行为，如果需要重写这个行为，你需要用 event.preventDefault() 来阻止默认行为，并且使用 callback(username, password) 来验证。

  1. const { app } = require('electron')
  3. app.on('login', (event, webContents, details, authInfo, callback) => {
  4.   event.preventDefault()
  5.   callback('username', 'secret')
  6. })

If callback is called without a username or password, the authentication request will be cancelled and the authentication error will be returned to the page.

Event: ‘gpu-info-update’

Emitted whenever there is a GPU info update.

事件: ‘gpu-process-crashed’ 已废弃

返回:

  • event Event
  • killed Boolean

当gpu进程崩溃或关闭（杀死）时触发

已废弃：这个事件被包含更多子进程退出信息原因的child-process-gone事件取代了。 It isn’t always because it crashed. The killed boolean can be replaced by checking reason === 'killed' when you switch to that event.

事件: ‘renderer-process-crashed’ 已废弃

返回:

当渲染器进程webContents崩溃或关闭（杀死）时触发。

已废弃： 此事件被包含更多关于渲染过程为何消失的信息的 render-process-gone 事件替代了 It isn’t always because it crashed. The killed boolean can be replaced by checking reason === 'killed' when you switch to that event.

Event: ‘render-process-gone’

返回:

  • event Event
  • webContents WebContents
  • details Object
    • reason String - The reason the render process is gone. 可选值：
      • clean-exit - Process exited with an exit code of zero
      • abnormal-exit - Process exited with a non-zero exit code
      • killed - Process was sent a SIGTERM or otherwise killed externally
      • crashed - Process crashed
      • oom - Process ran out of memory
      • launch-failed - Process never successfully launched
      • integrity-failure - Windows code integrity checks failed
    • exitCode Integer - The exit code of the process, unless reason is launch-failed, in which case exitCode will be a platform-specific launch failure error code.

Emitted when the renderer process unexpectedly disappears. This is normally because it was crashed or killed.

Event: ‘child-process-gone’

返回:

  • event Event
  • details Object
    • type String - Process type. One of the following values:
      • Utility
      • Zygote
      • Sandbox helper
      • GPU
      • Pepper Plugin
      • Pepper Plugin Broker
      • Unknown
    • reason String - The reason the child process is gone. 可选值：
      • clean-exit - Process exited with an exit code of zero
      • abnormal-exit - Process exited with a non-zero exit code
      • killed - Process was sent a SIGTERM or otherwise killed externally
      • crashed - Process crashed
      • oom - Process ran out of memory
      • launch-failed - Process never successfully launched
      • integrity-failure - Windows code integrity checks failed
    • exitCode Number - The exit code for the process (e.g. status from waitpid if on posix, from GetExitCodeProcess on Windows).
    • serviceName String (optional) - The non-localized name of the process.
    • name String (optional) - The name of the process. Examples for utility: Audio Service, Content Decryption Module Service, Network Service, Video Capture, etc.

Emitted when the child process unexpectedly disappears. This is normally because it was crashed or killed. It does not include renderer processes.

事件: “accessibility-support-changed” macOS Windows

返回:

  • event Event
  • accessibilitySupportEnabled当启用了 Chrome 的辅助功能时为 true, 其他情况为 false。

当 Chrome 的辅助功能状态改变时触发。 当启用或禁用辅助技术时将触发此事件，例如屏幕阅读器 。 查看更多详情 https://www.chromium.org/developers/design-documents/accessibility

事件:’session-created’

返回:

当 Electron创建了一个新的 session后被触发.

  1. const { app } = require('electron')
  3. app.on('session-created', (session) => {
  4.   console.log(session)
  5. })

事件: ‘second-instance’

返回:

  • event Event
  • argv String[] - 第二个实例的命令行参数数组
  • workingDirectory String - 第二个实例的工作目录

当第二个实例被执行并且调用 app.requestSingleInstanceLock() 时，这个事件将在你的应用程序的首个实例中触发

argv 是第二个实例的命令行参数的数组, workingDirectory 是这个实例当前工作目录。 通常, 应用程序会激活窗口并且取消最小化来响应。

Note: If the second instance is started by a different user than the first, the argv array will not include the arguments.

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

注意： 额外命令行参数可能由 Chromium 添加， ，例如 --original-process-start-time。

事件: ‘desktop-capturer-get-sources’

返回:

Emitted when desktopCapturer.getSources() is called in the renderer process of webContents. Calling event.preventDefault() will make it return empty sources.

Event: ‘remote-require’ Deprecated

返回:

在 webContents 的渲染器进程中调用 remote.require() 时发出。 调用 event.preventDefault() 将阻止模块返回。 可以通过设置 event.returnValue 返回自定义值。

Event: ‘remote-get-global’ Deprecated

返回:

在 webContents 的渲染器进程中调用 remote.getGlobal() 时发出。 调用 event.preventDefault() 将阻止全局返回。 可以通过设置 event.returnValue 返回自定义值。

Event: ‘remote-get-builtin’ Deprecated

返回:

在 webContents 的渲染器进程中调用 remote.getBuiltin() 时发出。 调用 event.preventDefault() 将阻止模块返回。 可以通过设置 event.returnValue 返回自定义值。

Event: ‘remote-get-current-window’ Deprecated

返回:

在 webContents 的渲染器进程中调用 remote.getCurrentWindow() 时发出。 调用 event.preventDefault() 将阻止对象返回 可以通过设置 event.returnValue 返回自定义值。

Event: ‘remote-get-current-web-contents’ Deprecated

返回:

在 webContents 的渲染器进程中调用 remote.getCurrentWebContents() 时发出。 调用 event.preventDefault() 将阻止对象返回 可以通过设置 event.returnValue 返回自定义值。

方法

app 对象具有以下方法:

注意: 某些方法仅在特定的操作系统上可用, 这些方法会被标记出来。

app.quit()

尝试关闭所有窗口 将首先发出 before-quit 事件。 如果所有窗口都已成功关闭, 则将发出 will-quit 事件, 并且默认情况下应用程序将终止。

此方法会确保执行所有beforeunload 和 unload事件处理程序。 可以在退出窗口之前的beforeunload事件处理程序中返回false取消退出。

app.exit([exitCode])

  • exitCode Integer (可选)

Exits immediately with exitCode. exitCode defaults to 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 被多次调用时,多个实例将在当前实例退出后启动。

立即重启当前实例并向新的实例添加新的命令行参数的示例：

  1. const { app } = require('electron')
  3. app.relaunch({ args: process.argv.slice(1).concat(['--relaunch']) })
  4. app.exit(0)

app.isReady()

返回 Boolean 类型 - 如果 Electron 已经完成初始化，则返回 true, 其他情况为 false See also app.whenReady().

app.whenReady()

返回 Promise<void> - 当Electron 初始化完成。 可用作检查 app.isReady() 的方便选择，假如应用程序尚未就绪，则订阅ready事件。

app.focus([options])

  • options Object (可选)
    • steal Boolean macOS - Make the receiver the active app even if another app is currently active.

On Linux, focuses on the first visible window. On macOS, makes the application the active app. On Windows, focuses on the application’s first window.

You should seek to use the steal option as sparingly as possible.

app.hide() macOS

隐藏所有的应用窗口，不是最小化.

app.show() macOS

Shows application windows after they were hidden. Does not automatically focus them.

app.setAppLogsPath([path])

  • path String (optional) - A custom path for your logs. Must be absolute.

Sets or creates a directory your app’s logs which can then be manipulated with app.getPath() or app.setPath(pathName, newPath).

Calling app.setAppLogsPath() without a path parameter will result in this directory being set to ~/Library/Logs/YourAppName on macOS, and inside the userData directory on Linux and Windows.

app.getAppPath()

返回 String 类型 - 当前应用程序所在目录

app.getPath(name)

  • name String - You can request the following paths by the name:
    • home 用户的 home 文件夹（主目录）
    • appData Per-user application data directory, which by default points to:
      • %APPDATA% Windows 中
      • $XDG_CONFIG_HOME or ~/.config Linux 中
      • ~/Library/Application Support macOS 中
    • userData 储存你应用程序设置文件的文件夹，默认是 appData 文件夹附加应用的名称
    • 缓存
    • temp 临时文件夹
    • exe当前的可执行文件
    • module The libchromiumcontent 库
    • desktop 当前用户的桌面文件夹
    • documents 用户文档目录的路径
    • downloads 用户下载目录的路径
    • music 用户音乐目录的路径
    • pictures 用户图片目录的路径
    • videos 用户视频目录的路径
    • recent Directory for the user’s recent files (Windows only).
    • logs应用程序的日志文件夹
    • crashDumps Directory where crash dumps are stored.

Returns String - A path to a special directory or file associated with name. On failure, an Error is thrown.

If app.getPath('logs') is called without called app.setAppLogsPath() being called first, a default log directory will be created equivalent to calling app.setAppLogsPath() without a path parameter.

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，一个特定的文件夹或者文件。 If the path specifies a directory that does not exist, an Error is thrown. In that case, the directory should be created with fs.mkdirSync or similar.

name 参数只能使用 app.getPath 定义过的 name

默认情况下, 网页的 cookie 和缓存将存储在 userData 目录下。 如果要更改这个位置, 你需要在 app 模块中的 ready 事件被触发之前重写 userData 的路径。

app.getVersion()

返回 String-加载的应用程序的版本。 如果应用程序的 package. json 文件中找不到版本号, 则返回当前包或者可执行文件的版本。

app.getName()

返回 String-当前应用程序的名称, 它是应用程序的 package. json 文件中的名称。

Usually the name field of package.json is a short lowercase name, according to the npm modules spec. 通常还应该指定一个 productName 字段, 是首字母大写的完整名称，用于表示应用程序的名称。Electron 会优先使用这个字段作为应用名。

app.setName(name)

  • name String

设置当前应用程序的名字

Note: This function overrides the name used internally by Electron; it does not affect the name that the OS uses.

app.getLocale()

Returns String - The current application locale. Possible return values are documented here.

要设置区域，则需要在应用启动时使用命令行时打开开关，你可以在这里找到。

注意: 分发打包的应用程序时, 你必须指定 locales 文件夹。

注意： 在 Windows 上，你必须得等 ready 事件触发之后，才能调用该方法

app.getLocaleCountryCode()

Returns String - User operating system’s locale two-letter ISO 3166 country code. The value is taken from native OS APIs.

注意： 当无法检测本地国家代码时，它返回空字符串。

app.addRecentDocument(path) macOS Windows

  • path String

将此 path 添加到最近打开的文件列表中

This list is managed by the OS. On Windows, you can visit the list from the task bar, and on macOS, you can visit it from dock menu.

app.clearRecentDocuments() macOS Windows

清空最近打开的文档列表

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

  • protocol String - 协议的名称, 不包含 ://。 For example, if you want your app to handle electron:// links, call this method with electron as the parameter.
  • path String (optional) Windows - The path to the Electron executable. Defaults to process.execPath
  • args String[] (optional) Windows - Arguments passed to the executable. Defaults to an empty array

返回 Boolean-是否成功调用。

Sets the current executable as the default handler for a protocol (aka URI scheme). It allows you to integrate your app deeper into the operating system. Once registered, all links with your-protocol:// will be opened with the current executable. The whole link, including protocol, will be passed to your application as a parameter.

Note: On macOS, you can only register protocols that have been added to your app’s info.plist, which cannot be modified at runtime. However, you can change the file during build time via Electron Forge, Electron Packager, or by editing info.plist with a text editor. 有关详细信息，请参阅 Apple’s documentation

Note: In a Windows Store environment (when packaged as an appx) this API will return true for all calls but the registry key it sets won’t be accessible by other applications. In order to register your Windows Store application as a default protocol handler you must declare the protocol in your manifest.

The API uses the Windows Registry and LSSetDefaultHandlerForURLScheme internally.

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

  • protocol String - 协议的名称, 不包含 ://。
  • pathString (可选) Windows -默认为 process.execPath
  • args String[] (可选) Windows - 默认为空数组

返回 Boolean-是否成功调用。

This method checks if the current executable as the default handler for a protocol (aka URI scheme). If so, it will remove the app as the default handler.

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

  • protocol String - 协议的名称, 不包含 ://。
  • pathString (可选) Windows -默认为 process.execPath
  • args String[] (可选) Windows - 默认为空数组

Returns Boolean - Whether the current executable is the default handler for a protocol (aka URI scheme).

注意: 在macOS上, 您可以使用此方法检查应用程序是否已注册为协议的默认协议处理程序。 同时可以通过查看 ~/Library/Preferences/com.apple.LaunchServices.plist 来确认。 有关详细信息，请参阅 Apple’s documentation

The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internally.

app.getApplicationNameForProtocol(url)

  • url String - a URL with the protocol name to check. Unlike the other methods in this family, this accepts an entire URL, including :// at a minimum (e.g. https://).

Returns String - Name of the application handling the protocol, or an empty string if there is no handler. For instance, if Electron is the default handler of the URL, this could be Electron on Windows and Mac. However, don’t rely on the precise format which is not guaranteed to remain unchanged. Expect a different format on Linux, possibly with a .desktop suffix.

This method returns the application name of the default handler for the protocol (aka URI scheme) of a URL.

app.getApplicationInfoForProtocol(url) macOS Windows

  • url String - a URL with the protocol name to check. Unlike the other methods in this family, this accepts an entire URL, including :// at a minimum (e.g. https://).

Returns Promise<Object> - Resolve with an object containing the following:

  • icon NativeImage - the display icon of the app handling the protocol.
  • path String - installation path of the app handling the protocol.
  • name String - display name of the app handling the protocol.

This method returns a promise that contains the application name, icon and path of the default handler for the protocol (aka URI scheme) of a URL.

app.setUserTasks(tasks) Windows

  • tasks Task[] - 由 Task 对象组成的数组

Adds tasks to the Tasks.aspx#tasks) category of the Jump List on Windows.

tasks 是 Task 对象组成的数组

返回 Boolean-是否成功调用。

注意: 如果您想自定义跳转列表, 请使用 aapp.setJumpList(categories) 来代替。

app.getJumpListSettings() Windows

返回 Object:

  • minItems Integer - 将在跳转列表中显示项目的最小数量(有关此值的更详细描述，请参阅 MSDN docs.aspx)).
  • removedItems JumpListItem[] - Array of JumpListItem objects that correspond to items that the user has explicitly removed from custom categories in the Jump List. 这些项目不能在 next 调用 app.setJumpList() 时重新添加到跳转列表中, Windows不会显示任何包含已删除项目的自定义类别.

app.setJumpList(categories) Windows

设置或删除应用程序的自定义跳转列表，并返回以下字符串之一：

  • ok - 没有出现错误
  • error - 发生一个或多个错误，启用运行日志记录找出可能的原因。
  • invalidSeparatorError - An attempt was made to add a separator to a custom category in the Jump List. Separators are only allowed in the standard Tasks category.
  • fileTypeRegistrationError -尝试向自定义跳转列表添加一个文件链接，但是该应用未注册处理该应用类型
  • customCategoryAccessDeniedError - 由于用户隐私或策略组设置，自定义类别无法添加到跳转列表。

如果 categories 的值为 null， 之前设定的自定义跳转列表(如果存在) 将被替换为标准的应用跳转列表(由windows生成)

Note: If a JumpListCategory object has neither the type nor the name property set then its type is assumed to be tasks. 如果设置了 name 属性，省略了 type 属性，那么 type 默认为 custom.

注意: 用户可以从自定义类别中移除项目， after 调用 app.setJumpList(categories) 方法之前， Windows不允许删除的项目添加回自定义类别。 尝试提前将删除的项目重新添加 到自定义类别中，将导致整个自定义类别被隐藏。 删除的项目可以使用 app.getJumpListSettings() 获取。

下面是创建自定义跳转列表的一个非常简单的示例:

  1. const { app } = require('electron')
  3. app.setJumpList([
  4.   {
  5.     type: 'custom',
  6.     name: 'Recent Projects',
  7.     items: [
  8.       { type: 'file', path: 'C:\\Projects\\project1.proj' },
  9.       { type: 'file', path: 'C:\\Projects\\project2.proj' }
  10.     ]
  11.   },
  12.   { // 已经有一个名字所以 `type` 被认为是 "custom"
  13.     name: 'Tools',
  14.     items: [
  15.       {
  16.         type: 'task',
  17.         title: 'Tool A',
  18.         program: process.execPath,
  19.         args: '--run-tool-a',
  20.         icon: process.execPath,
  21.         iconIndex: 0,
  22.         description: 'Runs Tool A'
  23.       },
  24.       {
  25.         type: 'task',
  26.         title: 'Tool B',
  27.         program: process.execPath,
  28.         args: '--run-tool-b',
  29.         icon: process.execPath,
  30.         iconIndex: 0,
  31.         description: 'Runs Tool B'
  32.       }
  33.     ]
  34.   },
  35.   { type: 'frequent' },
  36.   { //这里没有设置名字 所以 `type` 被认为是 "tasks"
  37.     items: [
  38.       {
  39.         type: 'task',
  40.         title: 'New Project',
  41.         program: process.execPath,
  42.         args: '--new-project',
  43.         description: 'Create a new project.'
  44.       },
  45.       { type: 'separator' },
  46.       {
  47.         type: 'task',
  48.         title: 'Recover Project',
  49.         program: process.execPath,
  50.         args: '--recover-project',
  51.         description: 'Recover Project'
  52.       }
  53.     ]
  54.   }
  55. ])

app.requestSingleInstanceLock()

返回 Boolean

此方法的返回值表示你的应用程序实例是否成功取得了锁。 如果它取得锁失败，你可以假设另一个应用实例已经取得了锁并且仍旧在运行，并立即退出。

例如：如果你的程序是应用的主要实例并且当这个方法返回 true时，你应该继续让你的程序运行。 如果当它返回 false如果你的程序没有取得锁，它应该立刻退出，并且将参数发送给那个已经取到锁的进程。

在 macOS 上, 当用户尝试在 Finder 中打开您的应用程序的第二个实例时, 系统会通过发出 open-file 和 open-url 事件来自动强制执行单个实例,。 但是当用户在命令行中启动应用程序时, 系统的单实例机制将被绕过, 您必须手动调用此方法来确保单实例。

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

  1. const { app } = require('electron')
  2. let myWindow = null
  4. const gotTheLock = app.requestSingleInstanceLock()
  6. if (!gotTheLock) {
  7.   app.quit()
  8. } else {
  9.   app.on('second-instance', (event, commandLine, workingDirectory) => {
  10.     // 当运行第二个实例时,将会聚焦到myWindow这个窗口
  11.     if (myWindow) {
  12.       if (myWindow.isMinimized()) myWindow.restore()
  13.       myWindow.focus()
  14.     }
  15.   })
  17.   // 创建 myWindow, 加载应用的其余部分, etc...
  18.   app.whenReady().then(() => {
  19.     myWindow = createWindow()
  20.   })
  21. }

app.hasSingleInstanceLock()

返回 Boolean

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

app.releaseSingleInstanceLock()

Releases all locks that were created by requestSingleInstanceLock. This will allow multiple instances of the application to once again run side by side.

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

  • type String - 活动的唯一标识。 映射到 NSUserActivity. activityType。
  • userInfo any - App-specific state to store for use by another device.
  • webpageURL String (optional) - The webpage to load in a browser if no suitable app is installed on the resuming device. The scheme must be http or https.

创建一个 NSUserActivity 并将其设置为当前活动。 该活动之后可以Handoff到另一个设备。

app.getCurrentActivityType() macOS

返回 String - 正在运行的 activity 的类型

app.invalidateCurrentActivity() macOS

使当前的Handoff用户活动无效。

app.resignCurrentActivity() macOS

Marks the current Handoff user activity as inactive without invalidating it.

app.updateCurrentActivity(type, userInfo) macOS

  • type String - 活动的唯一标识。 映射到 NSUserActivity. activityType。
  • userInfo any - App-specific state to store for use by another device.

当其类型与 type 匹配时更新当前活动, 将项目从 用户信息 合并到其当前 用户信息 字典中。

app.setAppUserModelId(id) Windows

  • id String

改变当前应用的 Application User Model ID.aspx) 为 id.

app.setActivationPolicy(policy) macOS

  • policy String - Can be ‘regular’, ‘accessory’, or ‘prohibited’.

Sets the activation policy for a given app.

Activation policy types:

  • ‘regular’ - The application is an ordinary app that appears in the Dock and may have a user interface.
  • ‘accessory’ - The application doesn’t appear in the Dock and doesn’t have a menu bar, but it may be activated programmatically or by clicking on one of its windows.
  • ‘prohibited’ - The application doesn’t appear in the Dock and may not create windows or be activated.

app.importCertificate(options, callback) Linux

  • 选项 对象
    • certificate String - pkcs12 文件的路径
    • password String - 证书的密码
  • callback Function
    • result Integer - 导入结果

将 pkcs12 格式的证书导入到平台证书库。 使用导入操作的 callback 调用返回 result ，值 0 表示成功，而任何其他值表示失败，根据Chromium net_error_list 。

app.disableHardwareAcceleration()

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

这个方法只能在应用程序准备就绪（ready）之前调用。

app.disableDomainBlockingFor3DAPIs()

By default, Chromium disables 3D APIs (e.g. WebGL) until restart on a per domain basis if the GPU processes crashes too frequently. This function disables that behavior.

这个方法只能在应用程序准备就绪（ready）之前调用。

app.getAppMetrics()

Returns ProcessMetric[]: Array of ProcessMetric objects that correspond to memory and CPU usage statistics of all the processes associated with the app.

app.getGPUFeatureStatus()

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

Note: This information is only usable after the gpu-info-update event is emitted.

app.getGPUInfo(infoType)

  • infoType String - Can be basic or complete.

Returns Promise<unknown>

For infoType equal to complete: Promise is fulfilled with Object containing all the GPU Information as in chromium’s GPUInfo object. 这包括 chrome://gpu 页面上显示的版本和驱动程序信息。

对于infoType等于basic： Promise 至少包含当请求complete时的属性Object。 下面是一个基础响应示例：

  1. {
  2.   auxAttributes:
  3.    {
  4.      amdSwitchable: true,
  5.      canSupportThreadedTextureMailbox: false,
  6.      directComposition: false,
  7.      directRendering: true,
  8.      glResetNotificationStrategy: 0,
  9.      inProcessGpu: true,
  10.      initializationTime: 0,
  11.      jpegDecodeAcceleratorSupported: false,
  12.      optimus: false,
  13.      passthroughCmdDecoder: false,
  14.      sandboxed: false,
  15.      softwareRendering: false,
  16.      supportsOverlays: false,
  17.      videoDecodeAcceleratorFlags: 0
  18.    },
  19.   gpuDevice:
  20.    [{ active: true, deviceId: 26657, vendorId: 4098 },
  21.      { active: false, deviceId: 3366, vendorId: 32902 }],
  22.   machineModelName: 'MacBookPro',
  23.   machineModelVersion: '11.5'
  24. }

如果只需要基本信息，如vendorId或driverId，则应优先使用basic。

app.setBadgeCount([count]) Linux macOS

  • count Integer (optional) - If a value is provided, set the badge to the provided value otherwise, on macOS, display a plain white dot (e.g. unknown number of notifications). On Linux, if a value is not provided the badge will not display.

返回 Boolean-是否成功调用。

设置当前应用程序的计数器标记. 将计数设置为 0 将隐藏该标记。

On macOS, it shows on the dock icon. On Linux, it only works for Unity launcher.

注意: Unity 启动器依赖于 . desktop 文件, 获取更多信息, 请阅读 桌面环境集成 。

app.getBadgeCount() Linux macOS

Returns Integer - 获取计数器提醒(badge) 中显示的当前值

app.isUnityRunning() Linux

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

app.getLoginItemSettings([options]) macOS Windows

  • options Object (可选)
    • path String (optional) Windows - The executable path to compare against. Defaults to process.execPath.
    • args String[] (optional) Windows - The command-line arguments to compare against. Defaults to an empty array.

如果你为 app. setLoginItemSettings 提供path 和 args 选项，那么你需要在这里为 openAtLogin 设置相同的参数已确保正确的设置。

返回 Object:

  • openAtLogin Boolean - true 如果应用程序设置为在登录时打开, 则为 <0>true</0>
  • openAsHidden Boolean macOS - true if the app is set to open as hidden at login. 该配置在 MAS 构建 时不可用。
  • wasOpenedAtLogin Boolean macOS - true if the app was opened at login automatically. 该配置在 MAS 构建 时不可用。
  • wasOpenedAsHidden Boolean macOS - true if the app was opened as a hidden login item. 这表示应用程序在启动时不应打开任何窗口。 该配置在 MAS 构建 时不可用。
  • restoreState Boolean macOS - true if the app was opened as a login item that should restore the state from the previous session. 这表示程序应该还原上次关闭时打开的窗口。 该配置在 MAS 构建 时不可用。
  • executableWillLaunchAtLogin Boolean Windows - true if app is set to open at login and its run key is not deactivated. This differs from openAtLogin as it ignores the args option, this property will be true if the given executable would be launched at login with any arguments.
  • launchItems Object[] Windows
    • name String Windows - name value of a registry entry.
    • path String Windows - The executable to an app that corresponds to a registry entry.
    • args String[] Windows - the command-line arguments to pass to the executable.
    • scope String Windows - one of user or machine. Indicates whether the registry entry is under HKEY_CURRENT USER or HKEY_LOCAL_MACHINE.
    • enabled Boolean Windows - true if the app registry key is startup approved and therefore shows as enabled in Task Manager and Windows settings.

app.setLoginItemSettings(settings) macOS Windows

  • settings Object
    • openAtLogin Boolean (optional) - true to open the app at login, false to remove the app as a login item. 默认值为 false.
    • openAsHidden Boolean (optional) macOS - true to open the app as hidden. 默认为false。 用户可以从系统首选项中编辑此设置, 以便在打开应用程序时检查 app.getLoginItemSettings().wasOpenedAsHidden 以了解当前值。 该配置在 MAS 构建 时不可用。
    • path String (optional) Windows - The executable to launch at login. Defaults to process.execPath.
    • args String[] (optional) Windows - The command-line arguments to pass to the executable. Defaults to an empty array. Take care to wrap paths in quotes.
    • enabled Boolean (optional) Windows - true will change the startup approved registry key and enable / disable the App in Task Manager and Windows Settings. 默认值为 true。
    • name String (optional) Windows - value name to write into registry. Defaults to the app’s AppUserModelId(). 设置应用程序的登录项设置。

如果需要在使用Squirrel的 Windows 上使用 Electron 的 autoUpdater ，你需要将启动路径设置为 Update.exe，并传递指定应用程序名称的参数。 例如：

  1. const appFolder = path.dirname(process.execPath)
  2. const updateExe = path.resolve(appFolder, '..', 'Update.exe')
  3. const exeName = path.basename(process.execPath)
  5. app.setLoginItemSettings({
  6.   openAtLogin: true,
  7.   path: updateExe,
  8.   args: [
  9.     '--processStart', `"${exeName}"`,
  10.     '--process-start-args', `"--hidden"`
  11.   ]
  12. })

app.isAccessibilitySupportEnabled() macOS Windows

Returns Boolean - 如果开启了Chrome的辅助功能, 则返回 true，其他情况返false。 如果使用了辅助技术（例如屏幕阅读），该 API 将返回 `true</0。 查看更多细节，请查阅 https://www.chromium.org/developers/design-documents/accessibility

app.setAccessibilitySupportEnabled(enabled)` _macOS_ _Windows_

``

手动启用 Chrome 的辅助功能的支持, 允许在应用程序中设置是否开启辅助功能。 在Chromium’s accessibility docs查看更多的细节 默认为禁用

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

注意: 渲染进程树会明显的影响应用的性能。默认情况下不应该启用。

``

app.showAboutPanel()

Show the app’s about panel options. These options can be overridden with app.setAboutPanelOptions(options).

app.setAboutPanelOptions(options)

  • 选项 对象
    • applicationName String (可选) - 应用程序的名字
    • applicationVersion String (可选) - 应用程序版本
    • copyright String (可选) - 版权信息
    • version String (optional) macOS - The app’s build version number.
    • credits String (optional) macOS Windows - Credit information.
    • authors String[] (optional) Linux - List of app authors.
    • website String (optional) Linux - The app’s website.
    • iconPath String (optional) Linux Windows - Path to the app’s icon in a JPEG or PNG file format. On Linux, will be shown as 64x64 pixels while retaining aspect ratio.

设置 “关于” 面板选项。 This will override the values defined in the app’s .plist file on macOS. 更多详细信息, 请查阅 Apple 文档 。 在 Linux 上，没有默认值，所以必须设置值才能显示。

If you do not set credits but still wish to surface them in your app, AppKit will look for a file named “Credits.html”, “Credits.rtf”, and “Credits.rtfd”, in that order, in the bundle returned by the NSBundle class method main. The first file found is used, and if none is found, the info area is left blank. See Apple documentation for more information.

app.isEmojiPanelSupported()

返回 布尔值 - 当前操作系统版本是否允许使用本机emoji选取器。

app.showEmojiPanel() macOS Windows

打开系统自身的emjio选取器。

app.startAccessingSecurityScopedResource(bookmarkData) mas

  • bookmarkData String - base64 编码的安全作用域的书签数据(bookmark data) ，通过 dialog.showOpenDialog 或者 dialog.showSaveDialog 方法获取。

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

  1. //开始读取文件
  2. const stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)
  3. // You can now access the file outside of the sandbox 🎉
  5. // Remember to stop accessing the file once you've finished with it.
  6. stopAccessingSecurityScopedResource()

开始访问安全范围内的资源。 通过这个方法，Electron 应用被打包为可到达Mac App Store沙箱之外访问用户选择的文件。 关于系统工作原理，请查阅Apple’s documentation

app.enableSandbox()

Enables full sandbox mode on the app. This means that all renderers will be launched sandboxed, regardless of the value of the sandbox flag in WebPreferences.

这个方法只能在应用程序准备就绪（ready）之前调用。

app.isInApplicationsFolder() macOS

Returns Boolean - Whether the application is currently running from the systems Application folder. Use in combination with app.moveToApplicationsFolder()

app.moveToApplicationsFolder([options]) macOS

  • options Object (可选)

    • conflictHandler Function\ (optional) - A handler for potential conflict in move failure.

      • conflictType String - The type of move conflict encountered by the handler; can be exists or existsAndRunning, where exists means that an app of the same name is present in the Applications directory and existsAndRunning means both that it exists and that it’s presently running.

Returns Boolean - Whether the move was successful. Please note that if the move is successful, your application will quit and relaunch.

No confirmation dialog will be presented by default. If you wish to allow the user to confirm the operation, you may do so using the dialog API.

注意:如果并非是用户造成操作失败，这个方法会抛出错误。 例如，如果用户取消了授权会话，这个方法将返回false。 如果无法执行复制操作, 则此方法将抛出错误。 The message in the error should be informative and tell you exactly what went wrong.

By default, if an app of the same name as the one being moved exists in the Applications directory and is not running, the existing app will be trashed and the active app moved into its place. If it is running, the pre-existing running app will assume focus and the previously active app will quit itself. This behavior can be changed by providing the optional conflict handler, where the boolean returned by the handler determines whether or not the move conflict is resolved with default behavior. i.e. returning false will ensure no further action is taken, returning true will result in the default behavior and the method continuing.

例如：

  1. app.moveToApplicationsFolder({
  2.   conflictHandler: (conflictType) => {
  3.     if (conflictType === 'exists') {
  4.       return dialog.showMessageBoxSync({
  5.         type: 'question',
  6.         buttons: ['Halt Move', 'Continue Move'],
  7.         defaultId: 0,
  8.         message: 'An app of this name already exists'
  9.       }) === 1
  10.     }
  11.   }
  12. })

Would mean that if an app already exists in the user directory, if the user chooses to ‘Continue Move’ then the function would continue with its default behavior and the existing app will be trashed and the active app moved into its place.

app.isSecureKeyboardEntryEnabled() macOS

Returns Boolean - whether Secure Keyboard Entry is enabled.

By default this API will return false.

app.setSecureKeyboardEntryEnabled(enabled) macOS

  • enabled Boolean - Enable or disable Secure Keyboard Entry

Set the Secure Keyboard Entry is enabled in your application.

By using this API, important information such as password and other sensitive information can be prevented from being intercepted by other processes.

See Apple’s documentation for more details.

Note: Enable Secure Keyboard Entry only when it is needed and disable it when it is no longer needed.

属性

app.accessibilitySupportEnabled macOS Windows

A Boolean property that’s true if Chrome’s accessibility support is enabled, false otherwise. This property will be true if the use of assistive technologies, such as screen readers, has been detected. Setting this property to true manually enables Chrome’s accessibility support, allowing developers to expose accessibility switch to users in application settings.

See Chromium’s accessibility docs for more details. 默认为禁用

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

注意: 渲染进程树会明显的影响应用的性能。默认情况下不应该启用。

app.applicationMenu

A Menu | null property that returns Menu if one has been set and null otherwise. Users can pass a Menu to set this property.

app.badgeCount Linux macOS

An Integer property that returns the badge count for current app. Setting the count to 0 will hide the badge.

On macOS, setting this with any nonzero integer shows on the dock icon. On Linux, this property only works for Unity launcher.

注意: Unity 启动器依赖于 . desktop 文件, 获取更多信息, 请阅读 桌面环境集成 。

Note: On macOS, you need to ensure that your application has the permission to display notifications for this property to take effect.

app.commandLine Readonly

A CommandLine object that allows you to read and manipulate the command line arguments that Chromium uses.

app.dock macOS Readonly

A Dock | undefined object that allows you to perform actions on your app icon in the user’s dock on macOS.

app.isPackaged Readonly

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

app.name

A String property that indicates the current application’s name, which is the name in the application’s package.json file.

Usually the name field of package.json is a short lowercase name, according to the npm modules spec. 通常还应该指定一个 productName 字段, 是首字母大写的完整名称，用于表示应用程序的名称。Electron 会优先使用这个字段作为应用名。

app.userAgentFallback

A String which is the user agent string Electron will use as a global fallback.

This is the user agent that will be used when no user agent is set at the webContents or session level. It is useful for ensuring that your entire app has the same user agent. Set to a custom value as early as possible in your app’s initialization to ensure that your overridden value is used.

app.allowRendererProcessReuse

A Boolean which when true disables the overrides that Electron has in place to ensure renderer processes are restarted on every navigation. The current default value for this property is true.

The intention is for these overrides to become disabled by default and then at some point in the future this property will be removed. This property impacts which native modules you can use in the renderer process. For more information on the direction Electron is going with renderer process restarts and usage of native modules in the renderer process please check out this Tracking Issue.

app.runningUnderRosettaTranslation macOS Readonly

A Boolean which when true indicates that the app is currently running under the Rosetta Translator Environment).

You can use this property to prompt users to download the arm64 version of your application when they are running the x64 version under Rosetta incorrectly.