跳至主要內容

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 - 以下其中一個值
    • 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 驗證，則會解析。

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 string - 要求存取的媒體類型；可以是 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。