systemPreferences
システムの環境設定を取得します。
const { systemPreferences } = require('electron')
console.log(systemPreferences.isAeroGlassEnabled())
イベント
systemPreferences
オブジェクトは以下のイベントを発生させます。
イベント: 'accent-color-changed' Windows
戻り値:
event
EventnewColor
string - ユーザがシステムのアクセントカラーに割り当てる新しいRGBAカラー。
イベント: 'color-changed' Windows
戻り値:
event
Event
メソッド
systemPreferences.isSwipeTrackingFromScrollEventsEnabled()
macOS
戻り値 boolean
- ページ間をスワイプの設定がオンかどうか。
systemPreferences.postNotification(event, userInfo[, deliverImmediately])
macOS
event
stringuserInfo
Record<string, any>deliverImmediately
boolean (任意) - サブスクライブ中のアプリがアクティブでなくても通知をすぐに送信する場合はtrue
です。
macOS のネイティブ通知として event
を送信します。 userInfo
は、通知とともに送信されるユーザ情報辞書を含むオブジェクトです。
systemPreferences.postLocalNotification(event, userInfo)
macOS
event
stringuserInfo
Record<string, any>
macOS のネイティブ通知として event
を送信します。 userInfo
は、通知とともに送信されるユーザ情報辞書を含むオブジェクトです。
systemPreferences.postWorkspaceNotification(event, userInfo)
macOS
event
stringuserInfo
Record<string, any>
macOS のネイティブ通知として event
を送信します。 userInfo
は、通知とともに送信されるユーザ情報辞書を含むオブジェクトです。
systemPreferences.subscribeNotification(event, callback)
macOS
event
string | nullcallback
Functionevent
stringuserInfo
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 | nullcallback
Functionevent
stringuserInfo
Record<string, unknown>object
string
戻り値 number
- この登録のID。
subscribeNotification
と同じですが、ローカルデフォルトでは NSNotificationCenter
を使用します。 これは、NSUserDefaultsDidChangeNotification
などのイベントに必要です。
event
が null の場合、 NSNotificationCenter
はオブザーバーへ伝達する基準としてこれを使用しません。 詳細は ドキュメント をご参照ください。
systemPreferences.subscribeWorkspaceNotification(event, callback)
macOS
event
string | nullcallback
Functionevent
stringuserInfo
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
stringtype
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
stringtype
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
- ウィンドウのタイトルバー領域のテキスト。
- Windows の場合:
戻り値 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 と対応しています。
非推奨: 新しい nativeTheme.prefersReducedTransparency
API を使用してください。
systemPreferences.effectiveAppearance
macOS Readonly
string
型のプロパティです。dark
、light
か unknown
にできます。
NSApplication.effectiveAppearance に割り当てられている、現在アプリケーションに適用されている macOS の外観設定を返します。