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` - 窗口标题栏区域中的文本。
- 在 **Windows** 上
返回 `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