Zum Hauptteil springen

Tray

Klasse: Tray​

Fügen Sie Symbole und Kontextmenüs in den Benachrichtigungsbereich des Systems hinzu.

Process: Main

Tray ist ein 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.

Platform Considerations

Linux

  • Tray icon uses StatusNotifierItem by default, when it is not available in user's desktop environment the GtkStatusIcon will be used instead.
  • 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.
  • In order for changes made to individual MenuItems to take effect, you have to call setContextMenu again. Ein Beispiel:
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' }
  ])

  // Make a change to the context menu
  contextMenu.items[1].checked = false

  // Call this again for Linux because we modified the context menu
  appIcon.setContextMenu(contextMenu)
})

MacOS

  • Icons passed to the Tray constructor should be Template Images.
  • To make sure your icon isn't grainy on retina monitors, be sure your @2x image is 144dpi.
  • If you are bundling your application (e.g., with webpack for development), be sure that the file names are not being mangled or hashed. 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 macOS - A unique string used to identify the tray icon. Must adhere to UUID format.

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

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.

Creates a new tray icon associated with the image.

Instanz-Ereignisse​

Das Tray Modul sendet folgende Ereignisse aus:

Ereignis: 'click'​

Kehrt zurück:

Wird beim Klicken des Tray Icons gesendet.

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

Ereignis: 'right-click' macOS Windows​

Kehrt zurück:

Wird durch einen Rechts Klick auf das Tray Icon gesendet.

Ereignis: 'double-click' macOS Windows​

Kehrt zurück:

Emitted when the tray icon is double clicked.

Event: 'middle-click' Windows​

Kehrt zurück:

Emitted when the tray icon is middle clicked.

Event: 'balloon-show' Windows​

Emitted when the tray balloon shows.

Event: 'balloon-click' Windows​

Emitted when the tray balloon is clicked.

Event: 'balloon-closed' Windows​

Emitted when the tray balloon is closed because of timeout or user manually closes it.

Event: 'drop' macOS​

Emitted when any dragged items are dropped on the tray icon.

Event: 'drop-files' macOS​

Kehrt zurück:

  • event Event
  • files string[] - The paths of the dropped files.

Emitted when dragged files are dropped in the tray icon.

Event: 'drop-text' macOS​

Kehrt zurück:

  • event Event
  • text string - the dropped text string.

Emitted when dragged text is dropped in the tray icon.

Event: 'drag-enter' macOS​

Emitted when a drag operation enters the tray icon.

Event: 'drag-leave' macOS​

Emitted when a drag operation exits the tray icon.

Event: 'drag-end' macOS​

Emitted when a drag operation ends on the tray or ends at another location.

Event: 'mouse-up' macOS​

Kehrt zurück:

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​

Kehrt zurück:

Emitted when the mouse clicks the tray icon.

Event: 'mouse-enter' macOS Windows​

Kehrt zurück:

Emitted when the mouse enters the tray icon.

Event: 'mouse-leave' macOS Windows​

Kehrt zurück:

Emitted when the mouse exits the tray icon.

Event: 'mouse-move' macOS Windows​

Kehrt zurück:

Emitted when the mouse moves in the tray icon.

Beispiel Methoden​

The Tray class has the following methods:

tray.destroy()​

Destroys the tray icon immediately.

tray.setImage(image)​

Sets the image associated with this tray icon.

tray.setPressedImage(image) macOS​

Sets the image associated with this tray icon when pressed on macOS.

tray.setToolTip(toolTip)​

  • toolTip string

Legt den Hover-Text für dieses Tray-Symbol fest. Setting the text to an empty string will remove the tooltip.

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

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

Legt den Titel fest, der neben dem Tray Icon in der Statusleiste angezeigt wird (Unterstütz ANSI-Farben).

tray.getTitle() macOS​

Returns string - the title displayed next to the tray icon in the status bar

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.

This value is set to false by default.

tray.getIgnoreDoubleClickEvents() macOS​

Returns boolean - Whether double click events will be ignored.

tray.displayBalloon(options) Windows​

  • options Objekt
    • icon (NativeImage | string) (optional) - Icon to use when iconType is custom.
    • iconType string (optional) - Can be none, info, warning, error or custom. Standard ist custom.
    • title string
    • content zeichenkette
    • largeIcon boolean (optional) - The large version of the icon should be used. Standard ist true. Maps to NIIF_LARGE_ICON.
    • noSound boolean (optional) - Do not play the associated sound. Standard ist false. Maps to NIIF_NOSOUND.
    • respectQuietTime boolean (optional) - Do not display the balloon notification if the current user is in "quiet time". Standard ist false. Maps to NIIF_RESPECT_QUIET_TIME.

Displays a tray balloon.

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 Menü (optional)
  • position Point (optional) - The pop up position.

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.

Die position ist nur unter Windows verfügbar und ist standardmäßig (0, 0).

tray.closeContextMenu() macOS Windows​

Closes an open context menu, as set by tray.setContextMenu().

tray.setContextMenu(menu)​

  • menu Menu | null

Legt das Kontextmenü für dieses Symbol fest.

tray.getBounds() macOS Windows​

Returns Rectangle

The bounds of this tray icon as Object.

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()​

Returns boolean - Whether the tray icon is destroyed.

Platform considerations​

Linux​

  • Tray icon uses StatusNotifierItem by default, when it is not available in user's desktop environment the GtkStatusIcon will be used instead.
  • 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.
  • In order for changes made to individual MenuItems to take effect, you have to call setContextMenu again. Ein Beispiel:
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' }
  ])

  // Make a change to the context menu
  contextMenu.items[1].checked = false

  // Call this again for Linux because we modified the context menu
  appIcon.setContextMenu(contextMenu)
})

macOS​

  • Icons passed to the Tray constructor should be Template Images.
  • To make sure your icon isn't grainy on retina monitors, be sure your @2x image is 144dpi.
  • If you are bundling your application (e.g., with webpack for development), be sure that the file names are not being mangled or hashed. 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.