Skip to main content

systemPreferences

获取系统偏好设置。

进程：主进程，工具进程

🌐 Process: Main, Utility

const { systemPreferences } = require('electron')

console.log(systemPreferences.getEffectiveAppearance())

事件​

🌐 Events

systemPreferences 对象会触发以下事件：

🌐 The systemPreferences object emits the following events:

Event: 'accent-color-changed' Windows Linux​

返回：

🌐 Returns:

  • event 活动
  • newColor 字符串 - 用户分配作为系统强调色的新 RGBA 颜色。

Event: 'color-changed' Windows​

返回：

🌐 Returns:

  • event 活动

方法​

🌐 Methods

systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS​

返回 boolean - 页面之间滑动设置是否开启。

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

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

  • event 字符串
  • 'userInfo'唱片<string, any>
  • deliverImmediately 布尔值（可选）- true 即使订阅应用处于不活跃状态，也要立即发送通知。

将 event 作为 macOS 的本地通知。userInfo 是一个对象，包含随通知发送的用户信息字典。

🌐 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 字符串
  • 'userInfo'唱片<string, any>

将 event 作为 macOS 的本地通知。userInfo 是一个对象，包含随通知发送的用户信息字典。

🌐 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 字符串
  • 'userInfo'唱片<string, any>

将 event 作为 macOS 的本地通知。userInfo 是一个对象，包含随通知发送的用户信息字典。

🌐 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 字符串 | 空
  • callback 函数
    • event 字符串
    • 'userInfo'唱片<string, unknown>
    • object 字符串

返回 number - 此订阅的 ID

🌐 Returns number - The ID of this subscription

订阅 macOS 的本地通知，当相应的 event 发生时，callback 将会被调用，并传入 callback(event, userInfo)。 userInfo 是一个包含随通知一起发送的用户信息字典的对象。object 是通知的发送者，目前仅支持 NSString 值。

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

返回订阅者的 id，可用于取消订阅 event。

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

在底层，这个 API 订阅了 NSDistributedNotificationCenter，event 的示例值如下：

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

  • AppleInterfaceThemeChangedNotification
  • AppleAquaColorVariantChanged
  • AppleColorPreferencesChangedNotification
  • AppleShowScrollBarsSettingChanged

如果 event 为 null，NSDistributedNotificationCenter 不会将其作为向观察者传递的条件。有关更多信息，请参见 文档。

🌐 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 字符串 | 空
  • callback 函数
    • event 字符串
    • 'userInfo'唱片<string, unknown>
    • object 字符串

返回 number - 此订阅的 ID

🌐 Returns number - The ID of this subscription

与 subscribeNotification 相同，但使用 NSNotificationCenter 作为本地默认值。这对于 NSUserDefaultsDidChangeNotification 等事件是必要的。

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

如果 event 为 null，NSNotificationCenter 不会将其作为传递给观察者的条件。更多信息请参见 文档。

🌐 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 字符串 | 空
  • callback 函数
    • event 字符串
    • 'userInfo'唱片<string, unknown>
    • object 字符串

返回 number - 此订阅的 ID

🌐 Returns number - The ID of this subscription

与 subscribeNotification 相同，但使用 NSWorkspace.sharedWorkspace.notificationCenter。 这在 NSWorkspaceDidActivateApplicationNotification 等事件中是必要的。

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

如果 event 为 null，NSWorkspaceNotificationCenter 不会将其作为传递给观察者的条件。更多信息请参见 文档。

🌐 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 整数

移除订阅者 id。

🌐 Removes the subscriber with id.

systemPreferences.unsubscribeLocalNotification(id) macOS​

  • id 整数

与 unsubscribeNotification 相同，但将订阅者从 NSNotificationCenter 中移除。

🌐 Same as unsubscribeNotification, but removes the subscriber from NSNotificationCenter.

systemPreferences.unsubscribeWorkspaceNotification(id) macOS​

  • id 整数

与 unsubscribeNotification 相同，但将订阅者从 NSWorkspace.sharedWorkspace.notificationCenter 中移除。

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

systemPreferences.registerDefaults(defaults) macOS​

  • 'defaults' 记录<string, string | boolean | number> - （key: value'）用户默认词典

将指定的默认值添加到你应用的 NSUserDefaults 中。

🌐 Add the specified defaults to your application's NSUserDefaults.

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

  • key 字符串
  • type 类型 - 可以是 string、boolean、integer、float、double、url、array 或 dictionary。

返回 UserDefaultTypes[Type] - NSUserDefaults 中 key 的值。

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

一些流行的 key 和 type 有：

🌐 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 字符串
  • type 类型 - 可以是 string、boolean、integer、float、double、url、array 或 dictionary。
  • 'value' 用户默认类型[类型]

在 NSUserDefaults 中设置 key 的值。

🌐 Set the value of key in NSUserDefaults.

请注意，type 应该与 value 的实际类型匹配。如果不匹配，将会抛出异常。

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

一些流行的 key 和 type 有：

🌐 Some popular key and types are:

  • ApplePressAndHoldEnabled：boolean

systemPreferences.removeUserDefault(key) macOS​

  • key 字符串

移除 NSUserDefaults 中的 key。这可以用来恢复以前使用 setUserDefault 设置的 key 的默认或全局值。

🌐 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()​

返回 string - 用户当前系统范围的强调色偏好，采用 RGBA 十六进制形式。

🌐 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"

此 API 仅适用于 macOS 10.14 Mojave 或更高版本。

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

systemPreferences.getColor(color) Windows macOS​

  • color 字符串 - 以下值之一：
    • 在 Windows 上：
      • 3d-dark-shadow - 三维显示元素的深色阴影。
      • 3d-face - 三维显示元素和对话框背景的面色。
      • 3d-highlight - 三维显示元素的高亮颜色。
      • 3d-light - 三维显示元素的浅色。
      • 3d-shadow - 三维显示元素的阴影颜色。
      • active-border - 活动窗口边框。
      • active-caption - 活动窗口标题栏。如果启用了渐变效果，指定活动窗口标题栏渐变色的左侧颜色。
      • active-caption-gradient - 活动窗口标题栏颜色渐变的右侧颜色。
      • app-workspace - 多文档界面（MDI）应用的背景颜色。
      • button-text - 按钮上的文本。
      • caption-text - 标题、大小框和滚动条箭头框中的文本。
      • desktop - 桌面背景颜色。
      • disabled-text - 灰色（禁用）文本。
      • highlight - 在控件中选择的项目。
      • highlight-text - 在控件中选择的项目的文本。
      • hotlight - 超链接或热跟踪项目的颜色。
      • inactive-border - 非活动窗口边框。
      • inactive-caption - 非活动窗口标题。如果启用了渐变效果，指定非活动窗口标题栏渐变色的左侧颜色。
      • inactive-caption-gradient - 非活动窗口标题栏颜色渐变的右侧颜色。
      • inactive-caption-text - 非活动标题中的文本颜色。
      • info-background - 工具提示控件的背景颜色。
      • info-text - 工具提示控件的文本颜色。
      • menu - 菜单背景。
      • menu-highlight - 当菜单以平面菜单显示时，用于高亮菜单项的颜色。
      • menubar - 菜单作为扁平菜单出现时，菜单栏的背景颜色。
      • menu-text - 菜单中的文本。
      • scrollbar - 滚动条灰色区域。
      • window - 窗口背景。
      • window-frame - 窗框。
      • window-text - 窗口中的文本。
    • 在 macOS 上
      • control-background - 大型界面元素（例如浏览器或表格）的背景。
      • control - 控件的表面。
      • control-text -未被禁用的控件文本。
      • disabled-control-text - 禁用的控件的文本。
      • find-highlight - 查找指示器的颜色。
      • grid - 界面元素（例如表格）的网格线。
      • header-text - 表中标题单元格的文本。
      • highlight - 屏幕上的虚拟光源。
      • keyboard-focus-indicator - 使用键盘进行界面导航时，当前聚焦控件周围出现的环。
      • label - 包含主要内容的标签文本。
      • link - 其他内容的链接。
      • placeholder-text - 控件或文本视图中的占位符字符串。
      • quaternary-label - 重要性低于三级标签的标签文本，例如水印文本。
      • scrubber-textured-background - 触摸栏中洗涤器的背景。
      • secondary-label - 比普通标签重要性较低的标签文本，例如用于表示副标题或附加信息的标签。
      • selected-content-background - 关键窗口或视图中选定内容的背景。
      • selected-control - 选定控件的表面。
      • selected-control-text - 选定控件的文本。
      • selected-menu-item-text - 所选菜单的文本。
      • selected-text-background - 所选文本的背景。
      • selected-text - 选定的文本。
      • separator - 不同内容部分之间的分隔符。
      • shadow - 屏幕上凸起的对象投射的虚拟阴影。
      • tertiary-label - 重要性低于辅助标签的标签文本，例如用于表示禁用文本的标签。
      • text-background - 文本背景。
      • text - 文档中的文本。
      • under-page-background - 文档内容背后的背景。
      • unemphasized-selected-content-background - 在非关键窗口或视图中选择的内容。
      • unemphasized-selected-text-background - 非关键窗口或视图中选定文本的背景。
      • unemphasized-selected-text - 非关键窗口或视图中的选定文本。
      • window-background - 窗口的背景。
      • window-frame-text - 窗口标题栏区域中的文本。

返回 string - 系统颜色设置的 RGBA 十六进制形式 (#RRGGBBAA)。有关更多详情，请参阅 Windows 文档 和 macOS 文档。

🌐 Returns string - The system color setting in RGBA hexadecimal form (#RRGGBBAA). See the Windows docs and the macOS docs for more details.

以下颜色仅在 macOS 10.14 上可用：find-highlight、selected-content-background、separator、unemphasized-selected-content-background、unemphasized-selected-text-background 和 unemphasized-selected-text。

🌐 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 字符串 - 以下值之一：
    • blue
    • brown
    • gray
    • green
    • orange
    • pink
    • purple
    • red
    • yellow

返回 string - 以 #RRGGBBAA 格式表示的标准系统颜色。

🌐 Returns string - The standard system color formatted as #RRGGBBAA.

返回几种标准系统颜色之一，这些颜色会根据亮度变化以及“增强对比度”和“减少透明度”等辅助功能设置的变化自动调整。更多详情请参见 Apple 文档。

🌐 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​

返回 string - 可以是 dark、light 或 unknown。

🌐 Returns string - Can be dark, light or unknown.

获取当前应用所使用的 macOS 外观设置，对应 NSApplication.effectiveAppearance

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

systemPreferences.canPromptTouchID() macOS​

返回 boolean —— 表示此设备是否具备使用 Touch ID 的能力。

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

systemPreferences.promptTouchID(reason) macOS​

  • reason 字符串 - 请求使用 Touch ID 进行身份验证的原因

返回 Promise<void> - 如果用户已成功通过 Touch ID 验证，则解析。

🌐 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)
})

这个 API 本身不会保护你的用户数据；它只是一个允许你实现数据保护的机制。原生应用需要在其钥匙串条目上设置例如 kSecAccessControlUserPresence 这样的访问控制常量，以便在读取时自动提示 Touch ID 生物识别同意。这可以通过 node-keytar 来实现，例如用 node-keytar 存储一个加密密钥，并且只有在 promptTouchID() 成功时才获取它。

🌐 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 - true；如果不是，则返回 false。

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

systemPreferences.getMediaAccessStatus(mediaType) Windows macOS​

  • mediaType 字符串 - 可以是 microphone、camera 或 screen。

返回 string - 可以是 not-determined、granted、denied、restricted 或 unknown。

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

在 macOS 10.13 High Sierra 上不需要用户同意，因此此方法将始终返回 granted。 macOS 10.14 Mojave 或更高版本需要获取 microphone 和 camera 访问的同意。 macOS 10.15 Catalina 或更高版本需要获取 screen 访问的同意。

🌐 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 有一个全局设置，用于控制所有 win32 应用对 microphone 和 camera 的访问。在旧版本的 Windows 上，它对 screen 和所有媒体类型始终返回 granted。

🌐 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 字符串 - 所请求的媒体类型；可以是 microphone、camera。

返回 Promise<boolean> - 一个 Promise，如果获得了同意则会以 true 解析，如果被拒绝则会以 false 解析。如果传入了无效的 mediaType，该 Promise 将被拒绝。如果访问请求被拒绝，后来又通过系统偏好设置面板更改，则需要重启应用以使新权限生效。如果访问已经被请求并拒绝，则必须通过偏好设置面板进行更改；不会弹出警告，Promise 将以现有的访问状态解析。

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

重要提示: 为了正确使用此 API，你必须在应用的 Info.plist 文件中设置 NSMicrophoneUsageDescription 和 NSCameraUsageDescription 字符串。这些键的值将用于填充权限对话框，以便用户能够正确了解权限请求的目的。有关如何在 Electron 环境中设置这些内容的更多信息，请参阅Electron 应用分发。

在 macOS 10.14 Mojave 之前不需要用户同意，因此如果你的系统运行的是 10.13 High Sierra，该方法将始终返回 true。

🌐 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：

🌐 Returns Object:

  • shouldRenderRichAnimation 布尔值 - 如果应渲染丰富动画，则返回 true。会根据会话类型（例如远程桌面）和无障碍设置来指导是否使用复杂动画。
  • scrollAnimationsEnabledBySystem 布尔值 - 用于按平台决定是否启用滚动动画（例如由 home/end 键触发的动画）。
  • prefersReducedMotion 布尔值 - 根据平台 API 判断用户是否希望减少动画效果。

返回具有系统动画设置的对象。

🌐 Returns an object with system animation settings.

属性​

🌐 Properties

systemPreferences.accessibilityDisplayShouldReduceTransparency macOS 已弃用​

🌐 systemPreferences.accessibilityDisplayShouldReduceTransparency macOS Deprecated

boolean 属性用于确定应用是否避免使用半透明背景。这对应于 NSWorkspace.accessibilityDisplayShouldReduceTransparency

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

已弃用： 请使用新的 nativeTheme.prefersReducedTransparency API。

systemPreferences.effectiveAppearance macOS 只读​

🌐 systemPreferences.effectiveAppearance macOS Readonly

一个可以是 dark、light 或 unknown 的 string 属性。

🌐 A string property that can be dark, light or unknown.

返回当前应用所使用的 macOS 外观设置，对应 NSApplication.effectiveAppearance

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