Aller au contenu principal

Tray

Classe : Tray​

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

Processus : Main

Tray est un EventEmitter.

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)
})

Considérations relatives à la plate-forme

Linux

  • Tray icon requires support of StatusNotifierItem in user's desktop environment.
  • The click event is emitted when the tray icon receives activation from user, however the StatusNotifierItem spec does not specify which action would cause an activation, for some environments it is left mouse click, but for some it might be double left mouse click.
  • 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

  // Nouvel appel pour Linux 
  appIcon.setContextMenu(contextMenu)
})

MacOS

  • Les icônes transmises au constructeur Tray doivent être Template Images.
  • Pour vous assurer que votre icône n'apparaisse 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. The filename needs to end in Template, and the @2x image needs to have the same filename as the standard image, or MacOS will not magically invert your image's colors or use the high density image.
  • 16x16 (72dpi) and 32x32@2x (144dpi) work well for most icons.

Windows

  • It is recommended to use ICO icons to get best visual effects.

new Tray(image, [guid])​

  • image (NativeImage | string)
  • guid string (optional) Windows - Assigns a GUID to the tray icon. If the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. OS level settings like the position of the tray icon in the system tray will persist even if the path to the executable changes. If the executable is not code-signed then the GUID is permanently associated with the path to the executable. Changing the path to the executable will break the creation of the tray icon and a new GUID must be used. However, it is highly recommended to use the GUID parameter only in conjunction with code-signed executable. If an App defines multiple tray icons then each icon must use a separate GUID.

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.

Note that on Linux this event is emitted when the tray icon receives an activation, which might not necessarily be left mouse click.

É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.

É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.

Event: 'mouse-up' macOS​

Retourne :

Emitted when the mouse is released from clicking the tray icon.

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.

Event: 'mouse-down' macOS​

Retourne :

Emitted when the mouse clicks the tray icon.

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

Retourne :

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

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

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.

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

  • title string
  • options Object (facultatif)
    • fontType string (optional) - The font family variant to display, can be monospaced or monospacedDigit. monospaced is available in macOS 10.15+ and monospacedDigit is available in macOS 10.11+. When left blank, the title uses the default system font.

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

Sets the option to ignore double click events. Ignoring these events allows you to detect every individual click of the tray icon.

Cette valeur est définie à <0>false</0> 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 (optional) - Can be none, info, warning, error or custom. La valeur par défaut est custom.
    • title string
    • content string
    • largeIcon boolean (optional) - The large version of the icon should be used. La valeur par défaut est true. Maps to NIIF_LARGE_ICON.
    • noSound boolean (optional) - Do not play the associated sound. Par défaut la valeur est false. Maps to NIIF_NOSOUND.
    • respectQuietTime boolean (optional) - Do not display the balloon notification if the current user is in "quiet time". Par défaut la valeur est false. Maps to NIIF_RESPECT_QUIET_TIME.

Affiche une bulle dans la barre d'État.

tray.removeBalloon() Windows​

Removes a tray balloon.

tray.focus() Windows​

Returns focus to the taskbar notification area. Notification area icons should use this message when they have completed their UI operation. For example, if the icon displays a shortcut menu, but the user presses ESC to cancel it, use tray.focus() to return focus to the notification area.

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

  • menu Menu (facultatif)
  • position Point (facultatif) - Position du menu.

Pops up the context menu of the tray icon. When menu is passed, the menu will be shown instead of the tray icon's context menu.

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

tray.closeContextMenu() macOS Windows​

Closes an open context menu, as set by 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.isDestroyed()​

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