app

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

进程：主进程

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

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

Control your application's event lifecycle.

Process: Main

The following example shows how to quit the application when the last window is closed:

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

事件

app 对象会发出以下事件:

Events

The app object emits the following events:

事件: 'will-finish-launching'

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

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

Event: 'will-finish-launching'

Emitted when the application has finished basic startup. On Windows and Linux, the will-finish-launching event is the same as the ready event; on macOS, this event represents the applicationWillFinishLaunching notification of NSApplication. You would usually set up listeners for the open-file and open-url events here, and start the crash reporter and auto updater.

In most cases, you should do everything in the ready event handler.

事件: 'ready'

返回:

• launchInfo Object macOS

当 Electron 完成初始化时被触发。 在 macOS 中, 如果从通知中心中启动，那么 launchInfo 中的 userInfo 包含用来打开应用程序的 NSUserNotification 信息。 你可以通过调用 app.isReady() 方法来检查此事件是否已触发。

Event: 'ready'

Returns:

• launchInfo Object macOS

Emitted when Electron has finished initializing. On macOS, launchInfo holds the userInfo of the NSUserNotification that was used to open the application, if it was launched from Notification Center. You can call app.isReady() to check if this event has already fired.

事件: 'window-all-closed'

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

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

Event: 'window-all-closed'

Emitted when all windows have been closed.

If you do not subscribe to this event and all windows are closed, the default behavior is to quit the app; however, if you subscribe, you control whether the app quits or not. If the user pressed Cmd + Q, or the developer called app.quit(), Electron will first try to close all the windows and then emit the will-quit event, and in this case the window-all-closed event would not be emitted.

事件：'before-quit'

返回:

• event Event

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

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

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

Event: 'before-quit'

Returns:

• event Event

Emitted before the application starts closing its windows. Calling event.preventDefault() will prevent the default behavior, which is terminating the application.

Note: If application quit was initiated by autoUpdater.quitAndInstall(), then before-quit is emitted after emitting close event on all windows and closing them.

Note: On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.

事件: 'will-quit'

返回:

• event Event

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

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

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

Event: 'will-quit'

Returns:

• event Event

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

See the description of the window-all-closed event for the differences between the will-quit and window-all-closed events.

Note: On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.

事件: 'quit'

返回:

• event Event
• exitCode Integer

在应用程序退出时发出。

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

Event: 'quit'

Returns:

• event Event
• exitCode Integer

Emitted when the application is quitting.

Note: On Windows, this event will not be emitted if the app is closed due to a shutdown/restart of the system or a user logout.

事件: 'open-file' macOS

返回:

• event Event
• path String

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

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

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

Event: 'open-file' macOS

Returns:

• event Event
• path String

Emitted when the user wants to open a file with the application. The open-file event is usually emitted when the application is already open and the OS wants to reuse the application to open the file. open-file is also emitted when a file is dropped onto the dock and the application is not yet running. Make sure to listen for the open-file event very early in your application startup to handle this case (even before the ready event is emitted).

You should call event.preventDefault() if you want to handle this event.

On Windows, you have to parse process.argv (in the main process) to get the filepath.

事件: 'open-url' macOS

返回:

• event Event
• url String

当用户想要在应用中打开一个 URL 时发出。 应用程序的 Info. plist 文件必须在 CFBundleURLTypes 项中定义 url 方案, 并将 NSPrincipalClass 设置为 AtomApplication。

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

Event: 'open-url' macOS

Returns:

• event Event
• url String

Emitted when the user wants to open a URL with the application. Your application's Info.plist file must define the url scheme within the CFBundleURLTypes key, and set NSPrincipalClass to AtomApplication.

You should call event.preventDefault() if you want to handle this event.

事件: 'activate' macOS

返回:

• event Event
• hasVisibleWindows Boolean

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

Event: 'activate' macOS

Returns:

• event Event
• hasVisibleWindows Boolean

Emitted when the application is activated. Various actions can trigger this event, such as launching the application for the first time, attempting to re-launch the application when it's already running, or clicking on the application's dock or taskbar icon.

事件: 'continue-activity' macOS

返回:

• event Event
• typeString-标识活动的字符串。 映射到 NSUserActivity. activityType。
• userInfoObject-包含由其他设备上的活动存储的应用程序特定状态。

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

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

Event: 'continue-activity' macOS

Returns:

• event Event
• type String - A string identifying the activity. Maps to NSUserActivity.activityType.
• userInfo Object - Contains app-specific state stored by the activity on another device.

Emitted during Handoff when an activity from a different device wants to be resumed. You should call event.preventDefault() if you want to handle this event.

A user activity can be continued only in an app that has the same developer Team ID as the activity's source app and that supports the activity's type. Supported activity types are specified in the app's Info.plist under the NSUserActivityTypes key.

事件: 'will-continue-activity' macOS

返回:

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

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

Event: 'will-continue-activity' macOS

Returns:

• event Event
• type String - A string identifying the activity. Maps to NSUserActivity.activityType.

Emitted during Handoff before an activity from a different device wants to be resumed. You should call event.preventDefault() if you want to handle this event.

事件: 'continue-activity-error' macOS

返回:

• event Event
• typeString-标识活动的字符串。 映射到 NSUserActivity. activityType。
• error String - 详细的错误信息

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

Event: 'continue-activity-error' macOS

Returns:

• event Event
• type String - A string identifying the activity. Maps to NSUserActivity.activityType.
• error String - A string with the error's localized description.

Emitted during Handoff when an activity from a different device fails to be resumed.

事件: 'activity-was-continued' macOS

返回:

• event Event
• typeString-标识活动的字符串。 映射到 NSUserActivity. activityType。
• userInfoObject-存储的应用程序特定状态。

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

Event: 'activity-was-continued' macOS

Returns:

• event Event
• type String - A string identifying the activity. Maps to NSUserActivity.activityType.
• userInfo Object - Contains app-specific state stored by the activity.

Emitted during Handoff after an activity from this device was successfully resumed on another one.

事件: 'update-activity-state' macOS

返回:

• event Event
• typeString-标识活动的字符串。 映射到 NSUserActivity. activityType。
• userInfoObject-存储的应用程序特定状态。

当 Handoff 即将通过另一个设备恢复时触发。 如果需要更新要传输的状态, 应立即调用 事件. preventDefault (), 构造新的 用户信息 字典, 并及时调用 应用程序 updateCurrentActiviy ()。 否则，操作会失败，并且触发 continue-activity-error

Event: 'update-activity-state' macOS

Returns:

• event Event
• type String - A string identifying the activity. Maps to NSUserActivity.activityType.
• userInfo Object - Contains app-specific state stored by the activity.

Emitted when Handoff is about to be resumed on another device. If you need to update the state to be transferred, you should call event.preventDefault() immediately, construct a new userInfo dictionary and call app.updateCurrentActiviy() in a timely manner. Otherwise, the operation will fail and continue-activity-error will be called.

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

返回:

• event Event

当用户单击 macOS 新选项卡按钮时发出。仅当当前 BrowserWindow 具有 tabbingIdentifier 时, 才会显示新的选项卡按钮

Event: 'new-window-for-tab' macOS

Returns:

• 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'

返回:

• event Event
• window BrowserWindow

在 browserWindow 失去焦点时发出。

Event: 'browser-window-blur'

Returns:

• event Event
• window BrowserWindow

Emitted when a browserWindow gets blurred.

事件: 'browser-window-focus'

返回:

• event Event
• window BrowserWindow

在 browserWindow 获得焦点时发出。

Event: 'browser-window-focus'

Returns:

• event Event
• window BrowserWindow

Emitted when a browserWindow gets focused.

事件: 'browser-window-created'

返回:

• event Event
• window BrowserWindow

在创建新的 browserWindow 时发出。

Event: 'browser-window-created'

Returns:

• event Event
• window BrowserWindow

Emitted when a new browserWindow is created.

事件: 'web-contents-created'

返回:

• event Event
• webContents WebContents

在创建新的 webContents 时发出。

Event: 'web-contents-created'

Returns:

• event Event
• webContents WebContents

Emitted when a new webContents is created.

事件: 'certificate-error'

返回:

• event Event
• webContents WebContents
• url String
• error String - 错误码
• certificate 证书

• callback Function

  • isTrustedBoolean-是否将证书视为可信的

当对 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)
  }
})

Event: 'certificate-error'

Returns:

• event Event
• webContents WebContents
• url String
• error String - The error code
• certificate Certificate

• callback Function

  • isTrusted Boolean - Whether to consider the certificate as trusted

Emitted when failed to verify the certificate for url, to trust the certificate you should prevent the default behavior with event.preventDefault() and call 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 证书[]

• callback Function

  • 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: 'select-client-certificate'

Returns:

• event Event
• webContents WebContents
• url URL
• certificateList Certificate[]

• callback Function

  • certificate Certificate (optional)

Emitted when a client certificate is requested.

The url corresponds to the navigation entry requesting the client certificate and callback can be called with an entry filtered from the list. Using event.preventDefault() prevents the application from using the first certificate from the store.

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

事件: "login"

返回:

• event Event
• webContents WebContents

• request Object

  • method String
  • url URL
  • referrer URL

• authInfo Object

  • isProxy Boolean
  • scheme String
  • host String
  • port Integer
  • realm String

• callback Function

  • username String
  • password String

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

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

const { app } = require('electron')
app.on('login', (event, webContents, request, authInfo, callback) => {
  event.preventDefault()
  callback('username', 'secret')
})

Event: 'login'

Returns:

• event Event
• webContents WebContents

• request Object

  • method String
  • url URL
  • referrer URL

• authInfo Object

  • isProxy Boolean
  • scheme String
  • host String
  • port Integer
  • realm String

• callback Function

  • username String
  • password String

Emitted when webContents wants to do basic auth.

The default behavior is to cancel all authentications. To override this you should prevent the default behavior with event.preventDefault() and call callback(username, password) with the credentials.

const { app } = require('electron')
app.on('login', (event, webContents, request, authInfo, callback) => {
  event.preventDefault()
  callback('username', 'secret')
})

Event: 'gpu-process-crashed'

返回:

• event Event
• killed Boolean

当 gpu 进程崩溃或被杀时触发。

Event: 'gpu-process-crashed'

Returns:

• event Event
• killed Boolean

Emitted when the gpu process crashes or is killed.

Event: 'renderer-process-crashed'

返回:

• event Event
• webContents WebContents
• killed Boolean

Emitted when the renderer process of webContents crashes or is killed.

Event: 'renderer-process-crashed'

Returns:

• event Event
• webContents WebContents
• killed Boolean

Emitted when the renderer process of webContents crashes or is killed.

事件: "accessibility-support-changed" macOS Windows

返回:

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

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

Event: 'accessibility-support-changed' macOS Windows

Returns:

• event Event
• accessibilitySupportEnabled Boolean - true when Chrome's accessibility support is enabled, false otherwise.

Emitted when Chrome's accessibility support changes. This event fires when assistive technologies, such as screen readers, are enabled or disabled. See https://www.chromium.org/developers/design-documents/accessibility for more details.

事件:'session-created'

返回:

• session Session

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

const { app } = require('electron')
app.on('session-created', (event, session) => {
  console.log(session)
})

Event: 'session-created'

Returns:

• session Session

Emitted when Electron has created a new session.

const { app } = require('electron')
app.on('session-created', (event, session) => {
  console.log(session)
})

事件: 'second-instance'

返回:

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

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

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

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

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

Event: 'second-instance'

Returns:

• event Event
• argv String[] - An array of the second instance's command line arguments
• workingDirectory String - The second instance's working directory

This event will be emitted inside the primary instance of your application when a second instance has been executed and calls app.requestSingleInstanceLock().

argv is an Array of the second instance's command line arguments, and workingDirectory is its current working directory. Usually applications respond to this by making their primary window focused and non-minimized.

This event is guaranteed to be emitted after the ready event of app gets emitted.

Note: Extra command line arguments might be added by Chromium, such as --original-process-start-time.

事件: 'desktop-capturer-get-sources'

返回:

• event Event
• webContents WebContents

当 desktopCapturer.getSources() 被 webContents 渲染过程中调用时触发。 调用 event.preventDefault() 将使它返回空的资源。

Event: 'desktop-capturer-get-sources'

Returns:

• event Event
• webContents WebContents

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

事件: 'remote-require'

返回:

• event Event
• webContents WebContents
• moduleName String

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

Event: 'remote-require'

Returns:

• event Event
• webContents WebContents
• moduleName String

Emitted when remote.require() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the module from being returned. Custom value can be returned by setting event.returnValue.

事件: 'remote-get-global'

返回:

• event Event
• webContents WebContents
• globalName String

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

Event: 'remote-get-global'

Returns:

• event Event
• webContents WebContents
• globalName String

Emitted when remote.getGlobal() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the global from being returned. Custom value can be returned by setting event.returnValue.

事件: 'remote-get-builtin'

返回:

• event Event
• webContents WebContents
• moduleName String

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

Event: 'remote-get-builtin'

Returns:

• event Event
• webContents WebContents
• moduleName String

Emitted when remote.getBuiltin() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the module from being returned. Custom value can be returned by setting event.returnValue.

事件: 'remote-get-current-window'

返回:

• event Event
• webContents WebContents

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

Event: 'remote-get-current-window'

Returns:

• event Event
• webContents WebContents

Emitted when remote.getCurrentWindow() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the object from being returned. Custom value can be returned by setting event.returnValue.

事件: 'remote-get-current-web-contents'

返回:

• event Event
• webContents WebContents

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

Event: 'remote-get-current-web-contents'

Returns:

• event Event
• webContents WebContents

Emitted when remote.getCurrentWebContents() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the object from being returned. Custom value can be returned by setting event.returnValue.

事件: 'remote-get-guest-web-contents'

返回:

• event Event
• webContents WebContents
• guestWebContents WebContents

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

Event: 'remote-get-guest-web-contents'

Returns:

• event Event
• webContents WebContents
• guestWebContents WebContents

Emitted when <webview>.getWebContents() is called in the renderer process of webContents. Calling event.preventDefault() will prevent the object from being returned. Custom value can be returned by setting event.returnValue.

方法

app 对象具有以下方法:

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

Methods

The app object has the following methods:

Note: Some methods are only available on specific operating systems and are labeled as such.

app.quit()

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

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

app.quit()

Try to close all windows. The before-quit event will be emitted first. If all windows are successfully closed, the will-quit event will be emitted and by default the application will terminate.

This method guarantees that all beforeunload and unload event handlers are correctly executed. It is possible that a window cancels the quitting by returning false in the beforeunload event handler.

app.exit([exitCode])

• exitCode Integer (可选)

立即退出程序并返回 exitCode。exitCode 的默认值是 0。

所有窗口都将立即被关闭，而不询问用户，而且 before-quit 和 will-quit 事件也不会被触发。

app.exit([exitCode])

• exitCode Integer (optional)

Exits immediately with exitCode. exitCode defaults to 0.

All windows will be closed immediately without asking the user, and the before-quit and will-quit events will not be emitted.

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.relaunch([options])

• options Object (optional)

  • args String
  • execPath String (optional)

Relaunches the app when current instance exits.

By default, the new instance will use the same working directory and command line arguments with current instance. When args is specified, the args will be passed as command line arguments instead. When execPath is specified, the execPath will be executed for relaunch instead of current app.

Note that this method does not quit the app when executed, you have to call app.quit or app.exit after calling app.relaunch to make the app restart.

When app.relaunch is called for multiple times, multiple instances will be started after current instance exited.

An example of restarting current instance immediately and adding a new command line argument to the new instance:

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

app.isReady()

返回 Boolean 类型 - 如果 Electron 已经完成初始化，则返回 true, 其他情况为 false

app.isReady()

Returns Boolean - true if Electron has finished initializing, false otherwise.

app.whenReady()

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

app.whenReady()

Returns Promise<void> - fulfilled when Electron is initialized. May be used as a convenient alternative to checking app.isReady() and subscribing to the ready event if the app is not ready yet.

app.focus()

在 Linux 系统中, 使第一个可见窗口获取焦点。在 macOS 上, 让该应用成为活动应用程序。在 Windows 上, 使应用的第一个窗口获取焦点。

app.focus()

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.

app.hide() macOS

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

app.hide() macOS

Hides all application windows without minimizing them.

app.show() 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.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.getAppPath()

Returns String - The current application directory.

app.getPath(name)

• name String

返回 String - 以 name 参数指定的文件夹或文件路径。当失败时抛出 Error 。

你可以通过名称请求以下的路径:

• home 用户的 home 文件夹（主目录）

• appData 当前用户的应用数据文件夹，默认对应：

  • %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 用户视频目录的路径
• logs应用程序的日志文件夹
• pepperFlashSystemPlugin Pepper Flash 插件的系统版本的完成路径。

app.getPath(name)

• name String

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

You can request the following paths by the name:

• home User's home directory.

• appData Per-user application data directory, which by default points to:

  • %APPDATA% on Windows
  • $XDG_CONFIG_HOME or ~/.config on Linux
  • ~/Library/Application Support on macOS
• userData The directory for storing your app's configuration files, which by default it is the appData directory appended with your app's name.
• temp Temporary directory.
• exe The current executable file.
• module The libchromiumcontent library.
• desktop The current user's Desktop directory.
• documents Directory for a user's "My Documents".
• downloads Directory for a user's downloads.
• music Directory for a user's music.
• pictures Directory for a user's pictures.
• videos Directory for a user's videos.
• logs Directory for your app's log folder.
• pepperFlashSystemPlugin Full path to the system version of the Pepper Flash plugin.

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

• path String

• options Object (可选)

  • size String

    • small - 16x16
    • normal - 32x32
    • large - Linux上是 48x48, Windows 上是 32x32, macOS 中无效

• callback Function

  • error Error
  • icon NativeImage

读取文件的关联图标。

On Windows, there are 2 kinds of icons:

• 与某些文件扩展名相关联的图标, 比如 . mp3 ，. png 等。
• 文件本身就带图标，像是 .exe, .dll, .ico

在 Linux 和 macOS 系统中，图标取决于和应用程序绑定的 文件 mime 类型

即将弃用

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

• path String

• options Object (optional)

  • size String

    • small - 16x16
    • normal - 32x32
    • large - 48x48 on Linux, 32x32 on Windows, unsupported on macOS.

• callback Function

  • error Error
  • icon NativeImage

Fetches a path's associated icon.

On Windows, there are 2 kinds of icons:

• Icons associated with certain file extensions, like .mp3, .png, etc.
• Icons inside the file itself, like .exe, .dll, .ico.

On Linux and macOS, icons depend on the application associated with file mime type.

Deprecated Soon

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.getFileIcon(path[, options])

• path String

• options Object (optional)

  • size String

    • small - 16x16
    • normal - 32x32
    • large - 48x48 on Linux, 32x32 on Windows, unsupported on macOS.

Returns Promise<NativeImage> - fulfilled with the app's icon, which is a NativeImage.

Fetches a path's associated icon.

On Windows, there a 2 kinds of icons:

• Icons associated with certain file extensions, like .mp3, .png, etc.
• Icons inside the file itself, like .exe, .dll, .ico.

On Linux and macOS, icons depend on the application associated with file mime type.

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.setPath(name, path)

• name String
• path String

Overrides the path to a special directory or file associated with name. 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.

You can only override paths of a name defined in app.getPath.

By default, web pages' cookies and caches will be stored under the userData directory. If you want to change this location, you have to override the userData path before the ready event of the app module is emitted.

app.getVersion()

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

app.getVersion()

Returns String - The version of the loaded application. If no version is found in the application's package.json file, the version of the current bundle or executable is returned.

app.getName()

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

根据 npm 的命名规则, 通常 package.json 中的 name 字段是一个短的小写字符串。 通常还应该指定一个 productName 字段, 是首字母大写的完整名称，用于表示应用程序的名称。Electron 会优先使用这个字段作为应用名。

app.getName()

Returns String - 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 lowercased name, according to the npm modules spec. You should usually also specify a productName field, which is your application's full capitalized name, and which will be preferred over name by Electron.

app.setName(name)

• name String

设置当前应用程序的名字

app.setName(name)

• name String

Overrides the current application's name.

app.getLocale()

返回 string——当前应用程序的语言环境。可能的返回值被记录在这里。

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

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

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

app.getLocale()

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

To set the locale, you'll want to use a command line switch at app startup, which may be found here.

Note: When distributing your packaged app, you have to also ship the locales folder.

Note: On Windows, you have to call it after the ready events gets emitted.

app.getLocaleCountryCode()

返回 string - 用户操作系统的本地双字节 ISO 3166 国家代码。该值来自本地操作系统API。

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

app.getLocaleCountryCode()

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

Note: When unable to detect locale country code, it returns empty string.

app.addRecentDocument(path) macOS Windows

• path String

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

这个列表由操作系统进行管理。在 Windows 中从任务栏访问列表, 在 macOS 中通过 dock 菜单进行访问。

app.addRecentDocument(path) macOS Windows

• path String

Adds path to the recent documents list.

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.clearRecentDocuments() macOS Windows

Clears the recent documents list.

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

• protocol String - 协议的名称, 不包含 ://。 如果您希望应用程序处理 electron:// 的链接, 请将 electron 作为该方法的参数.
• pathString (可选) Windows -默认为 process.execPath
• args String Windows - 默认为空数组

返回 Boolean-是否成功调用。

此方法将当前可执行文件设置为协议(也称为URI方案) 的默认处理程序。 它允许您将应用程序更深入地集成到操作系统中。 一旦注册成功, 所有 your-protocol:// 格式的链接都会使用你的程序打开。 整个链接 (包括协议) 将作为参数传递给您的应用程序。

在 Windows 系统中，你可以提供可选参数 path（可执行文件的路径）和 args（在启动时传递给可执行文件的参数数组）

注意: 在 macOS 上, 您只能注册已添加到应用程序的 info. plist 中的协议, 在运行时不能对其进行修改。 但是，您可以在构建时使用简单的文本编辑器或脚本更改文件。 有关详细信息，请参阅 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.

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

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

• protocol String - The name of your protocol, without ://. If you want your app to handle electron:// links, call this method with electron as the parameter.
• path String (optional) Windows - Defaults to process.execPath
• args String Windows - Defaults to an empty array

Returns Boolean - Whether the call succeeded.

This method 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.

On Windows, you can provide optional parameters path, the path to your executable, and args, an array of arguments to be passed to your executable when it launches.

Note: On macOS, you can only register protocols that have been added to your app's info.plist, which can not be modified at runtime. You can however change the file with a simple text editor or script during build time. Please refer to Apple's documentation for details.

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-是否成功调用。

此方法检查当前程序是否为协议（也称为URI scheme）的默认处理程序。 如果是，它会删除应用程序作为默认处理程序。

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

• protocol String - The name of your protocol, without ://.
• path String (optional) Windows - Defaults to process.execPath
• args String Windows - Defaults to an empty array

Returns Boolean - Whether the call succeeded.

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 - 默认为空数组

返回 Boolean

此方法检查当前可执行文件是否是协议(也称为URI方案) 的默认处理程序。如果是, 它将返回true。否则, 它将返回false。

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

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

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

• protocol String - The name of your protocol, without ://.
• path String (optional) Windows - Defaults to process.execPath
• args String Windows - Defaults to an empty array

Returns Boolean

This method checks if the current executable is the default handler for a protocol (aka URI scheme). If so, it will return true. Otherwise, it will return false.

Note: On macOS, you can use this method to check if the app has been registered as the default protocol handler for a protocol. You can also verify this by checking ~/Library/Preferences/com.apple.LaunchServices.plist on the macOS machine. Please refer to Apple's documentation for details.

The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internally.

app.setUserTasks(tasks) Windows

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

将 tasks 添加到 Windows 中 JumpList 功能的 Tasks 分类中。

tasks 是 Task 对象组成的数组

返回 Boolean-是否成功调用。

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

app.setUserTasks(tasks) Windows

• tasks Task[] - Array of Task objects

Adds tasks to the Tasks category of the JumpList on Windows.

tasks is an array of Task objects.

Returns Boolean - Whether the call succeeded.

Note: If you'd like to customize the Jump List even more use app.setJumpList(categories) instead.

app.getJumpListSettings() Windows

返回 Object:

• minItems Integer - 将在跳转列表中显示项目的最小数量(有关此值的更详细描述，请参阅 MSDN docs).
• removedItems JumpListItem[] - JumpListItem 对象组成的数组，对应用户在跳转列表中明确删除的项目。 这些项目不能在 next 调用 app.setJumpList() 时重新添加到跳转列表中, Windows不会显示任何包含已删除项目的自定义类别.

app.getJumpListSettings() Windows

Returns Object:

• minItems Integer - The minimum number of items that will be shown in the Jump List (for a more detailed description of this value see the MSDN docs).
• removedItems JumpListItem[] - Array of JumpListItem objects that correspond to items that the user has explicitly removed from custom categories in the Jump List. These items must not be re-added to the Jump List in the next call to app.setJumpList(), Windows will not display any custom category that contains any of the removed items.

app.setJumpList(categories) Windows

• categories JumpListCategory[] or null - JumpListCategory 对象组成的数组

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

• ok - 没有出现错误
• error - 发生一个或多个错误，启用运行日志记录找出可能的原因。
• invalidSeparatorError - 尝试向跳转列表中的自定义跳转列表添加分隔符。 分隔符只允许在标准的 Tasks 类别中。
• fileTypeRegistrationError -尝试向自定义跳转列表添加一个文件链接，但是该应用未注册处理该应用类型
• customCategoryAccessDeniedError - 由于用户隐私或策略组设置，自定义类别无法添加到跳转列表。

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

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

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

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

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' }
    ]
  },
  { // 已经有一个名字所以 `type` 被认为是 "custom"
    name: 'Tools',
    items: [{  type: 'task',  title: 'Tool A',  program: process.execPath,  args: '--run-tool-a',  icon: process.execPath,  iconIndex: 0,  description: 'Runs Tool A'},{  type: 'task',  title: 'Tool B',  program: process.execPath,  args: '--run-tool-b',  icon: process.execPath,  iconIndex: 0,  description: 'Runs Tool B'}
    ]
  },
  { type: 'frequent' },
  { //这里没有设置名字 所以 `type` 被认为是 "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.setJumpList(categories) Windows

• categories JumpListCategory[] or null - Array of JumpListCategory objects.

Sets or removes a custom Jump List for the application, and returns one of the following strings:

• ok - Nothing went wrong.
• error - One or more errors occurred, enable runtime logging to figure out the likely cause.
• 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 - An attempt was made to add a file link to the Jump List for a file type the app isn't registered to handle.
• customCategoryAccessDeniedError - Custom categories can't be added to the Jump List due to user privacy or group policy settings.

If categories is null the previously set custom Jump List (if any) will be replaced by the standard Jump List for the app (managed by Windows).

Note: If a JumpListCategory object has neither the type nor the name property set then its type is assumed to be tasks. If the name property is set but the type property is omitted then the type is assumed to be custom.

Note: Users can remove items from custom categories, and Windows will not allow a removed item to be added back into a custom category until after the next successful call to app.setJumpList(categories). Any attempt to re-add a removed item to a custom category earlier than that will result in the entire custom category being omitted from the Jump List. The list of removed items can be obtained using app.getJumpListSettings().

Here's a very simple example of creating a custom 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',  icon: process.execPath,  iconIndex: 0,  description: 'Runs Tool A'},{  type: 'task',  title: 'Tool B',  program: process.execPath,  args: '--run-tool-b',  icon: 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()

返回 Boolean

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

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

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

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

const { app } = require('electron')
let myWindow = null
const gotTheLock = app.requestSingleInstanceLock()
if (!gotTheLock) {
  app.quit()
} else {
  app.on('second-instance', (event, commandLine, workingDirectory) => {
    // 当运行第二个实例时,将会聚焦到myWindow这个窗口
    if (myWindow) {if (myWindow.isMinimized()) myWindow.restore()myWindow.focus()
    }
  })
  // 创建 myWindow, 加载应用的其余部分, etc...
  app.on('ready', () => {
  })
}

app.requestSingleInstanceLock()

Returns Boolean

The return value of this method indicates whether or not this instance of your application successfully obtained the lock. If it failed to obtain the lock, you can assume that another instance of your application is already running with the lock and exit immediately.

I.e. This method returns true if your process is the primary instance of your application and your app should continue loading. It returns false if your process should immediately quit as it has sent its parameters to another instance that has already acquired the lock.

On macOS, the system enforces single instance automatically when users try to open a second instance of your app in Finder, and the open-file and open-url events will be emitted for that. However when users start your app in command line, the system's single instance mechanism will be bypassed, and you have to use this method to ensure single instance.

An example of activating the window of primary instance when a second instance starts:

const { app } = require('electron')
let myWindow = null
const gotTheLock = app.requestSingleInstanceLock()
if (!gotTheLock) {
  app.quit()
} else {
  app.on('second-instance', (event, commandLine, workingDirectory) => {
    // Someone tried to run a second instance, we should focus our window.
    if (myWindow) {if (myWindow.isMinimized()) myWindow.restore()myWindow.focus()
    }
  })
  // Create myWindow, load the rest of the app, etc...
  app.on('ready', () => {
  })
}

app.hasSingleInstanceLock()

返回 Boolean

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

app.hasSingleInstanceLock()

Returns Boolean

This method returns whether or not this instance of your app is currently holding the single instance lock. You can request the lock with app.requestSingleInstanceLock() and release with app.releaseSingleInstanceLock()

app.releaseSingleInstanceLock()

释放由requestSingleInstanceLock创建的所有锁。这将允许应用中的多例再次同时执行。

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 Object - 应用程序特定状态，供其他设备使用
• webpageURL String (可选) - 如果在恢复设备上未安装合适的应用程序，则会在浏览器中加载网页。 该格式必须是 http 或 https。

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

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

• type String - Uniquely identifies the activity. Maps to NSUserActivity.activityType.
• userInfo Object - 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.

Creates an NSUserActivity and sets it as the current activity. The activity is eligible for Handoff to another device afterward.

app.getCurrentActivityType() macOS

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

app.getCurrentActivityType() macOS

Returns String - The type of the currently running activity.

app.invalidateCurrentActivity() macOS

• type String - 活动的唯一标识。 映射到 NSUserActivity. activityType。

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

app.invalidateCurrentActivity() macOS

• type String - Uniquely identifies the activity. Maps to NSUserActivity.activityType.

Invalidates the current Handoff user activity.

app.updateCurrentActivity(type, userInfo) macOS

• type String - 活动的唯一标识。 映射到 NSUserActivity. activityType。
• userInfo Object - 应用程序特定状态，供其他设备使用

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

app.updateCurrentActivity(type, userInfo) macOS

• type String - Uniquely identifies the activity. Maps to NSUserActivity.activityType.
• userInfo Object - App-specific state to store for use by another device.

Updates the current activity if its type matches type, merging the entries from userInfo into its current userInfo dictionary.

app.setAppUserModelId(id) Windows

• id String

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

app.setAppUserModelId(id) Windows

• id String

Changes the Application User Model ID to id.

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.importCertificate(options, callback) LINUX

• options Object

  • certificate String - Path for the pkcs12 file.
  • password String - Passphrase for the certificate.

• callback Function

  • result Integer - Result of import.

Imports the certificate in pkcs12 format into the platform certificate store. callback is called with the result of import operation, a value of 0 indicates success while any other value indicates failure according to Chromium net_error_list.

app.disableHardwareAcceleration()

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

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

app.disableHardwareAcceleration()

Disables hardware acceleration for current app.

This method can only be called before app is ready.

app.disableDomainBlockingFor3DAPIs()

默认情况下, 如果 GPU 进程频繁崩溃, Chromium 会禁用 3D api (例如 WebGL) 直到每个域重新启动。此函数禁用该行为。

这个方法只能在应用程序准备就绪（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 behaviour.

This method can only be called before app is ready.

app.getAppMetrics()

返回 ProcessMetric[]: 包含所有与应用相关的进程的内存和CPU的使用统计的 ProcessMetric 对象的数组。

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/ 的图形功能状态。

app.getGPUFeatureStatus()

Returns GPUFeatureStatus - The Graphics Feature Status from chrome://gpu/.

app.getGPUInfo(infoType)

• infoType String - 值可以是基本信息的basic，也可以是完整信息的complete

返回 Promise

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。 下面是一个基础响应示例：

{ 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或driverId，则应优先使用basic。

app.getGPUInfo(infoType)

• infoType String - Values can be either basic for basic info or complete for complete info.

Returns Promise

For infoType equal to complete: Promise is fulfilled with Object containing all the GPU Information as in chromium's GPUInfo object. This includes the version and driver information that's shown on chrome://gpu page.

For infoType equal to basic: Promise is fulfilled with Object containing fewer attributes than when requested with complete. Here's an example of basic response:

{ 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' }

Using basic should be preferred if only basic information like vendorId or driverId is needed.

app.setBadgeCount(count) Linux macOS

• count Integer

返回 Boolean-是否成功调用。

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

在macOS系统中，它会展示在dock图标上。在 Linux 系统中，它只会在Unity启动器中展示。

注意: 联合启动器需要.desktop文件的存在和工作， 获得更多信息请阅读 Desktop Environment Integration。

app.setBadgeCount(count) Linux macOS

• count Integer

Returns Boolean - Whether the call succeeded.

Sets the counter badge for current app. Setting the count to 0 will hide the badge.

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

Note: Unity launcher requires the existence of a .desktop file to work, for more information please read Desktop Environment Integration.

app.getBadgeCount() Linux macOS

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

app.getBadgeCount() Linux macOS

Returns Integer - The current value displayed in the counter badge.

app.isUnityRunning() Linux

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

app.isUnityRunning() Linux

Returns Boolean - Whether the current desktop environment is Unity launcher.

app.getLoginItemSettings([options]) macOS Windows

• options Object (可选)

  • pathString (可选) Windows -要比较的可执行文件路径。默认为 process. execPath。
  • 参数String Windows -要比较的命令行参数。默认为空数组。

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

返回 Object:

• openAtLogin Boolean - true 如果应用程序设置为在登录时打开, 则为 <0>true</0>
• openAsHidden Boolean macOS - true 表示应用在登录时以隐藏的方式启动。 该配置在 MAS 构建 时不可用。
• wasOpenedAtLogin Boolean macOS - true 表示应用在自动登录后已经启动。 该配置在 MAS 构建 时不可用。
• wasOpenedAsHiddenBoolean macOS - 如果应用在登录时已经隐藏启动, 则为 true。 这表示应用程序在启动时不应打开任何窗口。 该配置在 MAS 构建 时不可用。
• restoreState Boolean macOS - true 表示应用作为登录启动项并且需要恢复之前的会话状态。 这表示程序应该还原上次关闭时打开的窗口。 该配置在 MAS 构建 时不可用。

app.getLoginItemSettings([options]) macOS Windows

• options Object (optional)

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

If you provided path and args options to app.setLoginItemSettings, then you need to pass the same arguments here for openAtLogin to be set correctly.

Returns Object:

• openAtLogin Boolean - true if the app is set to open at login.
• openAsHidden Boolean macOS - true if the app is set to open as hidden at login. This setting is not available on MAS builds.
• wasOpenedAtLogin Boolean macOS - true if the app was opened at login automatically. This setting is not available on MAS builds.
• wasOpenedAsHidden Boolean macOS - true if the app was opened as a hidden login item. This indicates that the app should not open any windows at startup. This setting is not available on MAS builds.
• restoreState Boolean macOS - true if the app was opened as a login item that should restore the state from the previous session. This indicates that the app should restore the windows that were open the last time the app was closed. This setting is not available on MAS builds.

app.setLoginItemSettings(settings) macOS Windows

• settings Object

  • openAtLogin Boolean (可选) - true在登录时启动应用，false 移除应用作为登录启动项 。默认为 false.
  • openAsHidden Boolean (可选) macOS - true 表示以隐藏的方式启动应用。 默认为false。 用户可以从系统首选项中编辑此设置, 以便在打开应用程序时检查 app.getLoginItemSettings().wasOpenedAsHidden 以了解当前值。 该配置在 MAS 构建 时不可用。
  • path String (可选) Windows - 在登录时启动的可执行文件。默认为 process.execPath.
  • args String Windows - 要传递给可执行文件的命令行参数。默认为空数组。注意用引号将路径换行。

设置应用程序的登录项设置。

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

const appFolder = path.dirname(process.execPath)
const updateExe = path.resolve(appFolder, '..', 'Update.exe')
const exeName = path.basename(process.execPath)
app.setLoginItemSettings({
  openAtLogin: true,
  path: updateExe,
  args: [
    '--processStart', `"${exeName}"`,
    '--process-start-args', `"--hidden"`
  ]
})

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. Defaults to false.
  • openAsHidden Boolean (optional) macOS - true to open the app as hidden. Defaults to false. The user can edit this setting from the System Preferences so app.getLoginItemSettings().wasOpenedAsHidden should be checked when the app is opened to know the current value. This setting is not available on MAS builds.
  • path String (optional) Windows - The executable to launch at login. Defaults to process.execPath.
  • args String Windows - The command-line arguments to pass to the executable. Defaults to an empty array. Take care to wrap paths in quotes.

Set the app's login item settings.

To work with Electron's autoUpdater on Windows, which uses Squirrel, you'll want to set the launch path to Update.exe, and pass arguments that specify your application name. For example:

const appFolder = path.dirname(process.execPath)
const updateExe = path.resolve(appFolder, '..', 'Update.exe')
const exeName = path.basename(process.execPath)
app.setLoginItemSettings({
  openAtLogin: true,
  path: updateExe,
  args: [
    '--processStart', `"${exeName}"`,
    '--process-start-args', `"--hidden"`
  ]
})

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*

app.isAccessibilitySupportEnabled() macOS Windows

Returns Boolean - true if Chrome's accessibility support is enabled, false otherwise. This API will return true if the use of assistive technologies, such as screen readers, has been detected. See https://www.chromium.org/developers/design-documents/accessibility for more details.

Deprecated Soon

app.showAboutPanel macOS Linux

显示应用程序关于面板选项。这些选项可以被 app.setAboutOptions(options)覆盖。

app.setAccessibilitySupportEnabled(enabled) macOS Windows

• enabled Boolean - Enable or disable accessibility tree rendering

Manually enables Chrome's accessibility support, allowing to expose accessibility switch to users in application settings. See Chromium's accessibility docs for more details. Disabled by default.

This API must be called after the ready event is emitted.

Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.

Deprecated Soon

app.setAboutPanelOptions(options) macOS Linux

• options Object

  • applicationName String (可选) - 应用程序的名字
  • applicationVersion String (可选) - 应用程序版本
  • copyright String (可选) - 版权信息
  • version String (可选) - 应用程序版本号。macOS
  • credits String (可选) - 作者信息。macOS
  • website String (可选) - 应用网站。Linux
  • iconPath String (optional) - Path to the app's icon. Will be shown as 64x64 pixels while retaining aspect ratio. Linux

设置 "关于" 面板选项。 这将覆盖应在MacOS系统中应用程序的 . plist 文件中定义的值。 更多详细信息, 请查阅 Apple 文档 。 在 Linux 上，没有默认值，所以必须设置值才能显示。

app.showAboutPanel macOS Linux

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

app.isEmojiPanelSupported

Returns Boolean - whether or not the current OS version allows for native emoji pickers.

app.setAboutPanelOptions(options) macOS Linux

• options Object

  • applicationName String (optional) - The app's name.
  • applicationVersion String (optional) - The app's version.
  • copyright String (optional) - Copyright information.
  • version String (optional) - The app's build version number. macOS
  • credits String (optional) - Credit information. macOS
  • website String (optional) - The app's website. Linux
  • iconPath String (optional) - Path to the app's icon. Will be shown as 64x64 pixels while retaining aspect ratio. Linux

Set the about panel options. This will override the values defined in the app's .plist file on MacOS. See the Apple docs for more details. On Linux, values must be set in order to be shown; there are no defaults.

app.showEmojiPanel macOS Windows

Show the platform's native emoji picker.

app.isEmojiPanelSupported

Returns Boolean - whether or not the current OS version allows for native emoji pickers.

app.startAccessingSecurityScopedResource(bookmarkData) macOS (mas)

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

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

//开始读取文件
const stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)
// You can now access the file outside of the sandbox 
stopAccessingSecurityScopedResource()

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

app.showEmojiPanel macOS Windows

Show the platform's native emoji picker.

app.commandLine.appendSwitch(switch[, value])

• switch String - A command-line switch, without the leading --
• value String (optional) - 给开关设置的值

通过可选的参数 value 给 Chromium 中添加一个命令行开关。

Note: This will not affect process.argv. The intended usage of this function is to control Chromium's behavior.

app.startAccessingSecurityScopedResource(bookmarkData) macOS (mas)

• bookmarkData String - The base64 encoded security scoped bookmark data returned by the dialog.showOpenDialog or dialog.showSaveDialog methods.

Returns Function - This function must be called once you have finished accessing the security scoped file. If you do not remember to stop accessing the bookmark, kernel resources will be leaked and your app will lose its ability to reach outside the sandbox completely, until your app is restarted.

// Start accessing the file.
const stopAccessingSecurityScopedResource = app.startAccessingSecurityScopedResource(data)
// You can now access the file outside of the sandbox 
// Remember to stop accessing the file once you've finished with it.
stopAccessingSecurityScopedResource()

Start accessing a security scoped resource. With this method Electron applications that are packaged for the Mac App Store may reach outside their sandbox to access files chosen by the user. See Apple's documentation for a description of how this system works.

app.commandLine.appendArgument(value)

• valueString - 要追加到命令行的参数

Append an argument to Chromium's command line. The argument will be quoted correctly. Switches will precede arguments regardless of appending order.

If you're appending an argument like --switch=value, consider using appendSwitch('switch', 'value') instead.

Note: This will not affect process.argv. The intended usage of this function is to control Chromium's behavior.

app.commandLine.appendSwitch(switch[, value])

• switch String - A command-line switch, without the leading --
• value String (optional) - A value for the given switch

Append a switch (with optional value) to Chromium's command line.

Note: This will not affect process.argv. The intended usage of this function is to control Chromium's behavior.

app.commandLine.hasSwitch(switch)

• switch String - 命令行开关

返回Boolean - 命令行开关是否打开。

app.commandLine.appendArgument(value)

• value String - The argument to append to the command line

Append an argument to Chromium's command line. The argument will be quoted correctly. Switches will precede arguments regardless of appending order.

If you're appending an argument like --switch=value, consider using appendSwitch('switch', 'value') instead.

Note: This will not affect process.argv. The intended usage of this function is to control Chromium's behavior.

app.commandLine.getSwitchValue(switch)

• switch String - 命令行开关

返回 String - 命令行开关值。

Note: When the switch is not present or has no value, it returns empty string.

app.commandLine.hasSwitch(switch)

• switch String - A command-line switch

Returns Boolean - Whether the command-line switch is present.

app.enableSandbox() 实验功能

在应用程序上启用完全沙盒模式。

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

app.commandLine.getSwitchValue(switch)

• switch String - A command-line switch

Returns String - The command-line switch value.

Note: When the switch is not present or has no value, it returns empty string.

app.isInApplicationsFolder() macOS

返回 Boolean- 应用程序当前是否在系统应用程序文件夹运行。 可以搭配 app. moveToApplicationsFolder ()使用

app.enableSandbox() Experimental

Enables full sandbox mode on the app.

This method can only be called before app is ready.

app.moveToApplicationsFolder() macOS

返回 Boolean-移动是否成功。 请注意, 当您的应用程序移动成功, 它将退出并重新启动。

默认情况下这个操作将不会显示任何确认对话框, 如果您希望让用户来确认操作，你可能需要使用 dialog API

注意:如果并非是用户造成操作失败，这个方法会抛出错误。 例如，如果用户取消了授权会话，这个方法将返回false。 如果无法执行复制操作, 则此方法将抛出错误。 错误中的信息应该是信息性的，并告知具体问题。

app.isInApplicationsFolder() macOS

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

app.dock.bounce([type]) macOS

• type String (可选) - 可以为critical 或 informational. 默认值为 informational

当传入的是 critical 时, dock 中的应用将会开始弹跳, 直到这个应用被激活或者这个请求被取消。

当传入的是 informational 时, dock 中的图标只会弹跳一秒钟。但是, 这个请求仍然会激活, 直到应用被激活或者请求被取消。

返回 Integer 这个请求的 ID

app.moveToApplicationsFolder() macOS

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.

NOTE: This method throws errors if anything other than the user causes the move to fail. For instance if the user cancels the authorization dialog, this method returns false. If we fail to perform the copy, then this method will throw an error. The message in the error should be informative and tell you exactly what went wrong

app.dock.cancelBounce(id) macOS

• id Integer

取消这个 id 对应的请求。

app.dock.bounce([type]) macOS

• type String (optional) - Can be critical or informational. The default is informational

When critical is passed, the dock icon will bounce until either the application becomes active or the request is canceled.

When informational is passed, the dock icon will bounce for one second. However, the request remains active until either the application becomes active or the request is canceled.

Returns Integer an ID representing the request.

app.dock.downloadFinished(filePath) macOS

• filePath String

如果 filePath 位于 Downloads 文件夹中，则弹出下载队列。

app.dock.cancelBounce(id) macOS

• id Integer

Cancel the bounce of id.

app.dock.setBadge(text) macOS

• text String

设置应用在 dock 中显示的字符串。

app.dock.downloadFinished(filePath) macOS

• filePath String

Bounces the Downloads stack if the filePath is inside the Downloads folder.

app.dock.getBadge() macOS

返回 String - 应用在 dock 中显示的字符串。

app.dock.setBadge(text) macOS

• text String

Sets the string to be displayed in the dock’s badging area.

app.dock.hide() macOS

隐藏 dock 中的图标。

app.dock.getBadge() macOS

Returns String - The badge string of the dock.

app.dock.show() macOS

Returns Promise<void> - Resolves when the dock icon is shown.

app.dock.hide() macOS

Hides the dock icon.

app.dock.isVisible() macOS

Returns Boolean - Whether the dock icon is visible.

app.dock.show() macOS

Returns Promise<void> - Resolves when the dock icon is shown.

app.dock.setMenu(menu) macOS

• menu Menu

设置应用程序的Dock 菜单。

app.dock.isVisible() macOS

Returns Boolean - Whether the dock icon is visible.

app.dock.getMenu() macOS

Returns Menu | null - The application's dock menu.

app.dock.setMenu(menu) macOS

• menu Menu

Sets the application's dock menu.

app.dock.setIcon(image) macOS

• image (NativeImage | String)

设置image作为应用在 dock 中显示的图标

app.dock.getMenu() macOS

Returns Menu | null - The application's dock menu.

属性

app.dock.setIcon(image) macOS

• image (NativeImage | String)

Sets the image associated with this dock icon.

app.applicationMenu

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

Properties

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. Disabled by default.

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

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

app.applicationMenu

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

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. Useful for ensuring your entire app has the same user agent. Set to a custom value as early as possible in your apps initialization to ensure that your overridden value is used.

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. Disabled by default.

This API must be called after the ready event is emitted.

Note: Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.

app.isPackaged

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

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. Useful for ensuring your entire app has the same user agent. Set to a custom value as early as possible in your apps 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 false.

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.isPackaged

A Boolean property that returns true if the app is packaged, false otherwise. For many apps, this property can be used to distinguish development and production environments.