systemPreferences

Obtenha preferências do sistema.

Process: Main, Utility

const { systemPreferences } = require('electron')

console.log(systemPreferences.getEffectiveAppearance())

Eventos

O objeto systemPreferences emite os seguintes eventos:

Event: 'accent-color-changed' Windows Linux

Retorna:

• event Event
• newColor string - The new RGBA color the user assigned to be their system accent color.

Event: 'color-changed' Windows

Retorna:

• event Event

Métodos

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 string | null
• callback Function
  • event string
  • userInfo Record<string, unknown>
  • object string

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

If event is null, the NSDistributedNotificationCenter doesn’t use it as criteria for delivery to the observer. See docs for more information.

systemPreferences.subscribeLocalNotification(event, callback) macOS

• event string | null
• callback Function
  • event string
  • userInfo Record<string, unknown>
  • object string

Returns number - The ID of this subscription

Same as subscribeNotification, but uses NSNotificationCenter for local defaults. This is necessary for events such as NSUserDefaultsDidChangeNotification.

If event is null, the NSNotificationCenter doesn’t use it as criteria for delivery to the observer. See docs for more information.

systemPreferences.subscribeWorkspaceNotification(event, callback) macOS

• event string | null
• callback Function
  • event string
  • userInfo Record<string, unknown>
  • object string

Returns number - The ID of this subscription

Same as subscribeNotification, but uses NSWorkspace.sharedWorkspace.notificationCenter. This is necessary for events such as NSWorkspaceDidActivateApplicationNotification.

If event is null, the NSWorkspaceNotificationCenter doesn’t use it as criteria for delivery to the observer. See docs for more information.

systemPreferences.unsubscribeNotification(id) macOS

• id Inteiro

Removes the subscriber with id.

systemPreferences.unsubscribeLocalNotification(id) macOS

• id Inteiro

Same as unsubscribeNotification, but removes the subscriber from NSNotificationCenter.

systemPreferences.unsubscribeWorkspaceNotification(id) macOS

• id Inteiro

Same as unsubscribeNotification, but removes the subscriber from NSWorkspace.sharedWorkspace.notificationCenter.

systemPreferences.registerDefaults(defaults) macOS

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

Add the specified defaults to your application's 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.

Returns UserDefaultTypes[Type] - The value of key in NSUserDefaults.

Some popular key and types are:

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

Set the value of key in NSUserDefaults.

Note that type should match actual type of value. An exception is thrown if they don't.

Some popular key and types are:

• ApplePressAndHoldEnabled: boolean

systemPreferences.removeUserDefault(key) macOS

• key string

Removes the key in NSUserDefaults. This can be used to restore the default or global value of a key previously set with setUserDefault.

systemPreferences.getAccentColor()

Returns string - The users current system wide accent color preference in RGBA hexadecimal form.

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"

This API is only available on macOS 10.14 Mojave or newer.

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). See the Windows docs and the macOS docs for more details.

The following colors are only available on macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, and unemphasized-selected-text.

systemPreferences.getSystemColor(color) macOS

• color string - One of the following values:
  • azul
  • brown
  • cinza
  • verde
  • laranja
  • rosa
  • roxo
  • vermelho
  • yellow

Returns string - The standard system color formatted as #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)