systemPreferences¶

获取系统偏好设置。

进程：主进程、工具进程

const { systemPreferences } = require('electron')

console.log(systemPreferences.getEffectiveAppearance())

事件¶

systemPreferences 对象会发出以下事件：

事件：'accent-color-changed' Windows Linux¶

返回：

• event Event
• newColor string - 用户指定为系统强调色的新 RGBA 颜色。

事件：'color-changed' Windows¶

返回：

• event Event

方法¶

systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS¶

返回 boolean - “在页面之间轻扫”设置是否已开启。

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

• event string
• userInfo Record\<string, any>
• deliverImmediately boolean（可选）- true 表示即使订阅应用处于非活动状态，也立即发布通知。

将 event 作为 macOS 原生通知发布。userInfo 是一个对象，其中包含随通知一起发送的用户信息字典。

systemPreferences.postLocalNotification(event, userInfo) macOS¶

• event string
• userInfo Record\<string, any>

将 event 作为 macOS 原生通知发布。userInfo 是一个对象，其中包含随通知一起发送的用户信息字典。

systemPreferences.postWorkspaceNotification(event, userInfo) macOS¶

• event string
• userInfo Record\<string, any>

将 event 作为 macOS 原生通知发布。userInfo 是一个对象，其中包含随通知一起发送的用户信息字典。

systemPreferences.subscribeNotification(event, callback) macOS¶

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

返回 number - 此订阅的 ID。

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

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

在底层，此 API 会订阅 NSDistributedNotificationCenter，event 的示例值包括：

• AppleInterfaceThemeChangedNotification
• AppleAquaColorVariantChanged
• AppleColorPreferencesChangedNotification
• AppleShowScrollBarsSettingChanged

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

systemPreferences.subscribeLocalNotification(event, callback) macOS¶

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

返回 number - 此订阅的 ID。

与 subscribeNotification 相同，但使用 NSNotificationCenter 来处理本地默认设置。对于诸如 NSUserDefaultsDidChangeNotification 之类的事件，这是必需的。

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

systemPreferences.subscribeWorkspaceNotification(event, callback) macOS¶

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

返回 number - 此订阅的 ID。

与 subscribeNotification 相同，但使用 NSWorkspace.sharedWorkspace.notificationCenter。对于诸如 NSWorkspaceDidActivateApplicationNotification 之类的事件，这是必需的。

如果 event 为 null，则 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> - 一个（key: value）形式的用户默认设置字典。

将指定的默认设置添加到您应用的 NSUserDefaults 中。

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

• key string
• type Type - 可以是 string、boolean、integer、float、double、url、array 或 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 - 可以是 string、boolean、integer、float、double、url、array 或 dictionary。
• value UserDefaultTypes[Type]

在 NSUserDefaults 中设置 key 的值。

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

一些常用的 key 和 type 包括：

• ApplePressAndHoldEnabled: boolean

systemPreferences.removeUserDefault(key) macOS¶

• key string

从 NSUserDefaults 中移除 key。这可用于恢复先前通过 setUserDefault 设置的某个 key 的默认值或全局值。

systemPreferences.getAccentColor()¶

返回 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 - 以下值之一：
• 在 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 - Touch Bar 中 scrubber 的背景。
  • 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 文档。

以下颜色仅在 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 - 以下值之一：
• blue
• brown
• gray
• green
• orange
• pink
• purple
• red
• yellow

返回 string - 标准系统颜色，格式为 #RRGGBBAA。

返回多个标准系统颜色之一，这些颜色会自动适应半透明效果（vibrancy）以及辅助功能设置（如“增强对比度”和“降低透明度”）的变化。详见 Apple 文档。

systemPreferences.getEffectiveAppearance() macOS¶

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

获取当前应用于你的应用程序的 macOS 外观设置，对应 NSApplication.effectiveAppearance。

systemPreferences.canPromptTouchID() macOS¶

返回 boolean - 表示此设备是否能够使用 Touch ID。

systemPreferences.promptTouchID(reason) macOS¶

• reason string - 你请求 Touch ID 认证的原因。

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

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() resolve 时才获取它。

systemPreferences.isTrustedAccessibilityClient(prompt) macOS¶

• prompt boolean - 如果当前进程不受信任，是否通过提示告知用户。

返回 boolean - 如果当前进程是受信任的辅助功能客户端，则返回 true，否则返回 false。

systemPreferences.getMediaAccessStatus(mediaType) Windows macOS¶

• mediaType string - 可以是 microphone、camera 或 screen。

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

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

Windows 10 有一个全局设置，控制所有 win32 应用程序对 microphone 和 camera 的访问权限。对于 screen 以及旧版 Windows 上的所有媒体类型，它将始终返回 granted。

systemPreferences.askForMediaAccess(mediaType) macOS¶

• mediaType string - 被请求的媒体类型；可以是 microphone、camera。

返回 Promise<boolean> - 如果同意授权，则 promise resolve 为 true；如果被拒绝，则 resolve 为 false。如果传入无效的 mediaType，promise 将被拒绝。如果某个访问请求被拒绝，之后通过“系统偏好设置”面板更改，则需要重新启动应用程序才能使新权限生效。如果访问已被请求并拒绝，则 必须 通过偏好设置面板更改；不会弹出提示，promise 会以现有的访问状态 resolve。

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

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

systemPreferences.getAnimationSettings()¶

返回 Object：

• shouldRenderRichAnimation boolean - 如果应渲染丰富的动画，则返回 true。会查看会话类型（例如远程桌面）和辅助功能设置，以针对重度动画提供指导。
• scrollAnimationsEnabledBySystem boolean - 在每个平台的基础上决定是否应启用滚动动画（例如由 Home/End 键产生的动画）。
• prefersReducedMotion boolean - 根据平台 API 确定用户是否希望减少动态效果。

返回包含系统动画设置的对象。

属性¶

systemPreferences.accessibilityDisplayShouldReduceTransparency macOS 已弃用¶

一个 boolean 属性，决定应用是否避免使用半透明背景。此属性对应 NSWorkspace.accessibilityDisplayShouldReduceTransparency。

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

systemPreferences.effectiveAppearance macOS 只读¶

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

返回当前应用于您的应用程序的 macOS 外观设置， 映射至 NSApplication.effectiveAppearance