メインコンテンツへ飛ぶ

systemPreferences

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

プロセス: Main

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

イベント​

systemPreferences オブジェクトは以下のイベントを発生させます。

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

戻り値：

  • event Event
  • newColor string - ユーザがシステムのアクセントカラーに割り当てる新しいRGBAカラー。

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

戻り値：

  • event 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。

対応する event が発生したときに、macOS のネイティブ通知を監視し、callback が callback(event, userInfo) で呼ばれます。 userInfo は、通知とともに送信されるユーザ情報辞書を含むオブジェクトです。 object は通知の送信者であり、現時点では NSString の値のみをサポートしています。

event の登録を解除するために使用できる、監視者の id が返されます。

この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\> - a dictionary of (key: value) user defaults

アプリケーションの 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 と value は以下です。

  • 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 と value は以下です。

  • ApplePressAndHoldEnabled: boolean

systemPreferences.removeUserDefault(key) macOS​

  • key string

NSUserDefaults 内のその key を削除します。 これは、以前に setUserDefaultで設定された key のデフォルトまたはグローバル値を復元するために使用できます。

systemPreferences.isAeroGlassEnabled() Windows​

戻り値 boolean - DWM Composition (Aero Glass) が有効な場合は true、それ以外は false。

透明なウィンドウを作成するかどうかを決定するためにこのメソッドを使用する例です (透明なウィンドウは、DWM Composition が無効のときは正しく動作しません)。

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

// Windowを透明にする。ただしプラットフォームがサポートしている場合に限る。
if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
  browserOptions.transparent = true
  browserOptions.frame = false
}

// windowを作成します。
const win = new BrowserWindow(browserOptions)

// 移動します。
if (browserOptions.transparent) {
  win.loadFile('index.html')
} else {
  // 透明にできないので、基本的なスタイルを使用するフォールバックをロードします。
  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 - 3D 表示要素の暗い影の色。
      • 3d-face - 3D 表示要素とダイアログボックスの背景の表面の色。
      • 3d-highlight - 3D 表示要素のハイライト色。
      • 3d-light - 3D 表示要素の光源色。
      • 3d-shadow - 3D 表示要素の影の色。
      • 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 - タッチバーのスクラバーの背景。
      • 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 の形式の標準システムカラー。

「コントラストを上げる」や「透明度を下げる」など、鮮やかさやアクセシビリティ設定の変更に自動的に適応する標準のシステムカラーの1つを返します。 詳しくは、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 で暗号化キーを保存し、promptTouchID() の場合にのみそれを取得するように、node-keytar を使用して実行されます。

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> - 許可された場合は true で、拒否された場合は false で解決する Promise。 無効な mediaType を渡した場合、Promise は reject されます。 アクセス要求が拒否されて後でシステム環境設定パネルを通して変更した場合、新しい権限の効果を得るためにアプリの再起動が必要です。 すでにアクセスを要求して拒否された場合、設定パネルを通して変更しなければなりません。警告はポップアップせずに 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 と対応しています。

systemPreferences.effectiveAppearance macOS Readonly​

string 型のプロパティです。dark、light か unknown にできます。

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