跳到主要内容

systemPreferences

获取系统偏好设置。

进程：主进程，工具进程

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

事件​

systemPreferences 对象发出以下事件

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

返回

  • event 事件
  • newColor 字符串 - 用户分配为其系统强调色的新 RGBA 颜色。

事件：'color-changed' Windows​

返回

  • event 事件

方法​

systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS​

返回 boolean - “在页面之间滑动”设置是否已启用。

systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOS​

  • event 字符串
  • userInfo Record<string, any>
  • deliverImmediately 布尔值（可选） - 如果设置为 true，即使订阅的应用处于非活动状态，也会立即发布通知。

将 event 作为 macOS 的原生通知发布。 userInfo 是一个对象，其中包含随通知一起发送的用户信息字典。

systemPreferences.postLocalNotification(event, userInfo) macOS​

  • event 字符串
  • userInfo Record<string, any>

将 event 作为 macOS 的原生通知发布。 userInfo 是一个对象，其中包含随通知一起发送的用户信息字典。

systemPreferences.postWorkspaceNotification(event, userInfo) macOS​

  • event 字符串
  • userInfo Record<string, any>

将 event 作为 macOS 的原生通知发布。 userInfo 是一个对象，其中包含随通知一起发送的用户信息字典。

systemPreferences.subscribeNotification(event, callback) macOS​

  • event 字符串 | null
  • callback 函数
    • event 字符串
    • userInfo Record<string, unknown>
    • object 字符串

返回 number - 此订阅的 ID

订阅 macOS 的原生通知，当相应的 event 发生时，将使用 callback(event, userInfo) 调用 callback。 userInfo 是一个对象，其中包含随通知一起发送的用户信息字典。 object 是通知的发送者，目前仅支持 NSString 值。

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

在底层，此 API 订阅 NSDistributedNotificationCenter，event 的示例值为

  • AppleInterfaceThemeChangedNotification
  • AppleAquaColorVariantChanged
  • AppleColorPreferencesChangedNotification
  • AppleShowScrollBarsSettingChanged

如果 event 为 null，则 NSDistributedNotificationCenter 不会将其用作传递给观察者的标准。有关更多信息，请参阅文档。

systemPreferences.subscribeLocalNotification(event, callback) macOS​

  • event 字符串 | null
  • callback 函数
    • event 字符串
    • userInfo Record<string, unknown>
    • object 字符串

返回 number - 此订阅的 ID

与 subscribeNotification 相同，但使用 NSNotificationCenter 进行本地默认设置。 这对于 NSUserDefaultsDidChangeNotification 等事件是必需的。

如果 event 为 null，则 NSNotificationCenter 不会将其用作传递给观察者的标准。有关更多信息，请参阅文档。

systemPreferences.subscribeWorkspaceNotification(event, callback) macOS​

  • event 字符串 | null
  • callback 函数
    • event 字符串
    • userInfo Record<string, unknown>
    • object 字符串

返回 number - 此订阅的 ID

与 subscribeNotification 相同，但使用 NSWorkspace.sharedWorkspace.notificationCenter。 这对于 NSWorkspaceDidActivateApplicationNotification 等事件是必需的。

如果 event 为 null，则 NSWorkspaceNotificationCenter 不会将其用作传递给观察者的标准。有关更多信息，请参阅文档。

systemPreferences.unsubscribeNotification(id) macOS​

  • id 整数

删除具有 id 的订阅者。

systemPreferences.unsubscribeLocalNotification(id) macOS​

  • id 整数

与 unsubscribeNotification 相同，但从 NSNotificationCenter 中删除订阅者。

systemPreferences.unsubscribeWorkspaceNotification(id) macOS​

  • id 整数

与 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 字符串
  • 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 字符串
  • 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 字符串

移除 NSUserDefaults 中的 key。这可以用于恢复先前使用 setUserDefault 设置的 key 的默认值或全局值。

systemPreferences.isAeroGlassEnabled() Windows​

返回 boolean - 如果启用了 DWM 合成 (Aero Glass)，则返回 true，否则返回 false。

一个使用该方法来确定是否应创建透明窗口的示例（当禁用 DWM 合成时，透明窗口将无法正常工作）

const { BrowserWindow, systemPreferences } = require('electron')
const browserOptions = { width: 1000, height: 800 }

// Make the window transparent only if the platform supports it.
if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
  browserOptions.transparent = true
  browserOptions.frame = false
}

// Create the window.
const win = new BrowserWindow(browserOptions)

// Navigate.
if (browserOptions.transparent) {
  win.loadFile('index.html')
} else {
  // No transparency, so we load a fallback that uses basic styles.
  win.loadFile('fallback.html')
}

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-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 字符串 - 请求的媒体类型；可以是 microphone、camera。

返回 Promise<boolean> - 一个 Promise，如果许可被授予则解析为 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