本文へスキップ

systemPreferences

システム設定を取得します。

プロセス: メイン、ユーティリティ

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

イベント​

systemPreferencesオブジェクトは、次のイベントを発行します。

イベント: 'accent-color-changed' Windows​

戻り値

  • event イベント
  • newColor string - ユーザーがシステムアクセントカラーとして割り当てた新しいRGBAカラー。

イベント: 'color-changed' Windows​

戻り値

  • event イベント

メソッド​

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が発生すると、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 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> - (キー: 値)ユーザーデフォルトの辞書

指定されたデフォルトをアプリケーションのNSUserDefaultsに追加します。

systemPreferences.getUserDefault<Type extends keyof UserDefaultTypes>(key, type) macOS​

  • key string
  • 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 string
  • 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 string

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の16進数形式で返します。

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 - 3次元表示要素の暗い影。
      • 3d-face - 3次元表示要素とダイアログボックスの背景の面の色。
      • 3d-highlight - 3次元表示要素のハイライトカラー。
      • 3d-light - 3次元表示要素の明るい色。
      • 3d-shadow - 3次元表示要素の影の色。
      • 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 - ウォーターマークテキストなど、3次ラベルよりも重要度の低いラベルのテキスト。
      • 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 - 無効なテキストを表すラベルなど、2次ラベルよりも重要度の低いラベルのテキスト。
      • text-background - テキストの背景。
      • text - ドキュメント内のテキスト。
      • under-page-background - ドキュメントのコンテンツの背後にある背景。
      • unemphasized-selected-content-background - キーウィンドウまたはビュー以外のウィンドウまたはビューで選択されたコンテンツ。
      • unemphasized-selected-text-background - キーウィンドウまたはビュー以外のウィンドウまたはビューで選択されたテキストの背景。
      • unemphasized-selected-text - キーウィンドウまたはビュー以外のウィンドウまたはビューで選択されたテキスト。
      • window-background - ウィンドウの背景。
      • window-frame-text - ウィンドウのタイトルバー領域のテキスト。

stringを返します - RGBAの16進数形式（#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のいずれかになります。

NSApplication.effectiveAppearanceに対応する、アプリケーションに現在適用されているmacOSの外観設定を取得します。

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へのアクセスを制御するグローバル設定があります。古いバージョンのWindowsでは、screenとすべてのメディアタイプに対して常にgrantedを返します。

systemPreferences.askForMediaAccess(mediaType) macOS​

  • mediaType string - 要求されているメディアの種類。microphone、cameraのいずれかになります。

Promise<boolean>を返します - 同意が与えられた場合はtrue、拒否された場合はfalseで解決されるPromise。無効な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 - プラットフォームごとに、スクロールアニメーション（例：ホーム/エンドキーで生成されるアニメーション）を有効にするかどうかを決定します。
  • prefersReducedMotion boolean - プラットフォームAPIに基づいて、ユーザーがモーションの削減を希望するかどうかを決定します。

システムアニメーション設定を含むオブジェクトを返します。

プロパティ​

systemPreferences.accessibilityDisplayShouldReduceTransparency macOS 非推奨​

アプリケーションが半透明の背景の使用を避けるかどうかを決定するbooleanプロパティです。これはNSWorkspace.accessibilityDisplayShouldReduceTransparencyにマップされます。

非推奨: 新しいnativeTheme.prefersReducedTransparency APIを使用してください。

systemPreferences.effectiveAppearance macOS 読み取り専用​

dark、light、またはunknownのいずれかになりうるstringプロパティです。

現在アプリケーションに適用されているmacOSの外観設定を返します。NSApplication.effectiveAppearanceにマップされます。