app

app

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

过程:主

以下示例显示如何在最后一个窗口关闭时退出应用程序:

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

Events

app对象发出以下事件:

Event: ‘will-finish-launching’

应用程序完成基本启动时发出。在Windows和Linux上,will-finish-launching事件与事件相同ready; 在macOS上,此事件表示applicationWillFinishLaunching通知NSApplication。您通常会在此处设置侦听器open-fileopen-url事件,并启动崩溃记录器和自动更新器。

在大多数情况下,你应该在ready事件处理程序中做所有事情。

Event: ‘ready’

返回:

  • launchInfo Object macOS

Electron完成初始化时发射。在MacOS,launchInfo持有userInfoNSUserNotification是被用来打开应用程序,如果它是从通知中心启动。你可以调用app.isReady()来检查这个事件是否已经被完成。

Event: ‘window-all-closed’

所有窗户关闭时发射。

如果您未订阅此事件并关闭了所有窗口,则默认行为是退出该应用程序; 但是,如果您订阅,则可以控制应用程序是否退出。如果用户按下了Cmd + Q,或者开发人员调用了app.quit(),Electron会首先关闭所有窗口,然后发出will-quit事件,在这种情况下,window-all-closed事件不会被发射。

Event: ‘before-quit’

返回:

  • event Event

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

注:如果应用程序退出被发起autoUpdater.quitAndInstall(),然后before-quit被发射后,发射close所有的Windows事件和关闭它们。

Event: ‘will-quit’

返回:

  • event Event

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

请参阅window-all-closed事件描述以了解事件will-quitwindow-all-closed事件之间的差异。

Event: ‘quit’

返回:

  • event Event

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

Event: ‘open-file’ macOS

返回:

  • event Event

当用户想要用应用程序打开文件时发出。该open-file事件通常在应用程序已经打开并且操作系统想要重新使用应用程序打开文件时发出。open-file当文件被拖放到Dock上并且应用程序尚未运行时也会发出。确保open-file在应用程序启动时尽早监听事件以处理这种情况(甚至在ready事件发生之前)。

event.preventDefault()如果你想处理这个事件,你应该打电话。

在 Windows 上,您必须解析process.argv(在主进程中)获取文件路径。

Event: ‘open-url’ macOS

返回:

  • event Event

用户想要在应用程序中打开URL时发出。您的应用程序Info.plist文件必须在CFBundleURLTypes密钥中定义url方案,并设置NSPrincipalClassAtomApplication

event.preventDefault()如果你想处理这个事件,你应该打电话。

Event: ‘activate’ macOS

返回:

  • event Event

应用程序激活时发射。各种操作都可能触发此事件,例如第一次启动应用程序,试图在应用程序已经运行时重新启动应用程序,或者单击应用程序的停靠栏或任务栏图标。

Event: ‘continue-activity’ macOS

返回:

  • event 事件

当来自不同设备的活动想要恢复时,在切换期间发送。event.preventDefault()如果你想处理这个事件,你应该打电话。

用户活动只能在具有与活动的源应用程序相同的开发者团队ID并支持活动类型的应用程序中继续。受支持的活动类型在应用程序的密钥Info.plist下指定NSUserActivityTypes

Event: ‘new-window-for-tab’ macOS

返回:

  • event Event

用户单击本地macOS新选项卡按钮时发出。新选项卡按钮仅在当前BrowserWindow有a 按钮时才可见tabbingIdentifier

Event: ‘browser-window-blur’

返回:

  • event 事件

浏览器窗口变得模糊时发射。

Event: ‘browser-window-focus’

返回:

  • event 事件

浏览器窗口关注时发射。

Event: ‘browser-window-created’

返回:

  • event 事件

在创建新的 browserWindow 时发出。

Event: ‘web-contents-created’

返回:

  • event 事件

在创建新的webContents时发出。

Event: ‘certificate-error’

返回:

  • event 事件

发生失败时验证certificatefor url,要信任证书,您应该使用event.preventDefault()和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) } })

Event: ‘select-client-certificate’

返回:

  • event 事件

在请求客户端证书时发送。

url对应于导航条目请求客户端证书,并callback可以从列表过滤条目被调用。使用event.preventDefault()阻止应用程序使用商店中的第一个证书。

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

Event: ‘login’

返回:

  • event 事件

webContents想要进行基本身份验证时发出。

默认行为是取消所有认证,为了覆盖这一点,您应该防止默认行为event.preventDefault()callback(username, password)使用凭据进行调用。

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

Event: ‘gpu-process-crashed’

返回:

  • event Event

gpu 进程崩溃或死亡时发出。

Event: ‘accessibility-support-changed’ macOS Windows

返回:

  • event 事件

当Chrome的辅助功能支持发生变化时发出。当辅助技术(如屏幕阅读器)处于启用或禁用状态时,此事件会触发。有关更多详细信息,请参阅https://www.chromium.org/developers/design-documents/accessibility

方法

app对象具有以下方法:

注意:某些方法仅在特定操作系统上可用,并且被标记为这样。

app.quit()

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

这种方法保证所有beforeunloadunload事件处理程序是正确执行。有可能窗口通过falsebeforeunload事件处理程序中返回来取消退出。

app.exit([exitCode])

  • exitCode 整数(可选)

立即退出exitCodeexitCode默认为0。

所有窗口将立即关闭而不询问用户,before-quit并且will-quit事件不会被发射。

app.relaunch([options])

  • options 对象(可选)

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

默认情况下,新实例将使用与当前实例相同的工作目录和命令行参数。当args指定时,该args命令将作为命令行参数传递。当execPath指定时,execPath将执行重新启动而不是当前应用程序。

请注意,此方法在执行时不会退出应用程序,您必须调用app.quitapp.exit在调用后app.relaunch重新启动应用程序。

app.relaunch多次调用时,多个实例将在当前实例退出后启动。

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

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

app.isReady()

返回Boolean- true如果Electron已完成初始化,false否则。

app.focus()

在Linux上,重点关注第一个可见窗口。在macOS上,使应用程序成为活动应用程序。在Windows上,重点关注应用程序的第一个窗口。

app.hide() macOS

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

app.show() macOS

隐藏后显示应用程序窗口。不会自动关注它们。

app.getAppPath()

返回String- 当前应用程序目录。

app.getPath(name)

  • name String

返回String- 与特定目录或文件关联的路径name。失败时Error抛出。

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

  • home 用户的主目录。

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

  • path

获取路径的关联图标。

Windows上,有两种图标:

  • 某些文件扩展名,如相关联的图标.mp3.png等等。

LinuxMacOS上,图标取决于与文件MIME类型关联的应用程序。

app.setPath(name, path)

  • name String

Overrides the path to a special directory or file associated with name. If the path specifies a directory that does not exist, the directory will be created by this method. On failure an Error is thrown.

您只能覆盖name定义的路径app.getPath

默认情况下,网页的Cookie和缓存将被存储在userData目录下。如果要更改此位置,则必须在模块事件发出userData之前覆盖路径。readyapp

app.getVersion()

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

app.getName()

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

根据npm模块规范,通常这个name字段package.json是一个短小的名字。您通常也应该指定一个productName字段,这是您的应用程序的全名大写字母,并且将优先于nameElectron。

app.setName(name)

  • name String

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

app.getLocale()

返回String- 当前应用程序语言环境。这里记录可能的返回值。

注意:分发打包的应用程序时,您还必须运送该locales文件夹。

注意:在Windows上,必须在ready事件发出后调用它。

app.addRecentDocument(path) macOS Windows

  • path String

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

该列表由OS管理。在Windows上,您可以从任务栏访问列表,在macOS上,您可以通过扩展坞菜单访问它。

app.clearRecentDocuments() macOS Windows

清除最近的文档列表。

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

  • protocol字符串 - 协议的名称,不含://。如果您希望您的应用处理electron://链接,请使用此方法electron作为参数。

返回Boolean- 调用是否成功。

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

在Windows上,您可以提供可选参数路径,可执行文件的路径以及参数,这些参数将在启动时传递给可执行文件。

注意:在macOS上,只能注册已添加到应用程序的协议,这些协议info.plist在运行时不能修改。但是,您可以在构建期间使用简单的文本编辑器或脚本更改文件。有关详细信息,请参阅Apple的文档。

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

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

  • protocol字符串 - 协议的名称,不含://

返回Boolean- 调用是否成功。

此方法检查当前的可执行文件是否为协议的默认处理程序(又名URI方案)。如果是这样,它将删除该应用程序作为默认处理程序。

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

  • protocol字符串 - 协议的名称,不含://

Returns Boolean

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

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

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

app.setUserTasks(tasks) Windows

  • tasks Task[] - Array of Task objects

添加tasks到Windows上的JumpList 的任务(http://msdn.microsoft.com/en-us/library/windows/desktop/dd378460(v = vs.85%29.aspx#tasks))类别。

tasks是一个Task对象数组。

返回Boolean- 调用是否成功。

注意:如果您想自定义跳转列表,请app.setJumpList(categories)改用它。

app.getJumpListSettings() Windows

返回Object

  • minItems整数 - 将在跳转列表中显示的项目的最小数量(有关此值的更详细说明,请参阅MSDN文档。

app.setJumpList(categories) Windows

  • categoriesJumpListCategory []或者null- JumpListCategory对象数组。

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

  • ok - 没有出错。

如果categoriesnull以前设置的自定义跳转列表(如果有的话)将被用于应用程序(由Windows管理)标准的跳转列表进行更换。

注意:如果一个JumpListCategory对象既type没有name设置也没有设置属性,那么它type被假定为tasks。如果该name属性已设置,但该type属性被忽略,type则假定该属性为custom

注:用户可以从自定义类别中删除项目,和Windows将不允许添加一个删除的项目回一个自定义类别,直到之后的下一个成功的调用app.setJumpList(categories)。任何尝试重新添加删除项目到自定义类别之前,都会导致整个自定义类别从跳转列表中被省略。已删除项目的列表可以使用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' } ] }, { // 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.makeSingleInstance(callback)

  • callback 功能

返回Boolean

此方法使您的应用程序成为单实例应用程序 - 而不是允许您的应用程序的多个实例运行,这将确保只有您的应用程序的单个实例正在运行,并且其他实例指示此实例并退出。

callback将在第一个实例与callback(argv, workingDirectory)第二个实例执行时调用。argv是第二个实例的命令行参数的数组,并且workingDirectory是其当前工作目录。通常情况下,应用程序通过使其主窗口专注于非最小化来对此作出响应。

callback是保证后要执行ready的事件app时发出。

false如果您的进程是应用程序的主要实例并且您的应用程序应该继续加载,则此方法返回。并返回true,如果你的进程已派出它的参数到另一个实例,你应该立即退出。

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

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

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

app.releaseSingleInstance()

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

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

  • type字符串 - 唯一标识活动。映射到NSUserActivity.activityType

创建一个NSUserActivity并将其设置为当前活动。该活动是符合切换到后来其他设备。

app.getCurrentActivityType() macOS

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

app.setAppUserModelId(id) Windows

  • id String

将应用程序用户模型 ID(https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v = vs.85%29.aspx)更改为id

app.importCertificate(options, callback) LINUX

  • options 目的

将pkcs12格式的证书导入平台证书存储区。callbackresult导入操作一起调用时,值0表示成功,而任何其他值表示根据铬net_error_list失败。

app.disableHardwareAcceleration()

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

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

app.disableDomainBlockingFor3DAPIs()

默认情况下,如果GPU进程过于频繁地崩溃,则Chromium将禁用3D API(例如WebGL),直到每个域重新启动为止。该功能禁用该行为。

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

app.getAppMemoryInfo() Deprecated

返回ProcessMetric[]ProcessMetric对应于与应用程序关联的所有进程的内存和CPU使用情况统计信息的对象数组。注意:此方法已弃用,请app.getAppMetrics()改用。

app.getAppMetrics()

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

app.getGpuFeatureStatus()

返回GPUFeatureStatus- 来自图形特征状态chrome://gpu/

app.setBadgeCount(count) Linux macOS

  • count 整数

返回Boolean- 调用是否成功。

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

在 macOS 上它显示在停靠栏图标上。在 Linux 上它只适用于 Unity 启动器,

注意: Unity 启动程序需要存在一个.desktop文件才能工作,有关更多信息,请阅读桌面环境集成。

app.getBadgeCount() Linux macOS

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

app.isUnityRunning() Linux

返回Boolean- 当前桌面环境是否为 Unity 启动器。

app.getLoginItemSettings([options]) macOS Windows

  • options 对象(可选)

如果你提供的pathargs选择,app.setLoginItemSettings那么你需要在这里传递相同的参数进行openAtLogin正确设置。

返回Object

  • openAtLogin布尔值 - true如果应用程序设置为在登录时打开。

注意:此 API 对 MAS 构建没有影响。

app.setLoginItemSettings(settings) macOS Windows

  • settings 目的

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

autoUpdater在使用 Squirrel 的 Windows上使用 Electron ,您需要将启动路径设置为 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"` ] })

注意:此 API 对 MAS 构建没有影响。

app.isAccessibilitySupportEnabled() macOS Windows

返回Boolean- true如果 Chrome 的辅助功能支持已启用,false则返回。true如果检测到使用辅助技术(如屏幕阅读器),则此API将返回。有关更多详细信息,请参阅https://www.chromium.org/developers/design-documents/accessibility。

app.setAboutPanelOptions(options) macOS

  • options 目的

设置关于面板的选项。这将覆盖应用程序.plist文件中定义的值。有关更多详细信息,请参阅Apple文档。

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

  • switch 字符串 - 一个命令行开关

将一个开关(带有可选value)附加到 Chromium 的命令行。

注意:这不会影响process.argv,主要由开发人员用来控制一些低级别的 Chromium 行为。

app.commandLine.appendArgument(value)

  • value 字符串 - 追加到命令行的参数

在 Chromium 的命令行中追加一个参数。该论据将被正确引用。

注意:这不会影响process.argv

app.enableMixedSandbox() Experimental macOS Windows

在应用上启用混合沙盒模式。

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

app.dock.bounce([type]) macOS

  • type字符串(可选) -可以是criticalinformational。默认是informational

critical通过时,停靠栏图标将弹起,直到应用程序变为活动状态或取消请求。

何时informational通过,码头图标会弹跳一秒钟。但是,请求保持活动状态,直到应用程序变为活动状态或请求被取消。

返回Integer表示请求的ID。

app.dock.cancelBounce(id) macOS

  • id Integer

取消反弹id

app.dock.downloadFinished(filePath) macOS

  • filePath

如果 filePath 位于 Downloads 文件夹内,则弹出下载堆栈。

app.dock.setBadge(text) macOS

  • text String

设置要在码头的徽章区中显示的字符串。

app.dock.getBadge() macOS

返回String- 码头的徽章字符串。

app.dock.hide() macOS

隐藏停靠栏图标。

app.dock.show() macOS

显示停靠栏图标。

app.dock.isVisible() macOS

返回Boolean- 停靠栏图标是否可见。app.dock.show()调用是异步的,因此该方法在调用后可能不会立即返回 true。

app.dock.setMenu(menu) macOS

  • menu Menu

设置应用程序的停靠菜单

app.dock.setIcon(image) macOS

  • image (NativeImage | String)

设置image与此停靠栏图标关联。