Aller au contenu principal

systemPreferences

Récuperer les préférences système.

Processus : Main

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

Événements​

L'objet systemPreferences émet les événements suivants :

Événement : 'accent-color-changed' Windows​

Retourne :

  • event Event
  • newColor string - La nouvelle couleur RGBA que l'utilisateur à assigné à son système.

Événement : 'color-changed' Windows​

Retourne :

  • event Event

Événement : 'inverted-color-scheme-changed' Windows Deprecated​

Retourne :

  • event Event
  • invertedColorScheme boolean - true si un schéma de couleur inversé (un schéma de couleur à contraste élevé avec le texte clair et les fonds sombres) est utilisé, faux sinon.

Déprécié : Doit utiliser le nouvel événement mis à jour sur le module nativeTheme.

Événement : 'high-contrast-color-scheme-changed' Windows Deprecated​

Retourne :

  • event Event
  • highContrastColorScheme boolean - true si un thème à contraste élevé est utilisé, false sinon.

Déprécié : Doit utiliser le nouvel événement mis à jour sur le module nativeTheme.

Méthodes​

systemPreferences.isDarkMode() macOS Windows Déprécié​

Retourne boolean - Si le système est en mode sombre.

Déprécié : Doit utiliser le nouveau nativeTheme.shouldUseDarkColors API.

systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS​

Retourne boolean - Si l'option Swipe entre les pages est activé.

systemPreferences.postNotification(event, userInfo[, deliverImmediately]) macOS​

  • event string
  • userInfo Record<string, any>
  • deliverImmédiately booléen (facultatif) - true pour publier des notifications immédiatement même lorsque l'application d'abonnement est inactive.

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.postLocalNotification(event, userInfo) macOS​

  • event string
  • userInfo Record<string, any>

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.postWorkspaceNotification(event, userInfo) macOS​

  • event string
  • userInfo Record<string, any>

Posts event as native notifications of macOS. The userInfo is an Object that contains the user information dictionary sent along with the notification.

systemPreferences.subscribeNotification(event, callback) macOS​

  • event string | null
  • callback Function
    • event string
    • userInfo Record<string, unknown>
    • chaîne objet

Returns number - The ID of this subscription

S'abonne aux notifications natives de macOS, callback sera appelé avec callback(event, userInfo) lorsque le event correspondant se produit. userInfo est un objet qui contient le dictionnaire d'information utilisateur envoyé avec la notification. L'objet object est l'expéditeur de la notification, et ne supporte que les valeurs NSString pour le moment.

Le id de l'abonné est retourné, qui peut être utilisé pour désabonner le événement.

Sous le capot, cette API s'abonne à NSDistributedNotificationCenter, Les valeurs d'exemple de event sont :

  • AppleInterfaceThemeChangedNotification
  • AppleAquaColorVariantChanged
  • AppleColorPreferencesChangedNotification
  • AppleShowScrollBarsSettingChanged

If event is null, the NSDistributedNotificationCenter doesn’t use it as criteria for delivery to the observer. See docs for more information.

systemPreferences.subscribeLocalNotification(event, callback) macOS​

  • event string | null
  • callback Function
    • event string
    • userInfo Record<string, unknown>
    • chaîne objet

Returns number - The ID of this subscription

Same as subscribeNotification, but uses NSNotificationCenter for local defaults. Ceci est nécessaire pour des événements tels que NSUserDefaultsDidChangeNotification.

If event is null, the NSNotificationCenter doesn’t use it as criteria for delivery to the observer. See docs for more information.

systemPreferences.subscribeWorkspaceNotification(event, callback) macOS​

  • event string | null
  • callback Function
    • event string
    • userInfo Record<string, unknown>
    • chaîne objet

Returns number - The ID of this subscription

Identique à subscribeNotification, mais utilise NSWorkspace.sharedWorkspace.notificationCenter. Ceci est nécessaire pour des événements tels que NSWorkspaceDidActivateApplicationNotification.

If event is null, the NSWorkspaceNotificationCenter doesn’t use it as criteria for delivery to the observer. See docs for more information.

systemPreferences.unsubscribeNotification(id) macOS​

  • id Integer

Supprime l'abonnement avec l'id.

systemPreferences.unsubscribeLocalNotification(id) macOS​

  • id Integer

Identique à unsubscribeNotification, mais supprime l'abonné de NSNotificationCenter.

systemPreferences.unsubscribeWorkspaceNotification(id) macOS​

  • id Integer

Identique à unsubscribeNotification, mais supprime l'abonné de NSWorkspace.sharedWorkspace.notificationCenter.

systemPreferences.registerDefaults(defaults) macOS​

  • defaults Record<string, string | boolean | number> - a dictionary of (key: value) user defaults

Ajoute les valeurs par défaut à NSUserDefaultsde votre application.

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

  • key string
  • type Type - Can be string, boolean, integer, float, double, url, array or dictionary.

Returns UserDefaultTypes[Type] - The value of key in NSUserDefaults.

Certaines clé populaires et types sont:

  • AppleInterfaceStyle: chaîne
  • AppleAquaColorVariant: integer
  • AppleHighlightColor: chaîne
  • AppleShowScrollBars: string
  • NSNavRecentPlaces: tableau
  • NSPreferredWebServices: dictionnaire
  • NSUserDictionaryReplacementItems: tableau

systemPreferences.setUserDefault(key, type, value) macOS​

  • key string
  • type string - Can be string, boolean, integer, float, double, url, array or dictionary.
  • value string

Définit la valeur de clé dans NSUserDefaults.

Note that type should match actual type of value. An exception is thrown if they don't.

Certaines clé populaires et types sont:

  • ApplePressAndHoldEnabled : booléen

systemPreferences.removeUserDefault(key) macOS​

  • key string

Removes the key in NSUserDefaults. This can be used to restore the default or global value of a key previously set with setUserDefault.

systemPreferences.isAeroGlassEnabled() Windows​

Retourne boolean - true si la composition DWM (Aero Glass) est activée, et false sinon.

Un exemple d'utilisation pour déterminer si vous devez créer une fenêtre transparente ou non (les fenêtres transparentes ne fonctionneront pas correctement lorsque la composition DWM est désactivée) :

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.loadURL(`file://${__dirname}/index.html`)
} else {
  // Pas de transparence, donc nous chargeons un repli qui utilise des styles de base.
  win.loadURL(`file://${__dirname}/fallback.html`)
}

systemPreferences.getAccentColor() Windows macOS​

Retourne string - Les utilisateurs du système actuel de préférence de couleur d'accentuation large en RGBA forme hexadécimale.

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"

Cette API n'est disponible que sur macOS 10.14 Mojave ou plus récent.

systemPreferences.getColor(color) Windows macOS​

  • color string - One of the following values:
    • On Windows:
      • 3d-dark-shadow - Ombre noir pour les éléments affichés en trois dimensions.
      • 3d-face - Couleur de la face pour les éléments affichés en trois dimensions et le fond des boîtes de dialogue.
      • 3d-hihlight - Couleur de surlignage pour les éléments affichés en trois dimensions.
      • 3d-light - Couleur de la lumière pour les éléments affichés en trois dimensions.
      • 3d-shadow - Couleur d'ombre pour les éléments affichés en trois dimensions.
      • active-border - Bordure de la fenêtre active.
      • active-caption - Active window title bar. Specifies the left side color in the color gradient of an active window's title bar if the gradient effect is enabled.
      • active-caption-gradient - Couleur du côté droit du dégradé de couleur de la barre de titre de la fenêtre active.
      • app-workspace - Couleur de fond d'une interface d'application de document multiple (MDI).
      • button-text - Texte sur les boutons d'envoi.
      • caption-text - Texte dans une légende, boîte de dimensions, boîte avec la flèche pour la barre de défilement.
      • desktop - Couleur de fond du bureau.
      • disabled-text - Texte grisé (désactivé).
      • highlight - Élément(s) sélectionné(s) dans un groupe.
      • highlight-text - Texte des éléments sélectionnés dans un contrôle.
      • hotlight - Couleur pour un lien hypertexte ou un élément à suivre.
      • inactive-border - Bordure de fenêtre inactive.
      • inactive-caption - Inactive window caption. Specifies the left side color in the color gradient of an inactive window's title bar if the gradient effect is enabled.
      • inactive-caption-gradient - Couleur du côté droit dans le gradient de couleur d'une barre de titre de la fenêtre inactive.
      • inactive-caption-text - Color of text in an inactive caption.
      • info-background - Background color for tooltip controls.
      • info-text - Text color for tooltip controls.
      • menu - Menu background.
      • menu-highlight - The color used to highlight menu items when the menu appears as a flat menu.
      • menubar - La couleur de fond de la barre de menu lorsque les menus apparaissent sous la forme de menus plats.
      • menu-text - Texte dans les menus.
      • scrollbar - Zone grise de la barre de défilement.
      • window - Fond de la fenêtre.
      • window-frame - Cadre de fenêtres.
      • window-text - Texte dans windows.
    • On macOS
      • alternate-selected-control-text - Le texte sur une surface sélectionnée dans une liste ou un tableau. déprécié
      • control-background - L'arrière-plan d'un élément de grande interface, tel qu'un navigateur ou un tableau.
      • control - La surface d'un contrôle.
      • control-text -Le texte d'un contrôle qui n'est pas désactivé.
      • disabled-control-text - Le texte d'un contrôle qui est désactivé.
      • find-highlight - La couleur d'un indicateur de recherche.
      • grille - Les lignes de grilles d'un élément d'interface comme une table.
      • header-text - Le texte d'une cellule d'en-tête dans un tableau.
      • surlignement - La source de lumière virtuelle à l'écran.
      • keyboard-focus-indicator - L'anneau qui apparaît autour du contrôle actuellement focalisé lors de l'utilisation du clavier pour la navigation de l'interface.
      • label - Le texte d'une étiquette contenant le contenu principal.
      • lien - Un lien vers un autre contenu.
      • placeholder-text - Une chaîne de caractères dans une vue de contrôle ou de texte.
      • quaternary-label - Le texte d'une étiquette de moindre importance qu'une étiquette tertiaire telle que le texte du filigrane.
      • scrubber-textured-background - L'arrière-plan d'un scrubber dans la barre tactile.
      • étiquette secondaire - Le texte d'une étiquette de moindre importance qu'une étiquette normale telle qu'une étiquette utilisée pour représenter une sous-rubrique ou des informations complémentaires.
      • selected-content-background - L'arrière-plan du contenu sélectionné dans une fenêtre ou une vue clé.
      • selected-control - La surface d'une commande sélectionnée.
      • selected-control-text - Le texte d'une commande sélectionnée.
      • selected-menu-item-text - Le texte d'un menu sélectionné.
      • selected-text-background - L'arrière-plan du texte sélectionné.
      • texte sélectionné - Texte sélectionné.
      • Séparateur - Un séparateur entre différentes sections de contenu.
      • shadow - L'ombre virtuelle projetée par un objet levé à l'écran.
      • étiquette-tertiaire - Le texte d'une étiquette de moindre importance qu'une étiquette secondaire telle qu'une étiquette utilisée pour représenter le texte désactivé.
      • text-background - Fond d'écran du texte.
      • text - Le texte dans un document.
      • sous-page-background - L'arrière-plan derrière le contenu d'un document.
      • unemphaszed-selected-content-background - Le contenu sélectionné dans une fenêtre ou une vue non-clé.
      • unemphaszed-selected-text-background - Un fond pour le texte sélectionné dans une fenêtre ou une vue non-clé.
      • unemphaszed-selected-text - Texte sélectionné dans une fenêtre ou une vue non-clé.
      • window-background - L'arrière-plan d'une fenêtre.
      • window-frame-text - Le texte dans la barre de titre de la fenêtre.

Retourne string - Le paramètre de couleur système sous forme hexadécimale RVB (#ABCDEF). See the Windows docs and the macOS docs for more details.

The following colors are only available on macOS 10.14: find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, and unemphasized-selected-text.

systemPreferences.getSystemColor(color) macOS​

  • color string - One of the following values:
    • bleu
    • marron
    • gris
    • vert
    • orange
    • rose
    • violet
    • rouge
    • jaune

Returns string - The standard system color formatted as #RRGGBBAA.

Returns one of several standard system colors that automatically adapt to vibrancy and changes in accessibility settings like 'Increase contrast' and 'Reduce transparency'. See Apple Documentation for more details.

systemPreferences.isInvertedColorScheme() Windows Déprécié​

Returns boolean - true if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is active, false otherwise.

Déprécié : Doit utiliser le nouveau nativeTheme.shouldUseInvertedColorScheme API.

systemPreferences.isHighContrastColorScheme() macOS Windows Déprécié​

Returns boolean - true if a high contrast theme is active, false otherwise.

Déprécié : Doit utiliser le nouveau nativeTheme.shouldUseHighContrastColors API.

systemPreferences.getEffectiveAppearance() macOS​

Returns string - Can be dark, light or unknown.

Gets the macOS appearance setting that is currently applied to your application, maps to NSApplication.effectiveAppearance

systemPreferences.getAppLevelAppearance() macOS Déprécié​

Returns string | null - Can be dark, light or unknown.

Gets the macOS appearance setting that you have declared you want for your application, maps to NSApplication.appearance. You can use the setAppLevelAppearance API to set this value.

systemPreferences.setAppLevelAppearance(appearance) macOS Déprécié​

  • appearance string | null - Can be dark or light

Sets the appearance setting for your application, this should override the system default and override the value of getEffectiveAppearance.

systemPreferences.canPromptTouchID() macOS​

Returns boolean - whether or not this device has the ability to use Touch ID.

NOTE: This API will return false on macOS systems older than Sierra 10.12.2.

systemPreferences.promptTouchID(reason) macOS​

  • reason string - The reason you are asking for Touch ID authentication

Returns Promise<void> - resolves if the user has successfully authenticated with 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)
})

This API itself will not protect your user data; rather, it is a mechanism to allow you to do so. Native apps will need to set Access Control Constants like kSecAccessControlUserPresence on their keychain entry so that reading it would auto-prompt for Touch ID biometric consent. This could be done with node-keytar, such that one would store an encryption key with node-keytar and only fetch it if promptTouchID() resolves.

NOTE: This API will return a rejected Promise on macOS systems older than Sierra 10.12.2.

systemPreferences.isTrustedAccessibilityClient(prompt) macOS​

  • prompt boolean - whether or not the user will be informed via prompt if the current process is untrusted.

Returns boolean - true if the current process is a trusted accessibility client and false if it is not.

systemPreferences.getMediaAccessStatus(mediaType) Windows macOS​

  • mediaType string - Peut être microphone, camera ou screen.

Returns string - Can be not-determined, granted, denied, restricted or unknown.

This user consent was not required on macOS 10.13 High Sierra or lower so this method will always return granted. macOS 10.14 Mojave or higher requires consent for microphone and camera access. macOS 10.15 Catalina or higher requires consent for screen access.

Windows 10 has a global setting controlling microphone and camera access for all win32 applications. It will always return granted for screen and for all media types on older versions of Windows.

systemPreferences.askForMediaAccess(mediaType) macOS​

  • mediaType string - the type of media being requested; can be microphone, camera.

Returns Promise<boolean> - A promise that resolves with true if consent was granted and false if it was denied. If an invalid mediaType is passed, the promise will be rejected. If an access request was denied and later is changed through the System Preferences pane, a restart of the app will be required for the new permissions to take effect. If access has already been requested and denied, it must be changed through the preference pane; an alert will not pop up and the promise will resolve with the existing access status.

Important: In order to properly leverage this API, you must set the NSMicrophoneUsageDescription and NSCameraUsageDescription strings in your app's Info.plist file. Les valeurs de ces clés seront utilisées pour remplir les boîtes de dialogue des permissions afin que l'utilisateur soit correctement informé du but de la demande de permission. Voir Electron Application Distribution pour plus d'informations sur la façon de les définir dans le contexte d'Electron.

Ce consentement de l'utilisateur n'était pas requis avant macOS 10. 4 Mojave, donc cette méthode retournera toujours true si votre système fonctionne 10.13 Haute Sierra ou moins.

systemPreferences.getAnimationSettings()​

Retourne Object:

  • shouldRenderRichAnimation boolean - Renvoie vrai si les animations riches doivent être rendues. Regarde le type de session (par exemple, bureau distant) et les paramètres d'accessibilité pour donner des conseils pour les animations lourdes.
  • scrollAnimationsEnabledBySystem boolean - Détermine par plate-forme si les animations de défilement (par exemple produites par la touche maison/fin) doivent être activées.
  • prefersReducedMotion booléen - Détermine si l'utilisateur souhaite des mouvements réduits basés sur des API de plate-forme.

Retourne un objet avec les paramètres d'animation du système.

Propriétés​

systemPreferences.appLevelApparence macOS​

Une propriété string qui peut être dark, light ou unknown. Il détermine le paramètre d'apparence macOS pour votre application. Cette correspondance aux valeurs dans: NSApplication.appearance. Définir ceci remplacera la valeur par défaut du système ainsi que la valeur de getEffectiveAppearance.

Les valeurs possibles qui peuvent être définies sont dark et light, et les valeurs de retour possibles sont dark, light, et unknown.

Cette propriété n'est disponible que sur macOS 10.14 Mojave ou plus récent.

systemPreferences.effectiveAppearance macOS Readonly​

Une propriété string qui peut être dark, light ou unknown.

Retourne le paramètre d'apparence macOS qui est actuellement appliqué à votre application, correspond à NSApplication.effectiveAppearance