跳转到主内容

systemPreferences

获取system preferences.

进程：主进程

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

事件​

systemPreferences 对象触发以下事件:

Event: 'accent-color-changed' Windows​

返回:

  • event Event
  • newColor string - 用户指定的新 RGBA 颜色作为系统偏好颜色.

Event: 'color-changed' Windows​

返回:

  • event Event

Event: 'inverted-color-scheme-changed' Windows 已弃用​

返回:

  • event Event
  • invertedColorScheme boolean - 如果一个反转配色方案(具有浅色文本和深色背景的高对比度配色方案) 被使用为 true ， 否则为 false 。

已弃用： 应使用 nativeTheme 模块中的 updated 新事件。

Event: 'high-contrast-color-scheme-changed' Windows 已弃用​

返回:

  • event Event
  • highContrastColorScheme boolean - 如果高对比主题被使用为 true，否则为 false。

已弃用： 应使用 nativeTheme 模块中的 updated 新事件。

方法​

systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS​

返回值 boolean - 是否在页面设置之间进行滑动。

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

  • event string
  • userInfo Record<string, any>
  • deliverImmediately boolean (可选) - 为 true 时，立即发布通知，即使订阅应用处于非活动状态。

推送 macOS 原生通知 event。 userInfo 是一同发送给通知的包含用户信息字典的对象。

systemPreferences.postLocalNotification(event, userInfo) macOS​

  • event string
  • userInfo Record<string, any>

推送 macOS 原生通知 event。 userInfo 是一同发送给通知的包含用户信息字典的对象。

systemPreferences.postWorkspaceNotification(event, userInfo) macOS​

  • event string
  • userInfo Record<string, any>

推送 macOS 原生通知 event。 userInfo 是一同发送给通知的包含用户信息字典的对象。

systemPreferences.subscribeNotification(event, callback) macOS​

  • event string | null
  • callback Function
    • event string
    • userInfo Record<string, unknown>
    • object string

返回 number - 此订阅的 ID

订阅macOS的原生通知，当通信的 event</ 0>发生时，将调用 <code>callback(event, userInfo) 。 userInfo是一个Object，它包含随通知一起发送的用户信息字典。 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] - 在 key 中的值 NSUserDefaults。

常用的 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 类型 - 可以使 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 - true 如果启用了 DWM composition (Aero Glass), 否则为 false.

使用它来确定是否应创建透明窗口的示例 (当禁用 DWM 组合时, 透明窗口无法正常工作):

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

// 仅当平台支持时，使窗口透明。
if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
  browserOptions.transparent = true
  browserOptions.frame = false
}

// 创建窗口
const win = new BrowserWindow(browserOptions)

// 导航。
if (browserOptions.transparent) {
  win.loadFile('index.html')
} else {
  // 如果没有透明度，我们需要加载一个基本样式的 fallback
  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 - 下列值之一：
    • On 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 - 窗口的文字。
    • On macOS
      • alternate-selected-control-text - 在列表或表格中选中位置的文本。 已废弃
      • control-background - 一个大型接口元素的背景，比如一个浏览器或者表格。
      • control - The surface of a control.
      • control-text -The text of a control that isn’t disabled.
      • disabled-control-text - The text of a control that’s disabled.
      • find-highlight - The color of a find indicator.
      • grid - The gridlines of an interface element such as a table.
      • header-text - The text of a header cell in a table.
      • highlight - The virtual light source onscreen.
      • keyboard-focus-indicator - The ring that appears around the currently focused control when using the keyboard for interface navigation.
      • label - The text of a label containing primary content.
      • link - A link to other content.
      • placeholder-text - A placeholder string in a control or text view.
      • quaternary-label - The text of a label of lesser importance than a tertiary label such as watermark text.
      • scrubber-textured-background - The background of a scrubber in the Touch Bar.
      • secondary-label - The text of a label of lesser importance than a normal label such as a label used to represent a subheading or additional information.
      • selected-content-background - The background for selected content in a key window or view.
      • selected-control - The surface of a selected control.
      • selected-control-text - The text of a selected control.
      • selected-menu-item-text - The text of a selected menu.
      • selected-text-background - The background of selected text.
      • selected-text - Selected text.
      • separator - A separator between different sections of content.
      • shadow - The virtual shadow cast by a raised object onscreen.
      • tertiary-label - The text of a label of lesser importance than a secondary label such as a label used to represent disabled text.
      • text-background - Text background.
      • text - The text in a document.
      • under-page-background - The background behind a document's content.
      • unemphasized-selected-content-background - The selected content in a non-key window or view.
      • unemphasized-selected-text-background - A background for selected text in a non-key window or view.
      • unemphasized-selected-text - Selected text in a non-key window or view.
      • window-background - The background of a window.
      • window-frame-text - The text in the window's titlebar area.

返回 string -系统颜色设置为RGB十六进制格式 (#ABCDEF). 更多详细信息请参阅 Windows docs 和 macOS 文档。

以下颜色仅在 macOS 10.14 上可用：find-hightlight, 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.getAppLevelAppearance() macOS 已弃用​

返回 string | null - 其值可能为 dark、light 或 unknown。

获取您在macOS上为您的应用程序设置的外观，映射到NSApplication.appearance。 您可以使用 setAppLevelAppearance API 来设置此值。

systemPreferences.setAppLevelAppearance(appearance) macOS 已弃用​

  • appearance string | null - 可以是 dark 或 light

设定您的应用程序的外观设置，这应该覆盖系统默认值以及覆盖 getEffectiveAppearance 的值。

systemPreferences.canPromptTouchID() macOS​

返回 boolean - 此设备是否有能力使用 Touch ID。

systemPreferences.promptTouchID(reason) macOS​

  • reason string - 您要求进行触控 ID 身份验证的原因

返回 Promise<void> - resolve如果用户已成功通过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() 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。

This user consent was not required on macOS 10.13 High Sierra so this method will always return granted. macOS 10.14 Mojave 或更高版本需要授权访问 麦克风 和 摄像头。 macOS 10.15 Catalina 或更高版本需要授权访问 屏幕。

Windows 10的全局设置控制了所有win32 应用程序对 麦克风 和 摄像头的访问权限。 在旧版本的 Windows 中总是为 screen 和所有媒体类型返回 granted。

systemPreferences.askForMediaAccess(mediaType) macOS​

  • mediaType string - 请求的媒体类型，可以是microphone 和 camera。

Returns Promise<boolean> - A promise that resolves with true if consent was granted and false if it was denied. 如果传递了无效 mediaType ，则 Promise 将 rejected。 如果权限请求被拒绝，然后通过系统首选项面板进行更改， 需要重新启动应用才能使新的权限生效。 如果已经请求权限或请求被拒绝，它 必须 在首选项面板进行更改；不会弹出提醒，并且 promise 会返回现有的权限状态

Important: In order to properly leverage this API, you must set the NSMicrophoneUsageDescription and NSCameraUsageDescription strings in your app's Info.plist file. The values for these keys will be used to populate the permission dialogs so that the user will be properly informed as to the purpose of the permission request. See Electron Application Distribution for more information about how to set these in the context of Electron.

This user consent was not required until macOS 10.14 Mojave, so this method will always return true if your system is running 10.13 High Sierra.

systemPreferences.getAnimationSettings()​

返回 Object:

  • shouldRenderRichAnimation boolean - Returns true if rich animations should be rendered. Looks at session type (e.g. remote desktop) and accessibility settings to give guidance for heavy animations.
  • scrollAnimationsEnabledBySystem boolean - Determines on a per-platform basis whether scroll animations (e.g. produced by home/end key) should be enabled.
  • prefersReducedMotion boolean - Determines whether the user desires reduced motion based on platform APIs.

返回带有系统动画设置的对象。

属性​

systemPreferences.appLevelAppearance macOS 已弃用​

一个类型为string的属性，此属性可能的值为：dark, light or unknown. 它决定您的应用程序的 macOS 外观设置。 这映射到 NSApplication.appearance 中的值。 设置此选项将覆盖系统默认值以及 getEffectiveAppearance 的值。

可以设置的可能值是 dark 和 light，返回值可能是 dark、light 和 unknown。

此属性仅在 macOS 10.14 Mojave 或更高版本上可用。

systemPreferences.effectiveAppearance macOS 只读​

一个类型为string的属性，此属性可能的值为：dark, light or unknown.

返回当前应用到你的程序上的 macOS 设置项，会映射到 NSApplication.effectiveAppearance