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

systemPreferences

Получение системных параметров.

Process: Main, Utility

const { systemPreferences } = require('electron')
console.log(systemPreferences.isAeroGlassEnabled())

События​

Объект systemPreferences включает следующие события:

Событие: 'accent-color-changed' Windows​

Возвращает:

  • Событие типа event
  • newColor строка - новый цвет RGBA, назначенный пользователем в качестве акцентного цвета.

Событие: 'color-changed' Windows​

Возвращает:

  • Событие типа event

Методы​

systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS​

Returns boolean - Whether the Swipe between pages setting is on.

systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOS​

  • event string
  • userInfo Record<string, any>
  • deliverImmediately boolean (optional) - true to post notifications immediately even when the subscribing app is inactive.

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.postLocalNotification(event, userInfo) macOS​

  • event string
  • userInfo Record<string, any>

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.postWorkspaceNotification(event, userInfo) macOS​

  • event string
  • userInfo Record<string, any>

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.subscribeNotification(event, callback) macOS​

  • event Menu | null
  • callback Function
    • event string
    • userInfo Record<string, unknown>
    • строка object

Returns number - The ID of this subscription

Subscribes to native notifications of macOS, callback will be called with callback(event, userInfo) when the corresponding event happens. The userInfo is an Object that contains the user information dictionary sent along with the notification. The object is the sender of the notification, and only supports NSString values for now.

The id of the subscriber is returned, which can be used to unsubscribe the event.

Under the hood this API subscribes to NSDistributedNotificationCenter, example values of event are:

  • AppleInterfaceThemeChangedNotification
  • AppleAquaColorVariantChanged
  • AppleColorPreferencesChangedNotification
  • AppleShowScrollBarsSettingChanged

Если event аннулирован, NSDistributedNotificationCenter не использует его в качестве критериев для доставки наблюдателю. Смотрите документацию для получения дополнительной информации.

systemPreferences.subscribeLocalNotification(event, callback) macOS​

  • event Menu | null
  • callback Function
    • event string
    • userInfo Record<string, unknown>
    • строка object

Returns number - The ID of this subscription

То же, что и subscribeNotification, но использует NSNotificationCenter для локальных значений по умолчанию. Это необходимо для таких событий, как NSUserDefaultsDidChangeNotification.

Если event аннулирован, NSNotificationCenter не использует его в качестве критериев для доставки наблюдателю. Смотрите документацию для получения дополнительной информации.

systemPreferences.subscribeWorkspaceNotification(event, callback) macOS​

  • event Menu | null
  • callback Function
    • event string
    • userInfo Record<string, unknown>
    • строка object

Returns number - The ID of this subscription

То же, что и subscribeNotification, но использует NSWorkspace.sharedWorkspace.notificationCenter. Это необходимо для таких событий, как NSWorkspaceDidActivateApplicationNotification.

Если event аннулирован, NSWorkspaceNotificationCenter не использует его в качестве критериев для доставки наблюдателю. Смотрите документацию для получения дополнительной информации.

systemPreferences.unsubscribeNotification(id) macOS​

  • id Integer

Удаляет подписчика с id.

systemPreferences.unsubscribeLocalNotification(id) macOS​

  • id Integer

Так же, как и unsubscribeNotification, но удаляет подписчика из NSNotificationCenter.

systemPreferences.unsubscribeWorkspaceNotification(id) macOS​

  • id Integer

Так же, как и unsubscribeNotification, но удаляет подписчика из NSWorkspace.sharedWorkspace.notificationCenter.

systemPreferences.registerDefaults(defaults) macOS​

  • defaults Record<string, string | boolean | number> - a dictionary of (key: value) user defaults

Добавьте указанные значения по умолчанию в NSUserDefaults вашего приложения.

systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOS​

  • key string
  • type Type - Can be string, boolean, integer, float, double, url, array or dictionary.

Возвращает UserDefaultTypes[Type] - Значение key в NSUserDefaults.

Самые популярные key и type:

  • AppleInterfaceStyle: string
  • AppleAquaColorVariant: integer
  • AppleHighlightColor: string
  • AppleShowScrollBars: string
  • NSNavRecentPlaces: array
  • NSPreferredWebServices: dictionary
  • NSUserDictionaryReplacementItems: array

systemPreferences.setUserDefault<Type extends keyof UserDefaultTypes>(key, type, value) macOS​

  • key string
  • type Type - Can be string, boolean, integer, float, double, url, array or dictionary.
  • value UserDefaultTypes[Type]

Устанавливает значение key в NSUserDefaults.

Обратите внимание, что type должны соответствовать фактическому типу value. Исключение бросается, если оно не повторяется.

Самые популярные key и type:

  • ApplePressAndHoldEnabled: boolean

systemPreferences.removeUserDefault(key) macOS​

  • key string

Устанавливает значение key в NSUserDefaults. Это может быть использовано для восстановления стандартного или глобального значения key , ранее установленного на setUserDefault.

systemPreferences.isAeroGlassEnabled() Windows​

Возвращает boolean - true , если включена DWM композиция (Aero Glass), и false в противном случае.

Пример его использования для определения того, следует ли создавать прозрачное окно или (прозрачные окна не будут работать корректно, если DWM композиции отключены):

const { BrowserWindow, systemPreferences } = require('electron')
const browserOptions = { width: 1000, height: 800 }

// Make the window transparent only if the platform supports it.
if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
  browserOptions.transparent = true
  browserOptions.frame = false
}

// Create the window.
const win = new BrowserWindow(browserOptions)

// Navigate.
if (browserOptions.transparent) {
  win.loadFile('index.html')
} else {
  // No transparency, so we load a fallback that uses basic styles.
  win.loadFile('fallback.html')
}

systemPreferences.getAccentColor() Windows macOS​

Возвращает string - текущую системную цветовую настройку пользователя в RGBA шестнадцатеричной форме.

const color = systemPreferences.getAccentColor() // `"aabbccdd"` 
const red = color.substr(0, 2) // "aa" 
const green = color.substr(2, 2) // "bb" 
const blue = color.substr(4, 2) // "cc" 
const alpha = color.substr(6, 2) // "dd"

Этот API доступен только в macOS 10.14 Mojave или более поздней версии.

systemPreferences.getColor(color) Windows macOS​

  • color string - One of the following values:
    • On Windows:
      • 3d-dark-shadow - Dark shadow for three-dimensional display elements.
      • 3d-face - Face color for three-dimensional display elements and for dialog box backgrounds.
      • 3d-highlight - Highlight color for three-dimensional display elements.
      • 3d-light - Light color for three-dimensional display elements.
      • 3d-shadow - Shadow color for three-dimensional display elements.
      • active-border - Active window border.
      • active-caption - Active window title bar. Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.
      • active-caption-gradient - Right side color in the color gradient of an active window's title bar.
      • app-workspace - Background color of multiple document interface (MDI) applications.
      • button-text - Text on push buttons.
      • caption-text - Text in caption, size box, and scroll bar arrow box.
      • desktop - Desktop background color.
      • disabled-text - Grayed (disabled) text.
      • highlight - Item(s) selected in a control.
      • highlight-text - Text of item(s) selected in a control.
      • hotlight - Color for a hyperlink or hot-tracked item.
      • inactive-border - Inactive window border.
      • inactive-caption - Inactive window caption. Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.
      • inactive-caption-gradient - Right side color in the color gradient of an inactive window's title bar.
      • inactive-caption-text - Color of text in an inactive caption.
      • info-background - Background color for tooltip controls.
      • info-text - Text color for tooltip controls.
      • menu - Menu background.
      • menu-highlight - The color used to highlight menu items when the menu appears as a flat menu.
      • menubar - The background color for the menu bar when menus appear as flat menus.
      • menu-text - Text in menus.
      • scrollbar - Scroll bar gray area.
      • window - Window background.
      • window-frame - Window frame.
      • window-text - Text in windows.
    • On macOS
      • control-background - The background of a large interface element, such as a browser or table.
      • control - The surface of a control.
      • control-text -The text of a control that isn’t disabled.
      • disabled-control-text - The text of a control that’s disabled.
      • find-highlight - The color of a find indicator.
      • grid - The gridlines of an interface element such as a table.
      • header-text - The text of a header cell in a table.
      • highlight - The virtual light source onscreen.
      • keyboard-focus-indicator - The ring that appears around the currently focused control when using the keyboard for interface navigation.
      • label - The text of a label containing primary content.
      • link - A link to other content.
      • placeholder-text - A placeholder string in a control or text view.
      • quaternary-label - The text of a label of lesser importance than a tertiary label such as watermark text.
      • scrubber-textured-background - The background of a scrubber in the Touch Bar.
      • secondary-label - The text of a label of lesser importance than a normal label such as a label used to represent a subheading or additional information.
      • selected-content-background - The background for selected content in a key window or view.
      • selected-control - The surface of a selected control.
      • selected-control-text - The text of a selected control.
      • selected-menu-item-text - The text of a selected menu.
      • selected-text-background - The background of selected text.
      • selected-text - Selected text.
      • separator - A separator between different sections of content.
      • shadow - The virtual shadow cast by a raised object onscreen.
      • tertiary-label - The text of a label of lesser importance than a secondary label such as a label used to represent disabled text.
      • text-background - Text background.
      • text - The text in a document.
      • under-page-background - The background behind a document's content.
      • unemphasized-selected-content-background - The selected content in a non-key window or view.
      • unemphasized-selected-text-background - A background for selected text in a non-key window or view.
      • unemphasized-selected-text - Selected text in a non-key window or view.
      • window-background - The background of a window.
      • window-frame-text - The text in the window's titlebar area.

Returns string - The system color setting in RGBA hexadecimal form (#RRGGBBAA). Смотрите документы Windows и документы macOS для получения более подробной информации.

Следующие цвета доступны только в macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-backgroundи unemphasized-selected-text.

systemPreferences.getSystemColor(color) macOS​

  • color string - One of the following values:
    • blue
    • brown
    • gray
    • green
    • orange
    • pink
    • purple
    • red
    • yellow

Возвращает string — стандартный системный цвет в формате #RRGGBBAA.

Returns one of several standard system colors that automatically adapt to vibrancy and changes in accessibility settings like 'Increase contrast' and 'Reduce transparency'. See Apple Documentation for more details.

systemPreferences.getEffectiveAppearance() macOS​

Returns string - Can be dark, light or unknown.

Gets the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance

systemPreferences.canPromptTouchID() macOS​

Returns boolean - whether or not this device has the ability to use Touch ID.

systemPreferences.promptTouchID(reason) macOS​

  • reason string - The reason you are asking for Touch ID authentication

Returns Promise<void> - resolves if the user has successfully authenticated with Touch ID.

const { systemPreferences } = require('electron')

systemPreferences.promptTouchID('To get consent for a Security-Gated Thing').then(success => {
  console.log('You have successfully authenticated with Touch ID!')
}).catch(err => {
  console.log(err)
})

This API itself will not protect your user data; rather, it is a mechanism to allow you to do so. Native apps will need to set Access Control Constants like kSecAccessControlUserPresence on their keychain entry so that reading it would auto-prompt for Touch ID biometric consent. This could be done with node-keytar, such that one would store an encryption key with node-keytar and only fetch it if promptTouchID() resolves.

systemPreferences.isTrustedAccessibilityClient(prompt) macOS​

  • prompt boolean - whether or not the user will be informed via prompt if the current process is untrusted.

Returns boolean - true if the current process is a trusted accessibility client and false if it is not.

systemPreferences.getMediaAccessStatus(mediaType) Windows macOS​

  • mediaType string - может быть завершено microphone, отменено camera или прервано screen.

Returns string - Can be not-determined, granted, denied, restricted or unknown.

This user consent was not required on macOS 10.13 High Sierra so this method will always return granted. macOS 10.14 Mojave or higher requires consent for microphone and camera access. macOS 10.15 Catalina or higher requires consent for screen access.

Windows 10 has a global setting controlling microphone and camera access for all win32 applications. It will always return granted for screen and for all media types on older versions of Windows.

systemPreferences.askForMediaAccess(mediaType) macOS​

  • mediaType string - the type of media being requested; can be microphone, camera.

Returns Promise<boolean> - A promise that resolves with true if consent was granted and false if it was denied. If an invalid mediaType is passed, the promise will be rejected. If an access request was denied and later is changed through the System Preferences pane, a restart of the app will be required for the new permissions to take effect. If access has already been requested and denied, it must be changed through the preference pane; an alert will not pop up and the promise will resolve with the existing access status.

Important: In order to properly leverage this API, you must set the NSMicrophoneUsageDescription and NSCameraUsageDescription strings in your app's Info.plist file. The values for these keys will be used to populate the permission dialogs so that the user will be properly informed as to the purpose of the permission request. See Electron Application Distribution for more information about how to set these in the context of Electron.

This user consent was not required until macOS 10.14 Mojave, so this method will always return true if your system is running 10.13 High Sierra.

systemPreferences.getAnimationSettings()​

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

  • shouldRenderRichAnimation boolean - Returns true if rich animations should be rendered. Looks at session type (e.g. remote desktop) and accessibility settings to give guidance for heavy animations.
  • scrollAnimationsEnabledBySystem boolean - Determines on a per-platform basis whether scroll animations (e.g. produced by home/end key) should be enabled.
  • prefersReducedMotion boolean - Determines whether the user desires reduced motion based on platform APIs.

Returns an object with system animation settings.

Свойства​

systemPreferences.accessibilityDisplayShouldReduceTransparency macOS Deprecated​

A boolean property which determines whether the app avoids using semitransparent backgrounds. This maps to NSWorkspace.accessibilityDisplayShouldReduceTransparency

Deprecated: Use the new nativeTheme.prefersReducedTransparency API.

systemPreferences.effectiveAppearance macOS Readonly​

Свойство string может быть dark, light или unknown.

Returns the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance