跳到主要内容

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 文件中设置 NSMicrophoneUsageDescriptionNSCameraUsageDescription 字符串。这些键的值将用于填充权限对话框,以便用户能够正确了解权限请求的目的。有关如何在 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