Перейти к основному содержанию

app

Контролируйте жизненный цикл Вашего приложения.

ProcessMain

Этот пример показывает, как закрыть приложение, когда последнее окно будет закрыто:

const { app } = require('electron')

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

События​

Объект app имеет следующие события:

Событие: 'will-finish-launching'​

Происходит, когда приложение заканчивает основной запуск. На Windows и Linux событие will-finish-launching подобно событию ready; на macOS это событие представляет собой уведомление applicationWillFinishLaunching объекта NSApplication.

В большинстве случаев, Вы должны выполнять всё в обработчике события ready.

Событие: 'ready'​

Возвращает:

Происходит единожды при завершении инициализации Electron. В macOS, launchInfo содержит userInfo о NSUserNotification или информацию из UNNotificationResponse которая использовалась для открытия приложения, если оно было запущено из центра уведомлений (Notification Center). Вы также можете вызвать app.isReady() для проверки того, что событие уже произошло и app.whenReady() чтобы получить Promise, который выполнится, когда Electron будет инициализирован.

[!NOTE] The ready event is only fired after the main process has finished running the first tick of the event loop. If an Electron API needs to be called before the ready event, ensure that it is called synchronously in the top-level context of the main process.

Событие: 'window-all-closed'​

Происходит при закрытии всех окон.

Если Вы не подпишитесь на это событие, и все окна будут закрыты, поведением по умолчанию является выход из приложения; Однако, если Вы подпишитесь, то Вы определяете, будет ли приложение закрыто или нет. Если пользователь нажал Cmd + Q или разработчик вызвал app.quit(), Electron сначала попытается закрыть все окна, а затем происходит событие will-quit, и в этом случае событие window-all-closed не будет происходить.

Событие: 'before-quit'​

Возвращает:

  • event Event

Происходит до того, как приложение начнет закрывать свои окна. Вызов event.preventDefault() предотвратит поведение по умолчанию, которое приводит к прекращению работы приложения.

[!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.

[!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

Происходит при выходе из приложения.

[!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 панели, но приложение еще не запущено. Убедитесь, что обработчик события open-file в самом начале запуска Вашего приложения обрабатывает этот случай (даже прежде, чем происходит событие ready).

Вы должны вызвать event.preventDefault(), если хотите обработать это событие.

На Windows Вам необходимо распарсить process.argv (в основном процессе), чтобы получить путь к файлу.

Событие: 'open-url' macOS​

Возвращает:

  • event Event
  • url string

Происходит, когда пользователь хочет открыть URL-адрес из приложения. Файл Вашего приложения Info.plist должнен определять схему URL в ключе CFBundleURLTypes и установить NSPrincipalClass в AtomApplication.

As with the open-file event, be sure to register a listener for the open-url event early in your application startup to detect if the application is being opened to handle a URL. If you register the listener in response to a ready event, you'll miss URLs that trigger the launch of your application.

Событие: 'activate' macOS​

Возвращает:

  • event Event
  • hasVisibleWindows boolean

Происходит при активации приложения. Различные действия могут запускать это событие, например, запуск приложения в первый раз, попытка перезапустить приложение, когда оно уже запущено, или щелкнуть значок приложения в dock или панели задач.

Event: 'app-shim-connected' macOS Experimental​

Возвращает:

Emitted when an app shim connects to your app. Shims can only connect after app.startAppShimServer() has been called.

Any process running as the same user can connect. Verify the shim before creating windows in it, for example with shim.satisfiesCodeRequirement(), and call shim.quit() to reject a shim that you do not trust.

Event: 'app-shim-version-mismatch' macOS Experimental​

Возвращает:

  • event Event
  • bundlePath string - The path of the app shim's bundle.

Emitted when an app shim was launched but could not connect because your app's bundle has been replaced by a different version since your app started. A shim loads the version of Electron that is on disk, which cannot communicate with the version that is still running.

The shim quits without showing any UI, so use this event to tell the user what happened. Shims can connect again after your app restarts.

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

app.on('app-shim-version-mismatch', async () => {
const { response } = await dialog.showMessageBox({
message: `Restart ${app.name} to finish updating`,
buttons: ['Restart', 'Later']
})
if (response === 0) {
app.relaunch()
app.quit()
}
})

Событие: 'did-become-active' macOS​

Возвращает:

  • event Event

Emitted when the application becomes active. This differs from the activate event in that did-become-active is emitted every time the app becomes active, not only when Dock icon is clicked or application is re-launched. It is also emitted when a user switches to the app via the macOS App Switcher.

Event: 'did-resign-active' macOS​

Возвращает:

  • event Event

Emitted when the app is no longer active and doesn’t have focus. This can be triggered, for example, by clicking on another application or by using the macOS App Switcher to switch to another application.

Event: 'continue-activity' macOS​

Возвращает:

  • event Event
  • type string - A string identifying the activity. Maps to NSUserActivity.activityType.
  • userInfo unknown - содержит специфическое для приложения состояние, сохраненное на другом устройстве.
  • Объект details
    • webpageURL string (optional) - A string identifying the URL of the webpage accessed by the activity on another device, if available.

Emitted during Handoff when an activity from a different device wants to be resumed. Если Вы хотите обработать это событие, следует вызвать event.preventDefault().

Активность пользователя может быть продолжена только в приложении, которое имеет тот же ID команды разработчика, что и активность исходного приложения, и поддерживает тип активности. Поддерживаемые типы активности, указаны в Info.plist приложения под ключом NSUserActivityTypes.

Event: 'will-continue-activity' macOS​

Возвращает:

Emitted during Handoff before an activity from a different device wants to be resumed. Если Вы хотите обработать это событие, следует вызвать event.preventDefault().

Event: 'continue-activity-error' macOS​

Возвращает:

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

Event: 'activity-was-continued' macOS​

Возвращает:

  • event Event
  • type string - A string identifying the activity. Maps to NSUserActivity.activityType.
  • userInfo unknown - содержит специфичное, для приложения, состояние, сохраненное в хранилище по активности.

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

Event: 'update-activity-state' macOS​

Возвращает:

  • event Event
  • type string - A string identifying the activity. Maps to NSUserActivity.activityType.
  • userInfo unknown - содержит специфичное, для приложения, состояние, сохраненное в хранилище по активности.

Emitted when Handoff is about to be resumed on another device. Если Вы хотите обновить состояние, которое будет передано, Вам необходимо вызвать event.preventDefault() немедленно, собрать новый словарь userInfo и вызвать app.updateCurrentActivity() своевременно. Иначе, операция завершится ошибкой и будет вызвано continue-activity-error.

Событие: 'new-window-for-tab' macOS​

Возвращает:

  • event Event

Возникает при нажатии пользователем кнопки новой вкладки macOS. Кнопка новой вкладки отобразится только если текущий BrowserWindow имеет tabbingIdentifier.

You must create a window in this handler in order for macOS tabbing to work as expected.

Событие: 'browser-window-blur'​

Возвращает:

Emitted when a browserWindow gets blurred.

Событие: 'browser-window-focus'​

Возвращает:

Emitted when a browserWindow gets focused.

Событие: 'browser-window-created'​

Возвращает:

Emitted when a new browserWindow is created.

Событие: 'web-contents-created'​

Возвращает:

Emitted when a new webContents is created.

Событие: 'certificate-error'​

Возвращает:

  • event Event
  • webContents WebContents
  • url string
  • error string - The error code
  • certificate Certificate
  • callback Function
    • isTrusted boolean - Whether to consider the certificate as trusted
  • isMainFrame boolean

Происходит, когда не удалось проверить certificate для url, чтобы доверять сертификату, Вы должны предотвратить поведение по умолчанию с помощью event.preventDefault() и вызвать callback(true).

const { app } = require('electron')

app.on('certificate-error', (event, webContents, url, error, certificate, callback) => {
if (url === 'https://github.com') {
// Сверка логики.
event.preventDefault()
callback(true)
} else {
callback(false)
}
})

Событие: 'select-client-certificate'​

Возвращает:

Происходит, когда запрошен сертификат клиента.

url соответствует записи навигации, запрашивающей сертификат клиента, а callback можно вызвать с записью, отфильтрованной из списка. event.preventDefault() предотвращает использование первого сертификата из хранилища.

webContents is null when the request does not originate from a renderer process, for example when using net.request or net.fetch in the main process, or from a utility process created with respondToAuthRequestsFromMainProcess: true. For utility processes created without that flag, net requests proceed without a client certificate and this event is not emitted.

const { app } = require('electron')

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

Событие: 'login'​

Возвращает:

  • event Event
  • webContents WebContents | null
  • authenticationResponseDetails Object
    • url URL
    • pid number
    • isRequestForNavigation boolean - Indicates whether the request is for a navigation.
    • firstAuthAttempt boolean - Indicates whether this is the first authentication attempt.
    • responseHeaders Record<string, string | string[]> (optional) - The headers returned in the response.
  • authInfo Object
    • isProxy boolean
    • scheme string
    • host string
    • port Integer
    • realm string
  • callback Function
    • username string (optional)
    • password string (optional)

Emitted when webContents or Utility process wants to do basic auth.

Поведение по умолчанию - отмена всех аутентификаций. Чтобы переопределить это, Вы должны предотвратить поведение по умолчанию с помощью event.preventDefault() и вызвать callback(username, password) с учетными данными.

const { app } = require('electron')

app.on('login', (event, webContents, details, authInfo, callback) => {
event.preventDefault()
callback('username', 'secret')
})

Если calllback вызывается без имени пользователя или пароля, запрос аутентификации будет отменен и ошибка аутентификации будет возвращена на страницу.

Событие: 'gpu-info-update'​

Выдается при каждом обновлении информации о GPU.

Event: 'render-process-gone'​

Возвращает:

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

Событие 'child-process-gone'​

Возвращает:

  • event Event
  • Объект details
    • type string - Тип процесса. Одно из следующих значений:
      • Utility
      • Zygote
      • Sandbox helper
      • GPU
      • Pepper Plugin
      • Pepper Plugin Broker
      • Unknown
    • reason string - Причина исчезновения дочернего процесса. Возможные значения:
      • 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
      • memory-eviction - Process proactively terminated to prevent a future out-of-memory (OOM) situation
    • exitCode number - The exit code for the process (e.g. status from waitpid if on POSIX, from GetExitCodeProcess on Windows), unless reason is launch-failed, in which case exitCode will be a platform-specific launch failure error code.
    • systemErrorCode number (optional) Windows - The Windows system error code (GetLastError()) of the failed launch. Only set when reason is launch-failed.
    • serviceName string (optional) - The non-localized name of the process.
    • name string (опционально) - Название процесса. Например: Audio Service, Content Decryption Module Service, Network Service, Video Capture и т.д.

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

Событие: 'accessibility-support-changed' macOS Windows​

Возвращает:

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

Emitted when Chromium's accessibility support changes. Это событие срабатывает, когда вспомогательные технологии, такие как устройства чтения с экрана, включены или отключены. Смотрите https://www.chromium.org/developers/design-documents/accessibility для подробностей.

Событие: 'session-created'​

Возвращает:

Происходит, когда Electron создал новый объект session.

const { app } = require('electron')

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

Событие: 'second-instance'​

Возвращает:

  • event Event
  • argv string [] - массив аргументов командной строки вторичных экземпляров
  • workingDirectory string - рабочий каталог вторичных экземпляров
  • additionalData unknown - A JSON object of additional data passed from the second instance

Это событие произойдет внутри главного экземпляра Вашего приложения, когда второй экземпляр был запущен и вызывает app.requestSingleInstanceLock().

argv это массив аргументов командной строки второго экземпляра, а workingDirectory это текущий рабочий каталог. Обычно приложения реагируют на это, делая их основное окно сфокусированным и не свернутым.

Примечание

argv will not be exactly the same list of arguments as those passed to the second instance. The order might change and additional arguments might be appended. If you need to maintain the exact same arguments, it's advised to use additionalData instead.

[!NOTE] If the second instance is started by a different user than the first, the argv array will not include the arguments.

Это событие гарантировано происходит после события ready в app.

[!NOTE] Extra command line arguments might be added by Chromium, such as --original-process-start-time.

Методы​

Объект app имеет следующие методы:

[!NOTE] Some methods are only available on specific operating systems and are labeled as such.

app.quit()​

Попробуйте закрыть все окна. Сначала возникнет событие before-quit. Если все окна успешно закрыты, событие will-quit возникнет и по умолчанию приложение будет завершено.

Этот метод гарантирует, что все обработчики событий beforeunload и unload выполнятся корректно. Вполне возможно, что окно отменит выход, возвращая false в обработчике событий beforeunload.

app.exit([exitCode])​

  • exitCode Integer (опиционально)

Немедленный выход с помощью exitCode. exitCode по умолчанию 0.

Все окна будут закрыты немедленно, без разрешения пользователя, а также события before-quit и will-quit не будут происходить.

app.relaunch([options])​

  • options Object (опционально)
    • args string[] (опционально)
    • execPath string (опиционально)

Relaunches the app when the current instance exits.

By default, the new instance will use the same working directory and command line arguments as the current instance. When args is specified, the args will be passed as the command line arguments instead. When execPath is specified, the execPath will be executed for the relaunch instead of the 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 multiple times, multiple instances will be started after the current instance exits.

An example of restarting the 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 - true, если Electron завершил инициализацию, false в противном случае. См. также 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 macOS, makes the application the active app. On Windows, focuses on the application's first window. On Linux, either focuses on the first visible window (X11) or requests focus but may instead show a notification or flash the app icon (Wayland).

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

app.isActive() macOS​

Returns boolean - true if the application is active (i.e. focused).

app.hide() macOS​

Скрывает все окна приложения, не минимизируя их.

app.isHidden() macOS​

Returns boolean - true if the application—including all of its windows—is hidden (e.g. with Command-H), false otherwise.

app.show() macOS​

Показывает окна приложения после того, как они были скрыты. Автоматической фокусировки на них не происходит.

app.setAppLogsPath([path])​

  • path string (опционально) - пользовательский путь для Ваших логов. Должен быть абсолютным.

Устанавливает или создает каталог логов Вашего приложения, которые затем могут быть обработаны с помощью app.getPath() или app.setPath(pathName, newPath).

Вызов app.setAppLogsPath() без параметра path приведет к тому, что этот каталог будет установлен на ~/Library/Logs/YourAppName на macOS, и внутри директории userData на Linux и Windows.

app.getAppPath()​

Возвращает string - текущего каталога приложения.

app.getPath(name)​

  • name string - You can request the following paths by the name:
    • home домашний каталог пользователя.
    • appData Per-user application data directory, which by default points to:
      • %APPDATA% на Windows
      • $XDG_CONFIG_HOME или ~/.config на Linux
      • ~/Library/Application Support на macOS
    • assets The directory where app assets such as resources.pak are stored. By default this is the same as the folder containing the exe path. Available on Windows and Linux only.
    • userData The directory for storing your app's configuration files, which by default is the appData directory appended with your app's name. On Windows, the app's name must not contain reserved filename characters. By convention files storing user data should be written to this directory, and it is not recommended to write large files here because some environments may backup this directory to cloud storage. It is recommended to store app-specific files within a subdirectory of userData (e.g., path.join(app.getPath('userData'), 'my-app-data')) rather than directly in userData itself, to avoid naming conflicts with Chromium's own subdirectories (such as Cache, GPUCache, and Local Storage).
    • sessionData The directory for storing data generated by Session, such as localStorage, cookies, disk cache, downloaded dictionaries, network state, DevTools files and compiled GPU shaders. By default this points to userData. Chromium may write very large disk cache here, so if your app does not rely on browser storage like localStorage or cookies to save user data, it is recommended to set this directory to other locations to avoid polluting the userData directory.
    • temp временный каталог.
    • exe текущий исполняемый файл.
    • module The location of the Chromium module. By default this is synonymous with exe.
    • desktop каталог рабочего стола, текущего пользователя.
    • documents каталог пользователя для документов.
    • downloads Каталог пользователя "Downloads".
    • music каталог пользователя "Music".
    • pictures каталог пользователя для фотографии.
    • videos каталог пользователя для видео.
    • recent Directory for the user's recent files (Windows only).
    • logs каталог для логов Вашего приложения.
    • crashDumps Directory where crash dumps are stored. See Crash Reporting.

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 calling 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
      • small - 16x16
      • normal - 32x32
      • large - 48x48 on Linux, 32x32 on Windows, не поддерживается на macOS.

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

Извлекает путь значка.

На Window, есть 2 типа иконок:

  • Значки, связанные с определенными расширениями, как .mp3, .png, и т.д.
  • Значки внутри файла, таких как .exe, .dll, .ico.

На Linux и macOS иконки зависят от приложения, ассоциируемого с mime-типом файла.

app.setPath(name, path)​

  • name string
  • path string

Переопределяет path в специальный каталог или файл, связанный с name. Если путь задает каталог, который не существует, то при вызове выбросится Error. В этом случае каталог должен быть создан с помощью fs.mkdirSync или аналогичным способом.

Можно переопределять только пути name, определенное в app.getPath.

По умолчанию cookies и кэш веб-страницы будут храниться в каталоге sessionData. Если вы хотите изменить это расположение, вам необходимо переопределить путь sessionData прежде, чем событие ready модуля app возникнет.

app.getVersion()​

Возвращает string - версии загруженного приложения. Если версия не найдена в файле package.json приложения, возвращается версия текущего пакета или исполняемого файла.

app.getName()​

Возвращает string - имя текущего приложения, который является именем в файле приложения package.json.

Обычно поле name в package.json является коротким именем, написанном в нижнем регистре, согласно спецификации модулей npm. Обычно Вы должны также указать поле productName, которое пишется заглавными буквами - имя вашего приложения, и которое будет предпочтительнее name для Electron.

Electron uses the application's name to construct the default userData directory. On Windows, neither productName nor name should contain the following special characters, which cannot be used in directory or file names: <, >, :, ", \, /, |, ?, *. Using these characters in the application's name can prevent Electron from creating the default userData directory and cause the application to crash on startup.

app.setName(name)​

  • name string

Переопределяет имя текущего приложения.

On Windows, avoid the reserved filename characters in name.

[!NOTE] This function overrides the name used internally by Electron; it does not affect the name that the OS uses.

app.setDesktopName(name) Linux​

  • name string - The .desktop filename (e.g. 'com.example.MyApp.desktop').

Sets the .desktop filename on Linux. This must match the base filename of the app's installed .desktop file. The .desktop suffix is optional.

The name (without the .desktop suffix) is the app's identity for Linux desktop integration. It should be a reverse-DNS style ID such as com.example.MyApp, following the desktop entry naming conventions. This value is used as:

  • the XDG application ID (app_id) on Wayland and WM_CLASS on X11, used to match the app's icon and window grouping.
  • the app ID that xdg-desktop-portal reports to portal backends such as GlobalShortcuts.

Portals increasingly enforce this identity. If the name is not a valid reverse-DNS ID or does not match an installed .desktop file:

  • GNOME 50.0/50.1 (Ubuntu 26.04) rejects globalShortcut binds with org.freedesktop.portal.Error.NotAllowed — with no error surfaced to the app (see #52218).
  • xdg-desktop-portal 1.21 and later refuses portal sessions for app IDs it cannot resolve to a .desktop file.

If this value is not set and desktopName is not present in package.json, Electron falls back to a lowercased, hyphenated slug of the app's name (e.g. My App → my-app.desktop), which is unlikely to be a valid portal identity — packaged apps should always set it explicitly.

This API must be called before the ready event. The value can also be set using desktopName in package.json.

app.getLocale()​

Returns string - The current application locale, fetched using Chromium's l10n_util library. 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] This API must be called after the ready event is emitted.

[!NOTE] To see example return values of this API compared to other locale and language APIs, see app.getPreferredSystemLanguages().

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.getSystemLocale()​

Returns string - The current system locale. On Windows and Linux, it is fetched using Chromium's i18n library. On macOS, [NSLocale currentLocale] is used instead. To get the user's current system language, which is not always the same as the locale, it is better to use app.getPreferredSystemLanguages().

Different operating systems also use the regional data differently:

  • Windows 11 uses the regional format for numbers, dates, and times.
  • macOS Monterey uses the region for formatting numbers, dates, times, and for selecting the currency symbol to use.

Therefore, this API can be used for purposes such as choosing a format for rendering dates and times in a calendar app, especially when the developer wants the format to be consistent with the OS.

[!NOTE] This API must be called after the ready event is emitted.

[!NOTE] To see example return values of this API compared to other locale and language APIs, see app.getPreferredSystemLanguages().

app.getPreferredSystemLanguages()​

Returns string[] - The user's preferred system languages from most preferred to least preferred, including the country codes if applicable. A user can modify and add to this list on Windows or macOS through the Language and Region settings.

The API uses GlobalizationPreferences (with a fallback to GetSystemPreferredUILanguages) on Windows, \[NSLocale preferredLanguages\] on macOS, and g_get_language_names on Linux.

This API can be used for purposes such as deciding what language to present the application in.

Here are some examples of return values of the various language and locale APIs with different configurations:

On Windows, given application locale is German, the regional format is Finnish (Finland), and the preferred system languages from most to least preferred are French (Canada), English (US), Simplified Chinese (China), Finnish, and Spanish (Latin America):

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

On macOS, given the application locale is German, the region is Finland, and the preferred system languages from most to least preferred are French (Canada), English (US), Simplified Chinese, and Spanish (Latin America):

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

Both the available languages and regions and the possible return values differ between the two operating systems.

As can be seen with the example above, on Windows, it is possible that a preferred system language has no country code, and that one of the preferred system languages corresponds with the language used for the regional format. On macOS, the region serves more as a default country code: the user doesn't need to have Finnish as a preferred language to use Finland as the region, and the country code FI is used as the country code for preferred system languages that do not have associated countries in the language name.

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

Returns string[] - An array containing documents in the most recent documents list.

const { app } = require('electron')

const path = require('node:path')

const file = path.join(app.getPath('desktop'), 'foo.txt')
app.addRecentDocument(file)

const recents = app.getRecentDocuments()
console.log(recents) // ['/path/to/desktop/foo.txt'}

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

  • protocol string - имя вашего протокола, без ://. 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. По умолчанию process.execPath
  • args string[] (optional) Windows - Arguments passed to the executable. По умолчанию пустой массив

Возвращает 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. 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 - имя вашего протокола, без ://.
  • path string (optional) Windows - по умолчанию process.execPath
  • args string[] (optional) 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 - имя вашего протокола, без ://.
  • path string (optional) Windows - по умолчанию process.execPath
  • args string[] (optional) Windows - по умолчанию пустой массив

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

[!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.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)​

  • 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://).

Возвращает Promise<Object> - Разрешить с объектом, содержащим следующее:

  • 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[] - Array of Task objects

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

tasks is an array of Task objects.

Возвращает boolean - успешный ли вызов.

[!NOTE] If you'd like to customize the Jump List even more use app.setJumpList(categories) instead.

app.getJumpListSettings() Windows​

Возвращает 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. Эти элементы не должны быть снова добавлены в список переходов, при следующем вызове app.setJumpList(), Windows не будет отображать любую пользовательскую категорию, содержащую любой из удаленных пунктов.

app.setJumpList(categories) Windows​

Возвращает string

Задает или удаляет настраиваемый Jump List для приложения и возвращает одну из следующих строк:

  • 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 - была сделана попытка добавить ссылку на файл в Jump List для типа файла, который в приложении не зарегистрирован для обработки.
  • customCategoryAccessDeniedError - настраиваемые категории не могут быть добавлены в Jump List из-за ограничений конфиденциальности пользователей или групповой политики.

Если categories - null, то ранее установленный настраиваемый Jump List (если таковой имеется) будет заменён стандартным Jump List для приложения (управляется 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().

[!NOTE] The maximum length of a Jump List item's description property is 260 characters. Beyond this limit, the item will not be added to the Jump List, nor will it be displayed.

Вот очень простой способ, как создать настраиваемый Jump List:

const { app } = require('electron')

app.setJumpList([
{
type: 'custom',
name: 'Recent Projects',
items: [
{ type: 'file', path: 'C:\\Projects\\project1.proj' },
{ type: 'file', path: 'C:\\Projects\\project2.proj' }
]
},
{
// has a name so `type` is assumed to be "custom"
name: 'Tools',
items: [
{
type: 'task',
title: 'Tool A',
program: process.execPath,
args: '--run-tool-a',
iconPath: process.execPath,
iconIndex: 0,
description: 'Runs Tool A'
},
{
type: 'task',
title: 'Tool B',
program: process.execPath,
args: '--run-tool-b',
iconPath: process.execPath,
iconIndex: 0,
description: 'Runs Tool B'
}
]
},
{ type: 'frequent' },
{
// has no name and no type so `type` is assumed to be "tasks"
items: [
{
type: 'task',
title: 'New Project',
program: process.execPath,
args: '--new-project',
description: 'Create a new project.'
},
{ type: 'separator' },
{
type: 'task',
title: 'Recover Project',
program: process.execPath,
args: '--recover-project',
description: 'Recover Project'
}
]
}
])

app.requestSingleInstanceLock([additionalData])​

  • additionalData Record<any, any> (optional) - A JSON object containing additional data to send to the first instance.

Возвращает boolean

Значение, которое возвращает этот метод, указывает, успешно или нет экземпляр Вашего приложения получило блокировку. Если не удалось получить блокировку, можно предположить, что другой экземпляр Вашего приложения уже запущен с блокировкой и немедленно завершается.

I.e. This method returns true if your process is the primary instance of your application and your app should continue loading. Возвращает false, если Ваш процесс должен немедленно завершиться, так как он отправил свои параметры другому экземпляру, который уже приобрел блокировку.

На macOS система автоматически обеспечивает единственный экземпляр, когда пользователи пытаются открыть второй экземпляра Вашего приложения в Finder, для этого будут происходить события open-file и open-url. Так или иначе, когда пользователи запустят Ваше приложение через командную строку, системный механизм единственного экземпляра будет пропущен, и Вы должны использовать этот метод, чтобы обеспечить единственный экземпляр.

[!NOTE] On macOS and Linux, the second instance's command line arguments and additionalData are sent to the primary instance in a single message that is limited to 32 MB. Larger messages are dropped: this method still returns false, but the primary instance does not emit second-instance.

Пример активации окна первичного экземпляра, при запуске второго экземпляра:

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

let myWindow = null

const additionalData = { myKey: 'myValue' }
const gotTheLock = app.requestSingleInstanceLock(additionalData)

if (!gotTheLock) {
app.quit()
} else {
app.on('second-instance', (event, commandLine, workingDirectory, additionalData) => {
// Print out data received from the second instance.
console.log(additionalData)

// Someone tried to run a second instance, we should focus our window.
if (myWindow) {
if (myWindow.isMinimized()) myWindow.restore()
myWindow.focus()
}
})

app.whenReady().then(() => {
myWindow = new BrowserWindow({})
myWindow.loadURL('https://electronjs.org')
})
}

app.hasSingleInstanceLock()​

Возвращает boolean

Этот метод возвращает состояние, является или нет экземпляр Вашего приложения, в данный момент, удерживающим блокировку единственного экземпляра. Вы можете запросить блокировку с помощью app.requestSingleInstanceLock() и освободить с помощью app.releaseSingleInstanceLock()

app.releaseSingleInstanceLock()​

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 - уникально идентифицирует действие. Maps to NSUserActivity.activityType.
  • userInfo any- специфичное, для приложения, состояние для использования другими устройствами.
  • 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 и задает её в качестве текущей активности. The activity is eligible for Handoff to another device afterward.

app.getCurrentActivityType() macOS​

Возвращает string - тип текущей выполняемой активности.

app.invalidateCurrentActivity() macOS​

Invalidates the current Handoff user activity.

app.resignCurrentActivity() macOS​

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

app.updateCurrentActivity(type, userInfo) macOS​

  • type string - уникально идентифицирует действие. Maps to NSUserActivity.activityType.
  • userInfo any- специфичное, для приложения, состояние для использования другими устройствами.

Обновляет текущую активность, если его тип совпадает с type, объединяет записи из userInfo в его текущем словаре userInfo.

app.setAppUserModelId(id) Windows​

  • id string

Changes the Application User Model ID to id.

app.setToastActivatorCLSID(id) Windows​

  • id string

Changes the Toast Activator CLSID to id. If one is not set via this method, it will be randomly generated for the app.

  • The value must be a valid GUID/CLSID in one of the following forms:
    • Canonical brace-wrapped: {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} (preferred)
    • Canonical without braces: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX (braces will be added automatically)
  • Hex digits are case-insensitive.

This method should be called early (before showing notifications) so the value is baked into the registration/shortcut. Supplying an empty string or an unparsable value throws and leaves the existing (or generated) CLSID unchanged. If this method is never called, a random CLSID is generated once per run and exposed via app.toastActivatorCLSID.

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.startAppShimServer([options]) macOS Experimental​

  • options Object (опционально)
    • name string (optional) - A name for this server, which lets several running copies of your app each have their own. It can only contain letters, digits, ., - and _, and must match the ElectronAppShimServerName of the shims that connect to it. По умолчанию - appshim.

Starts accepting connections from app shims. An app-shim-connected event is emitted for each shim that connects.

Throws if the server cannot be started, for example because another copy of your app has already started a server with the same name.

This method can only be called after the app is ready. It is not available in Mac App Store builds.

app.stopAppShimServer() macOS Experimental​

Stops accepting connections from app shims. Shims that have already connected stay connected.

app.importCertificate(options, callback) Linux​

  • options Object
    • certificate string - путь к pkcs12 файлу.
    • password string - парольная фраза для сертификата.
  • callback Function
    • result Integer - результат импорта.

Импорт сертификата в формате pkcs12 из платформы хранилища сертификатов. 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.configureHostResolver(options)​

  • options Object
    • enableBuiltInResolver boolean (optional) - Whether the built-in host resolver is used in preference to getaddrinfo. When enabled, the built-in resolver will attempt to use the system's DNS settings to do DNS lookups itself. Enabled by default on macOS, disabled by default on Windows and Linux.
    • enableHappyEyeballs boolean (optional) - Whether the Happy Eyeballs V3 algorithm should be used in creating network connections. When enabled, hostnames resolving to multiple IP addresses will be attempted in parallel to have a chance at establishing a connection more quickly.
    • secureDnsMode string (optional) - Can be 'off', 'automatic' or 'secure'. Configures the DNS-over-HTTP mode. When 'off', no DoH lookups will be performed. When 'automatic', DoH lookups will be performed first if DoH is available, and insecure DNS lookups will be performed as a fallback. When 'secure', only DoH lookups will be performed. Defaults to 'automatic'.
    • secureDnsServers string[] (optional) - A list of DNS-over-HTTP server templates. See RFC8484 § 3 for details on the template format. Most servers support the POST method; the template for such servers is simply a URI. Note that for some DNS providers, the resolver will automatically upgrade to DoH unless DoH is explicitly disabled, even if there are no DoH servers provided in this list.
    • enableAdditionalDnsQueryTypes boolean (optional) - Controls whether additional DNS query types, e.g. HTTPS (DNS type 65) will be allowed besides the traditional A and AAAA queries when a request is being made via insecure DNS. Has no effect on Secure DNS which always allows additional types. Defaults to true.

Configures host resolution (DNS and DNS-over-HTTPS). By default, the following resolvers will be used, in order:

  1. DNS-over-HTTPS, if the DNS provider supports it, then
  2. the built-in resolver (enabled on macOS only by default), then
  3. the system's resolver (e.g. getaddrinfo).

This can be configured to either restrict usage of non-encrypted DNS (secureDnsMode: "secure"), or disable DNS-over-HTTPS (secureDnsMode: "off"). It is also possible to enable or disable the built-in resolver.

To disable insecure DNS, you can specify a secureDnsMode of "secure". If you do so, you should make sure to provide a list of DNS-over-HTTPS servers to use, in case the user's DNS configuration does not include a provider that supports DoH.

const { app } = require('electron')

app.whenReady().then(() => {
app.configureHostResolver({
secureDnsMode: 'secure',
secureDnsServers: ['https://cloudflare-dns.com/dns-query']
})
})

Этот метод должен вызываться после того, как произошло событие ready.

app.configureWebAuthn(options) macOS​

History
Version(s)Changes
None
API ADDED
  • options Object
    • touchID Object (optional) - Enables the Touch ID / Secure Enclave platform authenticator for Web Authentication requests.
      • keychainAccessGroup string - The keychain access group that WebAuthn credentials will be stored under. This value must also be present in your app's keychain-access-groups code-signing entitlement, and is typically of the form <TEAM_ID>.<BUNDLE_ID>.webauthn.
      • promptReason string (optional) - Customizes the reason text shown in the macOS Touch ID prompt. macOS renders the prompt as "<App Name>" is trying to <promptReason>, so the value should be a lowercase sentence fragment. An optional $1 placeholder is replaced with the relying party ID (e.g. example.com) of the request being authenticated. По умолчанию verify your identity on $1.
    • platformPasskeys boolean (optional) - Enables passkeys via Apple's ASAuthorizationController. When enabled, passkey operations present the system credential provider sheet (iCloud Keychain, 1Password, Bitwarden, etc.) and credentials sync across the user's devices. По умолчанию false. Passing null/undefined (or omitting the key) leaves the previous setting unchanged.

Configures platform authenticators for the Web Authentication API (navigator.credentials.create() / navigator.credentials.get()). Until this is called, PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable() resolves to false and platform-authenticator requests are not serviced.

When touchID is provided, WebAuthn credentials are stored in the macOS keychain and bound to this device's Secure Enclave. Electron automatically generates and persists a per-session metadata secret so that credentials created in one partition are not visible to another.

When platformPasskeys is true, passkey operations use Apple's ASAuthorizationController which delegates to the system's configured Credential Provider Extensions. This enables the same passkey experience as Safari — credentials are available across all devices signed into the same account. Unlike Touch ID credentials, platform passkeys are stored by the credential provider and scoped to the relying party, not to Electron: they are shared across all session partitions and with any other app or browser associated with the same domain. Platform passkeys cannot serve cross-origin (iframe) requests; those requests are left to the other available authenticators (Touch ID supports iframes) and a warning is logged to the DevTools console. The prf and largeBlob WebAuthn extensions are not currently supported by this authenticator — prf inputs are ignored, and a create() call with largeBlob: { support: 'required' } fails.

const { app } = require('electron')

app.configureWebAuthn({
touchID: {
keychainAccessGroup: 'A1B2C3D4E5.com.example.app.webauthn',
promptReason: 'sign in to $1'
},
platformPasskeys: true
})

With the matching entitlements in your app's entitlements.plist:

<key>keychain-access-groups</key>
<array>
<string>A1B2C3D4E5.com.example.app.webauthn</string>
</array>

For platform passkeys, your app needs the Associated Domains entitlement plus an application identifier, both in the same entitlements.plist:

<key>com.apple.developer.associated-domains</key>
<array>
<string>webcredentials:example.com</string>
</array>
<!-- Must match the App ID in your provisioning profile: <TEAM_ID>.<BUNDLE_ID>. -->
<key>com.apple.application-identifier</key>
<string>A1B2C3D4E5.com.example.app</string>

Listing these entitlements is not sufficient on its own — unlike most entitlements, com.apple.developer.associated-domains is provisioning-profile backed. For platform passkeys to work, all of the following must hold:

  • In the Apple Developer portal, your App ID (com.example.app) has the Associated Domains capability enabled, and you have created a provisioning profile for that App ID.
  • That provisioning profile is embedded in the built app bundle at Contents/embedded.provisionprofile. This is what authorizes the associated-domains entitlement at runtime; without an embedded profile macOS silently ignores the webcredentials association and the request fails. (Xcode and @electron/osx-sign embed the profile for you; if you sign manually, copy it into the bundle before signing.)
  • The app is signed (ad-hoc / unsigned builds do not qualify). Both distribution and development signing work — for development builds, use the developer-mode path described below.
  • com.apple.application-identifier matches the profile's App ID. Without it, ASAuthorizationController fails with "The calling process does not have an application identifier" — this is ASAuthorizationError code 1004.
  • The relying party's domain (example.com above) serves a valid apple-app-site-association file over HTTPS at /.well-known/apple-app-site-association containing a webcredentials entry whose apps array lists this app's <TEAM_ID>.<BUNDLE_ID>.
  • The relying party ID of each request matches that associated domain.

If these aren't satisfied, ASAuthorizationController fails before it can present the passkey sheet. The request surfaces to the page as a bare NotAllowedError with no further detail (Electron logs an explanatory message to the DevTools console on this path). Because the association is domain-based, platform passkeys always require a real associated domain and its AASA file — there is no localhost rpId escape hatch as there is in browsers.

To test against your domain with a development-signed build (before shipping a distribution profile), append ?mode=developer to the entitlement value and enable developer mode on the machine with swcutil developer-mode -e true. This makes macOS fetch the AASA directly from the domain — bypassing Apple's CDN cache — and honor the association for a development-signed app. You still need the embedded development provisioning profile described above:

<key>com.apple.developer.associated-domains</key>
<array>
<string>webcredentials:example.com?mode=developer</string>
</array>

[!NOTE] Because the request is fulfilled by the system credential provider (not a browser), the clientDataJSON returned to the page reports origin: "https://<rpId>" — the associated domain — rather than the page's own origin. Relying-party servers that enforce a strict expectedOrigin allowlist must include https://<rpId> for verification to succeed. This also means the relying party cannot distinguish which subdomain of the associated domain initiated the ceremony.

[!NOTE] Touch ID WebAuthn credentials are device-bound and are not synced via iCloud Keychain. They are only available on Macs with a Secure Enclave (Apple silicon, or Intel Macs with a T2 chip).

app.disableHardwareAcceleration()​

Отключает аппаратное ускорение для текущего приложения.

Этот метод может быть вызван только до того, как приложение будет готово.

app.isHardwareAccelerationEnabled()​

Returns boolean - whether hardware acceleration is currently enabled.

[!NOTE] This information is only usable after the gpu-info-update event is emitted.

app.disableDomainBlockingFor3DAPIs()​

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

Этот метод может быть вызван только до того, как приложение будет готово.

app.getAppMetrics()​

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

Примечание

cpu.percentCPUUsage and cpu.idleWakeupsPerSecond are averages over the time since the last call to app.getAppMetrics(), and each call starts a new measurement interval for every process at once. Other code in the main process, including dependencies, shares those intervals. See CPUUsage for more details.

app.getGPUFeatureStatus()​

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

[!NOTE] This information is only usable after the gpu-info-update event is emitted.

app.getGPUInfo(infoType)​

  • infoType string - Может быть basic или complete.

Возвращает 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: Промис выполняется с объектом, содержащий меньшее количество атрибутов, чем когда запрашивается с complete. Вот пример базового ответа:

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

Использование basics должно быть предпочтительным, если требуется только основная информация, такая как vendorId или deviceId.

Promise is rejected if the GPU is completely disabled, i.e. no hardware and software implementations are available.

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 - успешный ли вызов.

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 shows on docks and taskbars that support the LauncherEntry D-Bus API,

[!NOTE] On Linux, the badge is associated with the app's .desktop file, so app.setDesktopName (or the desktopName field in package.json) must match the name of the app's actual .desktop file.

[!NOTE] On macOS, you need to ensure that your application has the permission to display notifications for this method to work.

app.getBadgeCount() macOS​

Возвращает Integer - текущее значение, отображаемое в счетчике-значке.

app.getLoginItemSettings([options]) macOS Windows​

History
Version(s)Changes
None

Removed openAsHidden, wasOpenedAsHidden and restoreState fields from return value.

  • options Object (опционально)
    • type string (optional) macOS - Can be mainAppService, agentService, daemonService, or loginItemService. По умолчанию mainAppService. See app.setLoginItemSettings for more information about each type.
    • serviceName string (optional) macOS - The name of the service. Required if type is non-default.
    • path string (optional) Windows - The executable path to compare against. По умолчанию process.execPath.
    • args string[] (optional) Windows - The command-line arguments to compare against. По умолчанию пустой массив.

Если Вы предоставили параметры path и args в app.setLoginItemSettings, тогда Вам необходимо передать те же аргументы сюда, чтобы openAtLogin установилось корректно.

Возвращает Object:

  • openAtLogin boolean - true если приложение планируется открыть при входе в систему.
  • wasOpenedAtLogin boolean macOS - true if the app was opened at login automatically.
  • status string macOS - can be not-registered, enabled, requires-approval, or not-found.
  • 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 - can be 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​

History
Version(s)Changes
None

Removed openAsHidden option.

[!IMPORTANT] On macOS, your app should be code signed and notarized for login item settings to work reliably. When an app isn't packaged, code signed, and notarized, openAtLogin may silently fail to take effect.

  • Объект settings
    • openAtLogin boolean (optional) - true to open the app at login, false to remove the app as a login item. По умолчанию false.
    • type string (optional) macOS - The type of service to add as a login item. По умолчанию mainAppService.
      • mainAppService - The primary application.
      • agentService - The property list name for a launch agent. The property list name must correspond to a property list in the app’s Contents/Library/LaunchAgents directory.
      • daemonService string (optional) macOS - The property list name for a launch agent. The property list name must correspond to a property list in the app’s Contents/Library/LaunchDaemons directory.
      • loginItemService string (optional) macOS - The property list name for a login item service. The property list name must correspond to a property list in the app’s Contents/Library/LoginItems directory.
    • serviceName string (optional) macOS - The name of the service. Required if type is non-default.
    • path string (optional) Windows - The executable to launch at login. По умолчанию process.execPath.
    • args string[] (optional) Windows - The command-line arguments to pass to the executable. По умолчанию пустой массив. 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().

Устанавливает параметры приложения, при входе в систему.

To work with Electron's autoUpdater on Windows, which uses Squirrel, you'll want to set the launch path to your executable's name but a directory up, which is a stub application automatically generated by Squirrel which will automatically launch the latest version.

const { app } = require('electron')

const path = require('node:path')

const appFolder = path.dirname(process.execPath)
const ourExeName = path.basename(process.execPath)
const stubLauncher = path.resolve(appFolder, '..', ourExeName)

app.setLoginItemSettings({
openAtLogin: true,
path: stubLauncher,
args: [
// You might want to pass a parameter here indicating that this
// app was launched via login, but you don't have to
]
})

For more information about setting different services as login items on macOS, see SMAppService.

app.isAccessibilitySupportEnabled() macOS Windows​

Returns boolean - true if Chromium's accessibility support is enabled, false otherwise. Этот API будет возвращать true, если обнаружено использование вспомогательных технологий, таких как средства чтения с экрана. Смотрите https://www.chromium.org/developers/design-documents/accessibility для подробностей.

app.setAccessibilitySupportEnabled(enabled) macOS Windows​

Manually enables Chromium's accessibility support, allowing to expose accessibility switch to users in application settings. See Chromium's accessibility docs for more details. Отключено по умолчанию.

Этот метод должен вызываться после того, как произошло событие ready.

[!NOTE] Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default. Calling this method will enable the following accessibility support features: nativeAPIs, webContents, inlineTextBoxes, and extendedProperties.

app.getAccessibilitySupportFeatures() macOS Windows​

Returns string[] - Array of strings naming currently enabled accessibility support components. Возможные значения:

  • nativeAPIs - Native OS accessibility APIs integration enabled.
  • webContents - Web contents accessibility tree exposure enabled.
  • inlineTextBoxes - Inline text boxes (character bounding boxes) enabled.
  • extendedProperties - Extended accessibility properties enabled.
  • screenReader - Screen reader specific mode enabled.
  • html - HTML accessibility tree construction enabled.
  • labelImages - Accessibility support for automatic image annotations.
  • pdfPrinting - Accessibility support for PDF printing enabled.

Примечания:

  • The array may be empty if no accessibility modes are active.
  • Use app.isAccessibilitySupportEnabled() for the legacy boolean check; prefer this method for granular diagnostics or telemetry.

Пример:

const { app } = require('electron')

app.whenReady().then(() => {
if (app.getAccessibilitySupportFeatures().includes('screenReader')) {
// Change some app UI to better work with Screen Readers.
}
})

app.setAccessibilitySupportFeatures(features) macOS Windows​

  • features string[] - An array of the accessibility features to enable.

Возможные значения:

  • nativeAPIs - Native OS accessibility APIs integration enabled.
  • webContents - Web contents accessibility tree exposure enabled.
  • inlineTextBoxes - Inline text boxes (character bounding boxes) enabled.
  • extendedProperties - Extended accessibility properties enabled.
  • screenReader - Screen reader specific mode enabled.
  • html - HTML accessibility tree construction enabled.
  • labelImages - Accessibility support for automatic image annotations.
  • pdfPrinting - Accessibility support for PDF printing enabled.

To disable all supported features, pass an empty array [].

Пример:

const { app } = require('electron')

app.whenReady().then(() => {
// Enable a subset of features:
app.setAccessibilitySupportFeatures(['screenReader', 'pdfPrinting', 'webContents'])

// Other logic

// Some time later, disable all features:
app.setAccessibilitySupportFeatures([])
})

app.showAboutPanel()​

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

app.setAboutPanelOptions(options)​

  • options Object
    • applicationName string (опиционально) - имя приложения.
    • applicationVersion string (опиционально) - версия приложения.
    • copyright string (опционально) - информация авторских прав.
    • version string (опционально) macOS - номер версии сборки приложения.
    • credits string (optional) macOS Windows - Credit information.
    • authors string[] (опционально) Linux - список авторов приложения.
    • website string (опционально) Linux - веб-сайт приложения.
    • 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. On Windows, a 48x48 PNG will result in the best visual quality.

Устанавливает опции панели о приложении. This will override the values defined in the app's .plist file on macOS. See the Apple docs for more details. На 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()​

Возвращает boolean - позволяет или нет текущая версия ОС выбирать нативные эмодзи.

app.showEmojiPanel() macOS Windows​

Показывает нативный выбор эмодзи.

app.startAccessingSecurityScopedResource(bookmarkData) MAS​

  • bookmarkData string - Закодированные base64 данные закладки области безопасности, возвращаемые dialog.showOpenDialog или dialog.showSaveDialog.

Возвращает Function. Эта функция должна быть вызвана после того как вы 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.

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

const fs = require('node:fs')

let filepath
let bookmark

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

// ... restart app ...

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

Начать доступ в области безопасности ресурса. 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.enableSandbox()​

Включает полноценный режим песочницы в приложении. This means that all renderers will be launched sandboxed, regardless of the value of the sandbox flag in WebPreferences.

Этот метод может быть вызван только до того, как приложение будет готово.

app.isInApplicationsFolder() macOS​

Возвращает boolean - выполняется ли приложение в данный момент из системной папки Приложения. Используйте в сочетании с app.moveToApplicationsFolder()

app.moveToApplicationsFolder([options]) macOS​

  • options Object (опционально)
    • conflictHandler Function<boolean> (опционально) - обработчик потенциальных конфликтов при неудачных попытках.
      • conflictType string - Тип конфликта перемещения, с которым столкнулся обработчик; может быть exists или existsAndRunning, где exists означает, что приложение с тем же именем присутствует в каталоге приложений, а existsAndRunning означает, что он существует и работает в данный момент.

Возвращает boolean - если перемещение было успешным. Обратите внимание, что если перемещение выполнено успешно, ваше приложение закроется и перезапустится.

По умолчанию диалоговое окно подтверждения не отображается. Если нужно подтверждение операции пользователем, используйте dialog API.

ПРИМЕЧАНИЕ: Этот метод выдает ошибки, если что-то, кроме пользователя, вызывает переход к неудачи. Например, если пользователь отменяет диалоговое окно авторизации, этот метод возвращает false. Если нам не удастся выполнить копирование, этот метод вызовет ошибку. Сообщение об ошибке должно быть информативным и сообщать вам именно то, что пошло не так.

По умолчанию, если приложение с тем же именем, что и перемещаемое, существует в каталоге Applications и not запущено, существующее приложение будет удалено, а активное приложение перемещено на свое место. If it is running, the preexisting running app will assume focus and the previously active app will quit itself. Это поведение можно изменить, предоставив необязательный обработчик конфликтов, где логическое значение, возвращаемое обработчиком, определяет, будет ли конфликт перемещения разрешен с поведением по умолчанию. то есть возврат false гарантирует, что дальнейшие действия не будут приняты, возврат true приведет к поведению по умолчанию и продолжению метода.

Например:

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

app.moveToApplicationsFolder({
conflictHandler: (conflictType) => {
if (conflictType === 'exists') {
return (
dialog.showMessageBoxSync({
type: 'question',
buttons: ['Halt Move', 'Continue Move'],
defaultId: 0,
message: 'An app of this name already exists'
}) === 1
)
}
}
})

Будет означать, что если приложение уже существует в каталоге пользователя, если пользователь выберет 'Continue Move', то эта функция будет продолжена с поведением по умолчанию, и существующее приложение будет удалено и активное приложение будет перемещено на место.

app.isSecureKeyboardEntryEnabled() macOS​

Возвращает boolean - если включен Secure Keyboard Entry.

По умолчанию этот API вернет false.

app.setSecureKeyboardEntryEnabled(enabled) macOS​

  • enabled boolean - Включить или отключить Secure Keyboard Entry

Установка Secure Keyboard Entry включена в вашем приложении.

Используя этот API, можно предотвратить перехват важной информации, такой как пароль и другую конфиденциальную информацию, другими процессами.

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.setProxy(config)​

Возвращает Promise<void> - Разрешение после завершения процесса настройки прокси.

Sets the proxy settings for networks requests made without an associated Session. Currently this will affect requests made with Net in the utility process and internal requests made by the runtime (ex: geolocation queries).

This method can only be called after app is ready.

app.resolveProxy(url)​

  • url URL

Returns Promise<string> - Resolves with the proxy information for url that will be used when attempting to make requests using Net in the utility process.

app.setClientCertRequestPasswordHandler(handler) Linux​

  • handler Function<Promise<string>>

    • Объект clientCertRequestParams
      • hostname string - the hostname of the site requiring a client certificate
      • tokenName string - the token (or slot) name of the cryptographic device
      • isRetry boolean - whether there have been previous failed attempts at prompting the password

    Returns Promise<string> - Resolves with the password

The handler is called when a password is needed to unlock a client certificate for hostname.

const { app } = require('electron')

async function passwordPromptUI(text) {
return new Promise((resolve, reject) => {
// display UI to prompt user for password
// ...
// ...
resolve('the password')
})
}

app.setClientCertRequestPasswordHandler(async ({ hostname, tokenName, isRetry }) => {
const text = `Please sign in to ${tokenName} to authenticate to ${hostname} with your certificate`
const password = await passwordPromptUI(text)
return password
})

Свойства​

app.accessibilitySupportEnabled macOS Windows​

A boolean property that's true if Chromium's accessibility support is enabled, false otherwise. Это свойство будет true, если использование вспомогательных технологий, таких как средства чтения с экрана, были обнаружены. Setting this property to true manually enables Chromium's accessibility support, allowing developers to expose accessibility switch to users in application settings.

See Chromium's accessibility docs for more details. Отключено по умолчанию.

Этот метод должен вызываться после того, как произошло событие ready.

[!NOTE] Rendering accessibility tree can significantly affect the performance of your app. It should not be enabled by default.

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​

Свойство Integer, которое возвращает количество значков для текущего приложения. Установка счетчика на 0 скроет значок. Setting this with any nonzero integer shows the count on the Dock icon on macOS, or on the launcher on Linux.

[!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 property (Dock on macOS, undefined on all other platforms) that allows you to perform actions on your app icon in the user's dock.

app.isPackaged Readonly​

boolean свойство, которое возвращает true, если приложение упаковано, иначе false. Для многих приложений это свойство может использоваться для отличия среды разработки и продакшна.

app.toastActivatorCLSID Windows Readonly​

A string property that returns the app's Toast Activator CLSID.

app.name​

Свойство string, указывающее имя текущего приложения, которое является именем в файле package.json.

Обычно поле name в package.json является коротким именем, написанном в нижнем регистре, согласно спецификации модулей npm. Обычно Вы должны также указать поле productName, которое пишется заглавными буквами - имя вашего приложения, и которое будет предпочтительнее name для Electron.

On Windows, the application's name must not contain reserved filename characters, because it is used to construct the default userData directory.

app.userAgentFallback​

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

Это агент пользователя, который будет использоваться, если ни один агент пользователя не установлен на уровнях webContents или session. Это полезно для того, чтобы все ваше приложение имело один и тот же пользовательский агент. Установите пользовательское значение как можно раньше в инициализации Ваших приложений, чтобы убедиться, что используется переопределенное значение.

app.runningUnderARM64Translation Readonly macOS Windows​

A boolean which when true indicates that the app is currently running under an ARM64 translator (like the macOS Rosetta Translator Environment or Windows WOW).

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