跳到主要內容

systemPreferences

取得系統偏好設定。

程序：主要、實用

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

事件​

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 boolean (可選) - 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。

已棄用： 自 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 字串 - 以下其中一個值
    • 在 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 字串 - 以下其中一個值
    • 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 字串 - 您要求 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 字串 - 可以是 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