systemPreferences
获取系统偏好设置。
const { systemPreferences } = require('electron')
console.log(systemPreferences.getEffectiveAppearance())
事件
systemPreferences
对象发出以下事件
事件: 'accent-color-changed' Windows
返回值
event
EventnewColor
string - 用户分配为其系统强调色的新 RGBA 颜色。
事件: 'color-changed' Windows
返回值
event
Event
方法
systemPreferences.isSwipeTrackingFromScrollEventsEnabled()
macOS
返回值 boolean
- “在页面之间轻扫”设置是否开启。
systemPreferences.postNotification(event, userInfo[, deliverImmediately])
macOS
event
stringuserInfo
Record<string, any>deliverImmediately
boolean (可选) -true
表示立即发布通知,即使订阅应用处于非活动状态。
将 event
作为 macOS 的原生通知发布。 userInfo
是一个对象,其中包含随通知一起发送的用户信息字典。
systemPreferences.postLocalNotification(event, userInfo)
macOS
event
stringuserInfo
Record<string, any>
将 event
作为 macOS 的原生通知发布。 userInfo
是一个对象,其中包含随通知一起发送的用户信息字典。
systemPreferences.postWorkspaceNotification(event, userInfo)
macOS
event
stringuserInfo
Record<string, any>
将 event
作为 macOS 的原生通知发布。 userInfo
是一个对象,其中包含随通知一起发送的用户信息字典。
systemPreferences.subscribeNotification(event, callback)
macOS
event
string | nullcallback
Functionevent
stringuserInfo
Record<string, unknown>object
string
返回值 number
- 此订阅的 ID
订阅 macOS 的原生通知,当相应的 event
发生时,将调用 callback
,并传入 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 | nullcallback
Functionevent
stringuserInfo
Record<string, unknown>object
string
返回值 number
- 此订阅的 ID
与 subscribeNotification
相同,但使用 NSNotificationCenter
用于本地默认设置。 这对于诸如 NSUserDefaultsDidChangeNotification
等事件是必要的。
如果 event
为 null,则 NSNotificationCenter
不会将其用作传递给观察者的标准。 有关更多信息,请参阅 文档。
systemPreferences.subscribeWorkspaceNotification(event, callback)
macOS
event
string | nullcallback
Functionevent
stringuserInfo
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
stringtype
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
stringtype
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.isAeroGlassEnabled()
Windows 已弃用
返回值 boolean
- 如果 DWM 合成 (Aero Glass) 已启用,则为 true
,否则为 false
。
已弃用: 自 Electron 23 以来,此函数始终返回 true
,Electron 23 仅支持 Windows 10+。
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
- Touch Bar 中擦洗器的背景。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 - 以下值之一blue
brown
gray
green
orange
pink
purple
red
yellow
返回值 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 身份验证,则 Promise 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 将被 reject。 如果访问请求被拒绝,并且稍后通过“系统偏好设置”面板进行了更改,则需要重启应用程序才能使新权限生效。 如果已请求访问权限但被拒绝,则必须通过偏好设置面板进行更改;不会弹出警报,并且 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