Aller au contenu principal

systemPreferences

Récuperation des 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 Déprécié​

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é : Vous devez utiliser le nouvel événement updated du module nativeTheme.

Événement : 'high-contrast-color-scheme-changed' Windows Déprécié​

Retourne :

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

Déprécié : Vous devez utiliser le nouvel événement updated du 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 la nouvelle API nativeTheme.shouldUseDarkColors.

systemPreferences.isSwipeTrackingFromScrollEventsEnabled() macOS​

Retourne boolean - Indique si l'option de défilement avec le doigt (Swipe) entre les pages est activée.

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.

Poste event en tant que notifications natives de macOS. userInfo est un objet qui contient le dictionnaire d'information utilisateur envoyé avec la notification.

systemPreferences.postLocalNotification(event, userInfo) macOS​

  • event string
  • userInfo Record<string, any>

Poste event en tant que notifications natives de macOS. userInfo est un objet qui contient le dictionnaire d'information utilisateur envoyé avec la notification.

systemPreferences.postWorkspaceNotification(event, userInfo) macOS​

  • event string
  • userInfo Record<string, any>

Poste event en tant que notifications natives de macOS. userInfo est un objet qui contient le dictionnaire d'information utilisateur envoyé avec la notification.

systemPreferences.subscribeNotification(event, callback) macOS​

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

Retourne number - Identifiant de cet abonnement

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.

L'id de l'abonné est retourné, et pourra être utilisé pour désabonner de l' event.

Sous le capot, cette API s'abonne à NSDistributedNotificationCenter, Voici quelques exemples de valeur pour event :

  • AppleInterfaceThemeChangedNotification
  • AppleAquaColorVariantChanged
  • AppleColorPreferencesChangedNotification
  • AppleShowScrollBarsSettingChanged

Si event est null, le NSDistributedNotificationCenter ne l'utilisera pas comme critère de distribution à l'observateur. Pour plus d'informations voir la documentation.

systemPreferences.subscribeLocalNotification(event, callback) macOS​

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

Retourne number - Identifiant de cet abonnement

Identique à subscribeNotification, mais utilise par contre NSNotificationCenter pour les valeurs locales par défaut. Ceci est nécessaire pour les événements tels que NSUserDefaultsDidChangeNotification.

Si event est null, le NSNotificationCenter ne l'utilisera pas comme critère de distribution à l'observateur. Pour plus d'informations voir la documentation.

systemPreferences.subscribeWorkspaceNotification(event, callback) macOS​

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

Retourne number - Identifiant de cet abonnement

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

Si event est null, le NSWorkspaceNotificationCenter ne l'utilisera pas comme critère de distribution à l'observateur. Pour plus d'informations voir la documentation.

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> - dictionnaire des (key: value) par défaut de l'utilisateur

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

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

  • key string
  • type Type - Peut être string, boolean, integer, float, double, url, array ou dictionary.

Retourne UserDefaultTypes[Type] - La valeur de la clé dans NSUserDefaults.

Certains key et type courants:

  • 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 - Peut être string, boolean, integer, float, double, url, array ou dictionary.
  • value UserDefaultTypes[Type]

Définit la valeur de clé dans NSUserDefaults.

Notez que type doit correspondre au type actuel de value. Si ce n'est pas le cas une exception sera levée.

Certains key et type courants:

  • ApplePressAndHoldEnabled : booléen

systemPreferences.removeUserDefault(key) macOS​

  • key string

Supprime la key dans NSUserDefaults. Cela peut être utilisé pour restaurer la valeur par défaut ou une valeur globale d'une key précédemment définie avec 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 }

// Rendre la fenêtre transparente seulement si l'Os est compatible.
if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
  browserOptions.transparent = true
  browserOptions.frame = false
}

// Création de la fenètre.
const win = new BrowserWindow(browserOptions)

// Navigation.
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 - Une des valeurs suivantes :
    • Sous Windows:
      • 3d-dark-shadow - Ombre noire pour les éléments affichés en trois dimensions.
      • 3d-face - Couleur des surfaces 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 - Bordure de la fenêtre active. Spécifie la couleur de l'extémité gauche du dégradé de couleur de la barre de titre d'une fenêtre active lorsque l'effet de dégradé est activé.
      • active-caption-gradient - Couleur de l'extrémité droite 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 - Légende de fenêtre inactive. Spécifie la couleur de l'extémité gauche du dégradé de couleur de la barre de titre d'une fenêtre active lorsque l'effet de dégradé est activé.
      • 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 - Couleur du texte dans une légende inactive.
      • info-background - Couleur d'arrière-plan pour les commandes des info-bulles.
      • info-text - Couleur du texte pour les commandes des info-bulles.
      • menu - Arrière-plan du menu.
      • menu-highlight - Couleur utilisée pour mettre en surbrillance les liens de menu lorsque le menu apparaît comme un menu plat.
      • 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.
    • Sous 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 - Texte d'un label contenant un 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'un label de moindre importance qu'un label tertiaire telle qu'un texte de filigrane.
      • scrubber-textured-background - L'arrière-plan d'une brosse dans la touchbar.
      • é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). Pour plus de détails voir la documentation Windows et la documentation MacOS.

Les couleurs suivantes ne sont disponibles que sur macOS 10.14 : find-highlight, selected-content-background, separator, unemphasized-selected-content-background, unemphasized-selected-text-background, et unemphasized-selected-text.

systemPreferences.getSystemColor(color) macOS​

  • color string - Une des valeurs suivantes :
    • blue
    • brown
    • gray
    • green
    • orange
    • pink
    • purple
    • red
    • yellow

Retourne une string - La couleur standard du système au format #RRGGBBAA.

Renvoie une des couleurs standard du système qui s'adaptent automatiquement à la vibrance et aux changements dans les paramètres d'accessibilité tels que 'Augmenter le contraste' et 'Réduire la transparence'. Pour plus de détails consultez la documentation d’Apple .

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

Retourne un boolean - la valeur true indique que le jeu de couleurs est inversé ( thème avec contraste élevé avec les textes en clair et les arrière plans en foncé) en cours d'utilisation, false dans les autres cas.

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

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

Retourne un boolean - qui est à true si un thème à contraste élevé est actif, et sinon est à false.

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

systemPreferences.getEffectiveAppearance() macOS​

Retourne une string - Peut être dark, light, ou unknown.

Récupère le paramètre d'apparence macOS qui est actuellement appliqué à votre application et correspondant à NSApplication.effectiveAppearance

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

Retourne string | null - Peut être dark, light ou unknown.

Récupère le paramètre d'apparence macOS que vous avez déclaré pour votre application et correspondant à NSApplication.appearance. Vous pouvez utiliser l'API setAppLevelAppearance pour définir cette valeur.

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

  • appearance string | null - Peut être dark ou light

Définit le paramètre d'apparence de votre application, cela remplace la valeur par défaut du système et la valeur de getEffectiveAppearance.

systemPreferences.canPromptTouchID() macOS​

Retourne un boolean - qui indique si cet appareil a la possibilité d'utiliser Touch ID.

NOTE : Cette API retournera false sur les systèmes sous macOS antérieurs Sierra 10.12.2.

systemPreferences.promptTouchID(reason) macOS​

  • reason string - Raison pour laquelle vous demandez l'authentification Touch ID

Retourne une Promise<void> - qui se résout si l'utilisateur a réussi à s'authentifier avec 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)
})

Cette API ne protégera pas d'elle-même vos données d'utilisateur; il s'agit plutôt d'un mécanisme pour vous permettre de le faire. Les applications natives devront définir des constantes de contrôle d’accès comme kSecAccessControlUserPresence sur leur entrée de Keychain afin que sa lecture demande automatiquement le consentement biométrique Touch ID. Cela peut être fait avec node-keytar de sorte que l’on stocke une clé de chiffrement avec node-keytar et que l'on ne la récupére que si promptTouchID() elle est résolue.

NOTE: Cette API retournera une promesse rejetée sur les systèmes macOS antérieurs à Sierra 10.12.2.

systemPreferences.isTrustedAccessibilityClient(prompt) macOS​

  • prompt boolean - Indique si l'utilisateur sera informé par l'invite que le processus en cours n'est pas fiable.

Retourne boolean - true si le processus actuel est un client d'accessibilité de confiance et false si ce n'est pas le cas.

systemPreferences.getMediaAccessStatus(mediaType) Windows macOS​

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

Retourne string - Peut être not-determined, granted, denied, restricted, ou unknown.

Le consentement de l'utilisateur n'était pas requis sur macOS 10.13 High Sierra ou inférieure, donc cette méthode retournera toujours granted. macOS 10.14 Mojave ou supérieur nécessite l'autorisation d'accès au microphone et à la camera. sur macOS 10.15 Catalina ou version plus récente l'autorisation d'accès au screen est nécessaire.

Windows 10 a un réglage global contrôlant l'accès au microphone et à la camera pour toutes les applications win32. Sur les anciennes versions de Windows cela retournera toujours granted pour screen et pour tous les types de média .

systemPreferences.askForMediaAccess(mediaType) macOS​

  • String mediaType - type de média intérogé; peut être microphone ou camera.

Retourne une Promise<boolean> - qui donne true si le consentement a été donné et false si il a été refusé. Si un mediaType invalide est fourni, la promesse sera rejetée. Si une demande d'accès a été refusée et qu'une requête ultérieure est modifiée via le volet Préférences Système, un redémarrage de l'application sera nécessaire pour que les nouvelles autorisations prennent effet. Si l'accès a déjà été demandé et refusé, il doit être changé via les préférences ; une alerte ne s'affichera pas et la promesse sera résolue avec le statut d'accès existant.

Important : Afin de tirer parti correctelent de cette API, vous devez définir les strings NSMicrophoneUsageDescription et NSCameraUsageDescription dans le fichier Info.plist de votre application. 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