Aller au contenu principal

Tray

Classe : Tray​

Ajoute des icônes et des menus contextuels à la zone de notification du système.

Process: Main

Tray est un EventEmitter.

Creating a basic tray menu
const { app, Menu, Tray } = require('electron')

let tray = null
app.whenReady().then(() => {
  tray = new Tray('/path/to/my/icon')
  const contextMenu = Menu.buildFromTemplate([
    { label: 'Item1', type: 'radio' },
    { label: 'Item2', type: 'radio' },
    { label: 'Item3', type: 'radio', checked: true },
    { label: 'Item4', type: 'radio' }
  ])
  tray.setToolTip('This is my application.')
  tray.setContextMenu(contextMenu)
})

[!TIP] See also: A detailed guide about how to implement Tray menus.

[!WARNING] Electron's built-in classes cannot be subclassed in user code. For more information, see the FAQ.

Considérations relatives à la plate-forme

Linux

  • L'icône de la barre d'état utilise StatusNotifierItem par défaut, lorsqu'il n'est pas disponible dans l'environnement de bureau de l'utilisateur, le GtkStatusIcon sera utilisé à la place.
  • L'évènement click est émis lorsque l'icône de la barre de tache est activée par l'utilisateur, cependant, la fonctionnalité StatusNotifierItem ne spécifie pas quelle action l'active. Pour certains environnemments de bureau, un click droit l'active, mais pour d'autres, cela peut être un double click droit.
  • Afin que les modifications apportées à MenuItems prennent effet, vous devez appeler setContextMenu à nouveau. Par exemple :
const { app, Menu, Tray } = require('electron')

let appIcon = null
app.whenReady().then(() => {
  appIcon = new Tray('/path/to/my/icon')
  const contextMenu = Menu.buildFromTemplate([
    { label: 'Item1', type: 'radio' },
    { label: 'Item2', type: 'radio' }
  ])

  // Changement apporté au menu contextuel
  contextMenu.items[1].checked = false

  //Il faut effectuer un second appel pour Linux suite à la modification du menu contextuel
  appIcon.setContextMenu(contextMenu)
})

MacOS

  • Icons passed to the Tray constructor should be Template Images.
  • Pour vous assurer que votre icône n'apparaitra pas avec un grain trop grossier sur les moniteurs de type retina, assurez-vous que votre image @2x est de 144dpi.
  • Si vous regroupez votre application (par exemple, avec webpack pour le développement), assurez-vous que les noms de fichiers ne sont pas mutilés ou hachés. Le nom du fichier doit se terminer par Template, et l'image @2x doit avoir le même nom de fichier que l'image standard, sinon MacOS ne pourra pas comme par magie inverser les couleurs de votre image ou utilisera l'image haute densité.
  • 16x16 (72dpi) et 32x32@2x (144dpi) fonctionne correctement pour la plupart des icônes.

Windows

  • Pour obtenir les meilleurs effets visuels, il est recommandé d'utiliser des icônes du type ICO .

new Tray(image, [guid])​

  • image (NativeImage | string)
  • guid string (facultatif) Windows macOS - Chaîne unique utilisée pour identifier l'icône de la barre de tâches.

Windows

On Windows, if the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. Les paramètres au niveau de l'OS comme la position de l'icône de la barre d'état dans la barre d'état système persisteront même si le chemin d'accès à l'exécutable change. Si l'exécutable n'est pas signé, alors le GUID est associé de façon permanente au chemin vers l'exécutable. Toute modification du chemin de l'éxécutable casse la création de l'icône de la zone de notification et un nouveau GUID doit être utilisé. Cependant, il est fortement recommandé d'utiliser le paramètre GUID uniquement en conjonction avec les exécutables dont le code est signé. Si une application définit plusieurs icônes dans la zone de notification, chaque icône doit utiliser un GUID distinct.

MacOS

On macOS, the guid is a string used to uniquely identify the tray icon and allow it to retain its position between relaunches. Using the same string for a new tray item will create it in the same position as the previous tray item to use the string.

Créer une nouvelle icône dans la barre de notification avec l'image.

Événements d’instance​

Le module Tray émet les événements suivants :

Événement : 'click'​

Retourne :

Émis lorsque l’utilisateur clique sur l’icône.

Notez que sous Linux, cet événement est émis lorsque l'icône de la barre d'état reçoit une activation et que celle ci n'est pas nécessairement un click sur le bouton gauche de la souris.

Événement : 'right-click' macOS Windows​

Retourne :

Émis lorsque l’utilisateur fait un clique droit sur l’icône.

Événement : 'double-click' macOS Windows​

Retourne :

Émis lorsque l’utilisateur double clique sur l’icône.

Event: 'middle-click' Windows​

Retourne :

Émis lorsque l’utilisateur double clique sur l’icône.

Événement : 'balloon-show' Windows​

Émis lorsque le ballon de la barre d’État s’affiche.

Événement : 'balloon-click' Windows​

Émis lorsque l’utilisateur clique sur le ballon de la barre d'État.

Événement : 'balloon-closed' Windows​

Émis lorsque le ballon de la barre d’État est fermé en raison du délai d’attente dépassé ou de l’utilisateur le ferme manuellement.

Événement : 'drop' macOS​

Émis lorsque un ou des éléments sont glissés et déposés sur l’icône.

Événement : 'drop-files' macOS​

Retourne :

  • event Event
  • files string[] - les chemins d’accès des fichiers déposés.

Émis lorsque des fichiers sont glissés et déposés sur l’icône.

Événement : 'drop-text' macOS​

Retourne :

  • event Event
  • text string - le texte déposé.

Émis lorsqu'un texte est déposé sur l’icône.

Événement : 'drag-enter' macOS​

Émis lorsqu’une opération glisser entre dans la zone de l’icône.

Événement : 'drag-leave' macOS​

Émis lorsqu’une opération glisser sort de la zone de l’icône.

Événement : 'drag-end' macOS​

Émis lorsqu’une opération glisser se termine sur l'icône ou à un autre emplacement.

Évènement: 'mouse-up' macOS​

Retourne :

Émis lorsque la souris est relachée de l'icône de la zone de notification.

[!NOTE] This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.

Événement : 'mouse-move' macOS​

Retourne :

Émis lors d'un click de souris sur l'icône de la zone de notification.

Event: 'mouse-enter' macOS Windows​

Retourne :

Émis lorsque la souris entre dans la zone de l’icône.

Event: 'mouse-leave' macOS Windows​

Retourne :

Émis lorsque la souris sort de la zone de l’icône.

Event: 'mouse-move' macOS Windows​

Retourne :

Émis lorsque la souris bouge dans la zone de l’icône.

Méthodes d’instance​

La classe Tray dispose des méthodes suivantes :

tray.destroy()​

Détruit l’icône immédiatement.

tray.setImage(image)​

Définit l’image associée à l'icône.

tray.setPressedImage(image) macOS​

Définit l’image associée à l'icône quand elle est pressée sur macOS.

tray.setToolTip(toolTip)​

  • toolTip string

Définit le texte au survol pour l'icône. Setting the text to an empty string will remove the tooltip.

tray.setTitle(title[, options]) macOS​

  • title string
  • options Object (facultatif)
    • fontType string (facultatif) - Variante de la famille de police à afficher, peut être monospaced ou monospacedDigit. monospaced est disponible sur macOS 10.15+ Si laissé vide, le titre utilise la police système par défaut.

Définit le titre affiché à côté de l'icône de la barre d'état dans la barre d'état (couleurs support ANSI).

tray.getTitle() macOS​

Retourne string - le titre affiché à côté de l'icône de la barre d'état

tray.setIgnoreDoubleClickEvents(ignore) macOS​

  • ignore boolean

Définit l'option pour ignorer les événements double click. Ignorer ces événements vous permet de détecter chaque clic de l'icône de la barre de notification.

Cette valeur est définie à false par défaut.

tray.getIgnoreDoubleClickEvents() macOS​

Retourne un boolean - Si oui ou non les événènements de double clic seront ignorés.

tray.displayBalloon(options) Windows​

  • Objet options
    • icon (NativeImage | string) (optional) - Icon to use when iconType is custom.
    • iconType string (facultatif) - Peut prendre une des valeurs none, info, warning, error ou custom. La valeur par défaut est custom.
    • title string
    • content string
    • largeIcon boolean (facultatif) - Indique si la grande version de l'icône doit être utilisée. La valeur par défaut est true. Correspond à NIIF_LARGE_ICON.
    • noSound boolean (optionelle) - Ne pas jouer le son associé. Par défaut la valeur est false. Correspond à NIIF_NOSOUND.
    • respectQuietTime boolean (facultatif) - Ne pas afficher la bulle si l'utilisateur actuel est en "temps silencieux". Par défaut la valeur est false. Correspond à NIIF_RESPECT_QUIET_TIME.

Affiche une bulle dans la barre d'État.

tray.removeBalloon() Windows​

Supprime une bulle dans la barre d'État.

tray.focus() Windows​

Redonne le focus à la zone de notification de la barre des tâches. Les icônes de la zone de notification doivent utiliser ce message quand elles ont terminé leur opération d'interface utilisateur. Par exemple, si l'icône affiche un menu de raccourci, mais que l'utilisateur appuie sur ESC pour l'annuler, vous devez utiliser tray.focus() pour redonner le focus à la zone de notification.

tray.popUpContextMenu([menu, position]) macOS Windows​

  • menu Menu (facultatif)
  • position Point (optional) - The pop up position.

Fait apparaître le menu contextuel de l'icône de la barre de notification. Quand menu est transmis, le menu va être affiché au lieu de la barre d'icônes.

La position n’est disponible que sur Windows, et c’est (0, 0) par défaut.

tray.closeContextMenu() macOS Windows​

Ferme un menu contextuel ouvert, tel que défini par tray.setContextMenu().

tray.setContextMenu(menu)​

  • menu Menu | null

Définit le menu contextuel de l'icône.

tray.getBounds() macOS Windows​

Retourne Rectangle

Les limites de l'icône de la barre d’État en tant qu'Objet.

tray.getGUID() macOS Windows​

Returns string | null - The GUID used to uniquely identify the tray icon and allow it to retain its position between relaunches, or null if none is set.

tray.isDestroyed()​

Retourne boolean - si l’icône est détruite.

Considérations relatives aux plate-formes​

Linux​

  • L'icône de la barre d'état utilise StatusNotifierItem par défaut, lorsqu'il n'est pas disponible dans l'environnement de bureau de l'utilisateur, le GtkStatusIcon sera utilisé à la place.
  • L'évènement click est émis lorsque l'icône de la barre de tache est activée par l'utilisateur, cependant, la fonctionnalité StatusNotifierItem ne spécifie pas quelle action l'active. Pour certains environnemments de bureau, un click droit l'active, mais pour d'autres, cela peut être un double click droit.
  • Afin que les modifications apportées à MenuItems prennent effet, vous devez appeler setContextMenu à nouveau. Par exemple :
const { app, Menu, Tray } = require('electron')

let appIcon = null
app.whenReady().then(() => {
  appIcon = new Tray('/path/to/my/icon')
  const contextMenu = Menu.buildFromTemplate([
    { label: 'Item1', type: 'radio' },
    { label: 'Item2', type: 'radio' }
  ])

  // Changement apporté au menu contextuel
  contextMenu.items[1].checked = false

  //Il faut effectuer un second appel pour Linux suite à la modification du menu contextuel
  appIcon.setContextMenu(contextMenu)
})

macOS​

  • Icons passed to the Tray constructor should be Template Images.
  • Pour vous assurer que votre icône n'apparaitra pas avec un grain trop grossier sur les moniteurs de type retina, assurez-vous que votre image @2x est de 144dpi.
  • Si vous regroupez votre application (par exemple, avec webpack pour le développement), assurez-vous que les noms de fichiers ne sont pas mutilés ou hachés. Le nom du fichier doit se terminer par Template, et l'image @2x doit avoir le même nom de fichier que l'image standard, sinon MacOS ne pourra pas comme par magie inverser les couleurs de votre image ou utilisera l'image haute densité.
  • 16x16 (72dpi) et 32x32@2x (144dpi) fonctionne correctement pour la plupart des icônes.

Windows​

  • Pour obtenir les meilleurs effets visuels, il est recommandé d'utiliser des icônes du type ICO .