systemPreferences

systemPreferences

获取system preferences.

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

事件

systemPreferences 对象触发以下事件:

Event: ‘accent-color-changed’ Windows

event Event
newColor String - 用户指定的新 RGBA 颜色作为系统偏好颜色.

Event: ‘color-changed’ Windows

event Event

Event: ‘inverted-color-scheme-changed’ Windows Deprecated

event Event
invertedColorScheme Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is being used, false otherwise.

Deprecated: Should use the new updated event on the nativeTheme module.

Event: ‘high-contrast-color-scheme-changed’ Windows Deprecated

event Event
highContrastColorScheme Boolean - true if a high contrast theme is being used, false otherwise.

Deprecated: Should use the new updated event on the nativeTheme module.

Note: On macOS 10.15 Catalina in order for this API to return the correct value when in the “automatic” dark mode setting you must either have NSRequiresAquaSystemAppearance=false in your Info.plist or be on Electron >=7.0.0. See the dark mode guide for more information.

Deprecated: Should use the new nativeTheme.shouldUseDarkColors API.

`systemPreferences.isSwipeTrackingFromScrollEventsEnabled()` macOS

返回值 Boolean - 是否在页面设置之间进行滑动。

`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
callback Function
- event String
- userInfo Record<String, unknown>
- object String

返回 Number - 该订阅的 ID

订阅macOS的原生通知，当通信的 event</ 0>发生时，将调用 <code>callback(event, userInfo) 。 userInfo是一个Object，它包含随通知一起发送的用户信息字典。 The object is the sender of the notification, and only supports NSString values for now.

返回订阅的 id, 可用于取消该订阅的 event.

在这个API下订阅NSDistributedNotificationCenter， event 的示例值为：

AppleInterfaceThemeChangedNotification
AppleAquaColorVariantChanged
AppleColorPreferencesChangedNotification
AppleShowScrollBarsSettingChanged

`systemPreferences.subscribeLocalNotification(event, callback)` macOS

event String
callback Function
- event String
- userInfo Record<String, unknown>
- object String

返回 Number - 该订阅的 ID

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

`systemPreferences.subscribeWorkspaceNotification(event, callback)` macOS

event String
callback Function
- event String
- userInfo Record<String, unknown>
- object String

与 subscribeNotification一样, 但使用NSWorkspace.sharedWorkspace.notificationCenter。这对事件 NSWorkspaceDidActivateApplicationNotification 是必需的。

`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(key, type)` macOS

key String
type String - 可以为 string, boolean, integer, float, double, url, array 或 dictionary.

返回 any - NSUserDefaults 中 key 的值.

常用的 key 和 type 的类型为:

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

`systemPreferences.setUserDefault(key, type, value)` macOS

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

设置 NSUserDefaults 中 key 的值.

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

常用的 key 和 type 的类型为:

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.isAeroGlassEnabled()` Windows

返回 Boolean - true 如果启用了 DWM composition (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.loadURL(`file://${__dirname}/index.html`)
} else {
  // No transparency, so we load a fallback that uses basic styles.
  win.loadURL(`file://${__dirname}/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"

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 - 三维显示元素的暗阴影。
  - 3d-face - 面向三维显示元素和对话框背景的颜色。
  - 3d-highlight - 三维显示元素的高亮色.
  - 3d-light - 三维显示元素的亮色.
  - 3d-shadow - 三维显示元素的阴影颜色.
  - active-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 - 活动窗口标题栏的颜色渐变中的右侧颜色。
  - app-workspace - 多文档界面 (MDI) 应用程序的背景颜色。
  - button-text - 按钮上的文本。
  - caption-text - 标题，大小框和滚动条箭头框中的文本。
  - desktop - 桌面的背景色。
  - disabled-text - 灰色 (禁用的) 文字.
  - highlight - 在控件中选择的项目。
  - highlight-text - 在控件中选择的项目文本。
  - hotlight - 超链接或热追踪项目的颜色。
  - inactive-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 - 非活动窗口标题栏的颜色渐变中的右侧颜色。
  - inactive-caption-text - 非活动标题中的文字颜色。
  - info-background - 工具提示控件的背景颜色。
  - info-text - 工具提示控件的文本颜色。
  - menu - 菜单的背景色.
  - menu-highlight - 当菜单显示为平面菜单时用于突出显示菜单项的颜色。
  - menubar - 菜单显示为平面菜单时菜单栏的背景颜色。
  - menu-text - 菜单的文字.
  - scrollbar - 滚动条的灰色区域.
  - window - 窗口的背景色.
  - window-frame - 窗口框.
  - window-text - 窗口的文字。
- On macOS
  - alternate-selected-control-text - The text on a selected surface in a list or table. deprecated
  - 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.

返回 String -系统颜色设置为RGB十六进制格式 (#ABCDEF). See the Windows docs.aspx) 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:
- blue
- brown
- gray
- green
- orange
- pink
- purple
- red
- 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.isInvertedColorScheme()` Windows Deprecated

Returns Boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is active, false otherwise.

Deprecated: Should use the new nativeTheme.shouldUseInvertedColorScheme API.

`systemPreferences.isHighContrastColorScheme()` macOS Windows Deprecated

Returns Boolean - true if a high contrast theme is active, false otherwise.

Deprecated: Should use the new nativeTheme.shouldUseHighContrastColors API.

`systemPreferences.getEffectiveAppearance()` macOS

返回 String - 其值可能是 dark、light 或 unknown.

获取当前应用到你的程序上的 macOS 设置项，会映射到 NSApplication.effectiveAppearance

`systemPreferences.getAppLevelAppearance()` macOS Deprecated

返回 String | null - 其值可能为 dark、light 或 unknown。

Gets the macOS appearance setting that you have declared you want for your application, maps to NSApplication.appearance. 您可以使用 setAppLevelAppearance API 来设置此值。

`systemPreferences.setAppLevelAppearance(appearance)` macOS Deprecated

appearance String | null - 可以是 dark 或 light

设定您的应用程序的外观设置，这应该覆盖系统默认值以及覆盖 getEffectiveAppearance 的值。

`systemPreferences.canPromptTouchID()` macOS

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

NOTE: This API will return false on macOS systems older than Sierra 10.12.2.

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

NOTE: This API will return a rejected Promise on macOS systems older than Sierra 10.12.2.

`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 - Can be microphone, camera or screen.

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

This user consent was not required on macOS 10.13 High Sierra or lower 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 or lower.

`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.appLevelAppearance` macOS

A String property that can be dark, light or unknown. It determines the macOS appearance setting for your application. This maps to values in: NSApplication.appearance. Setting this will override the system default as well as the value of getEffectiveAppearance.

Possible values that can be set are dark and light, and possible return values are dark, light, and unknown.

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

`systemPreferences.effectiveAppearance` macOS Readonly

A String property that can be dark, light or unknown.

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