跳到主要内容

systemPreferences

获取系统偏好设置。

进程: 主进程, 实用进程

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

事件​

`systemPreferences` 对象发出以下事件

事件: 'accent-color-changed' Windows​

返回

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

事件: 'color-changed' Windows​

返回

  • `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)`。`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] - `NSUserDefaults` 中 `key` 的值。

一些常用的 `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()` 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 - 以下值之一：
    • 在 **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 文档。

以下颜色仅在 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 - 以下值之一：
    • 蓝色
    • 棕色
    • 灰色
    • 绿色
    • 橙色
    • 粉色
    • 紫色
    • 红色
    • 黄色

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

返回几种标准系统颜色之一，这些颜色会自动适应鲜艳度和辅助功能设置（如“增加对比度”和“降低透明度”）的变化。有关更多详细信息，请参阅 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 认证，则解析。

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

`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>` - 如果已授予权限，则解析为 `true`；如果已拒绝，则解析为 `false`。如果传入无效的 `mediaType`，Promise 将被拒绝。如果访问请求被拒绝，并且后来通过“系统偏好设置”面板更改，则需要重新启动应用程序才能使新权限生效。如果访问已被请求并拒绝，则*必须*通过偏好设置面板进行更改；不会弹出警报，并且 Promise 将使用现有访问状态进行解析。

**重要提示：** 为了正确利用此 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