跳到主要内容

systemPreferences

获取系统偏好设置。

进程: 主进程, 工具进程

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

事件

systemPreferences 对象发出以下事件

事件: 'accent-color-changed' Windows

返回值

  • 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,并传入 callback(event, userInfo)userInfo 是一个对象,其中包含随通知一起发送的用户信息字典。 object 是通知的发送者,目前仅支持 NSString 值。

返回订阅者的 id,可用于取消订阅 event

此 API 底层订阅了 NSDistributedNotificationCenterevent 的示例值包括

  • 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 - 可以是 stringbooleanintegerfloatdoubleurlarraydictionary

返回值 UserDefaultTypes[Type] - NSUserDefaultskey 的值。

一些常用的 keytype 包括

  • 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 - 可以是 stringbooleanintegerfloatdoubleurlarraydictionary
  • value UserDefaultTypes[Type]

NSUserDefaults 中设置 key 的值。

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

一些常用的 keytype 包括

  • 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 - 窗口标题栏区域中的文本。

返回值 string - 以 RGBA 十六进制格式 (#RRGGBBAA) 表示的系统颜色设置。 有关更多详细信息,请参阅 Windows 文档macOS 文档

以下颜色仅在 macOS 10.14 上可用:find-highlightselected-content-backgroundseparatorunemphasized-selected-content-backgroundunemphasized-selected-text-backgroundunemphasized-selected-text

systemPreferences.getSystemColor(color) macOS

  • color string - 以下值之一
    • blue
    • brown
    • gray
    • green
    • orange
    • pink
    • purple
    • red
    • yellow

返回值 string - 标准系统颜色,格式为 #RRGGBBAA

返回几种标准系统颜色之一,这些颜色自动适应鲜艳度和辅助功能设置的变化,例如“增加对比度”和“减少透明度”。 有关更多详细信息,请参阅 Apple 文档

systemPreferences.getEffectiveAppearance() macOS

返回值 string - 可以是 darklightunknown

获取当前应用于应用程序的 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 - 可以是 microphonecamerascreen

返回值 string - 可以是 not-determinedgranteddeniedrestrictedunknown

在 macOS 10.13 High Sierra 上不需要此用户许可,因此此方法将始终返回 granted。 macOS 10.14 Mojave 或更高版本需要 microphonecamera 访问权限。 macOS 10.15 Catalina 或更高版本需要 screen 访问权限。

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

systemPreferences.askForMediaAccess(mediaType) macOS

  • mediaType string - 请求的媒体类型;可以是 microphonecamera

返回值 Promise<boolean> - 如果授予许可,则 Promise resolve 为 true,如果拒绝许可,则 resolve 为 false。 如果传递了无效的 mediaType,则 Promise 将被 reject。 如果访问请求被拒绝,并且稍后通过“系统偏好设置”面板进行了更改,则需要重启应用程序才能使新权限生效。 如果已请求访问权限但被拒绝,则必须通过偏好设置面板进行更改;不会弹出警报,并且 Promise 将 resolve 为现有访问状态。

重要提示: 为了正确利用此 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 属性,可以是 darklightunknown

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