Skip to main content

Tray

类：Tray​

¥Class: Tray

将图标和上下文菜单添加到系统的通知区域。

¥Add icons and context menus to the system's notification area.

进程：主进程

¥Process: Main

Tray 是 EventEmitter。

¥Tray is an 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)
})

平台注意事项

¥Platform Considerations

Linux

  • 托盘图标默认使用 状态通知项，当用户桌面环境中不可用时，将使用 GtkStatusIcon。

    ¥Tray icon uses StatusNotifierItem by default, when it is not available in user's desktop environment the GtkStatusIcon will be used instead.

  • 当托盘图标收到用户的激活时，会发出 click 事件，但是 StatusNotifierItem 规范没有指定哪个操作会导致激活，对于某些环境，它是鼠标左键单击，但对于某些环境，它可能是鼠标左键双击。

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

  • 为了使对个别 MenuItem 所做的更改生效，你必须再次调用 setContextMenu。例如：

    ¥In order for changes made to individual MenuItems to take effect, you have to call setContextMenu again. For example:

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

  • 传递给 Tray 构造函数的图标应该是 模板图片。

    ¥Icons passed to the Tray constructor should be Template Images.

  • 为了确保你的图标在视网膜显示器上不出现颗粒状，请确保你的 @2x 图片为 144dpi。

    ¥To make sure your icon isn't grainy on retina monitors, be sure your @2x image is 144dpi.

  • 如果你正在打包应用（例如，使用 webpack 进行开发），请确保文件名没有被破坏或散列。文件名需要以 Template 结尾，并且 @2x 图片需要与标准图片具有相同的文件名，否则 MacOS 将不会神奇地反转图片的颜色或使用高密度图片。

    ¥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) 和 32x32@2x (144dpi) 适用于大多数图标。

    ¥16x16 (72dpi) and 32x32@2x (144dpi) work well for most icons.

Windows

  • 建议使用 ICO 图标以获得最佳视觉效果。

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

new Tray(image, [guid])​

  • image(NativeImage | string)

  • guid 字符串（可选） Windows - 为托盘图标分配 GUID。如果可执行文件已签名并且签名在主题行中包含组织，则 GUID 将与该签名永久关联。即使可执行文件的路径发生变化，操作系统级别的设置（例如系统托盘中托盘图标的位置）也将保留。如果可执行文件未经过代码签名，则 GUID 将永久与可执行文件的路径关联。更改可执行文件的路径将破坏托盘图标的创建，并且必须使用新的 GUID。但是，强烈建议仅将 GUID 参数与代码签名的可执行文件结合使用。如果应用定义了多个托盘图标，则每个图标必须使用单独的 GUID。

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

创建与 image 关联的新托盘图标。

¥Creates a new tray icon associated with the image.

实例事件​

¥Instance Events

Tray 模块发出以下事件：

¥The Tray module emits the following events:

事件：'click'​

¥Event: 'click'

返回：

¥Returns:

单击托盘图标时发出。

¥Emitted when the tray icon is clicked.

请注意，在 Linux 上，当托盘图标收到激活（不一定是鼠标左键单击）时，会发出此事件。

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

事件：'right-click' macOS Windows​

¥Event: 'right-click' macOS Windows

返回：

¥Returns:

右键单击托盘图标时发出。

¥Emitted when the tray icon is right clicked.

事件：'double-click' macOS Windows​

¥Event: 'double-click' macOS Windows

返回：

¥Returns:

双击托盘图标时发出。

¥Emitted when the tray icon is double clicked.

事件：'middle-click' Windows​

¥Event: 'middle-click' Windows

返回：

¥Returns:

单击托盘图标时发出。

¥Emitted when the tray icon is middle clicked.

事件：'balloon-show' Windows​

¥Event: 'balloon-show' Windows

当托盘气球显示时发出。

¥Emitted when the tray balloon shows.

事件：'balloon-click' Windows​

¥Event: 'balloon-click' Windows

单击托盘气球时发出。

¥Emitted when the tray balloon is clicked.

事件：'balloon-closed' Windows​

¥Event: 'balloon-closed' Windows

当托盘气球由于超时或用户手动关闭它而关闭时发出。

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

事件：'drop' macOS​

¥Event: 'drop' macOS

当任何拖动的项目放到托盘图标上时发出。

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

事件：'drop-files' macOS​

¥Event: 'drop-files' macOS

返回：

¥Returns:

  • event 事件

    ¥event Event

  • files 字符串[] - 删除文件的路径。

    ¥files string[] - The paths of the dropped files.

当拖动的文件放入托盘图标时发出。

¥Emitted when dragged files are dropped in the tray icon.

事件：'drop-text' macOS​

¥Event: 'drop-text' macOS

返回：

¥Returns:

  • event 事件

    ¥event Event

  • text 字符串 - 删除的文本字符串。

    ¥text string - the dropped text string.

当拖动的文本放入托盘图标时发出。

¥Emitted when dragged text is dropped in the tray icon.

事件：'drag-enter' macOS​

¥Event: 'drag-enter' macOS

当拖动操作进入托盘图标时发出。

¥Emitted when a drag operation enters the tray icon.

事件：'drag-leave' macOS​

¥Event: 'drag-leave' macOS

当拖动操作退出托盘图标时发出。

¥Emitted when a drag operation exits the tray icon.

事件：'drag-end' macOS​

¥Event: 'drag-end' macOS

当拖动操作在托盘上结束或在另一个位置结束时发出。

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

事件：'mouse-up' macOS​

¥Event: 'mouse-up' macOS

返回：

¥Returns:

当单击托盘图标释放鼠标时发出。

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

注意：如果你使用 tray.setContextMenu 为托盘设置了上下文菜单，由于 macOS 级别的限制，则不会发出此消息。

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

事件：'mouse-down' macOS​

¥Event: 'mouse-down' macOS

返回：

¥Returns:

当鼠标单击托盘图标时发出。

¥Emitted when the mouse clicks the tray icon.

事件：'mouse-enter' macOS Windows​

¥Event: 'mouse-enter' macOS Windows

返回：

¥Returns:

当鼠标进入托盘图标时发出。

¥Emitted when the mouse enters the tray icon.

事件：'mouse-leave' macOS Windows​

¥Event: 'mouse-leave' macOS Windows

返回：

¥Returns:

当鼠标退出托盘图标时发出。

¥Emitted when the mouse exits the tray icon.

事件：'mouse-move' macOS Windows​

¥Event: 'mouse-move' macOS Windows

返回：

¥Returns:

当鼠标在托盘图标中移动时发出。

¥Emitted when the mouse moves in the tray icon.

实例方法​

¥Instance Methods

Tray 类有以下方法：

¥The Tray class has the following methods:

tray.destroy()​

立即销毁托盘图标。

¥Destroys the tray icon immediately.

tray.setImage(image)​

设置与此托盘图标关联的 image。

¥Sets the image associated with this tray icon.

tray.setPressedImage(image) macOS​

设置在 macOS 上按下时与此托盘图标关联的 image。

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

tray.setToolTip(toolTip)​

  • toolTip 字符串

    ¥toolTip string

设置此托盘图标的悬停文本。

¥Sets the hover text for this tray icon.

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

  • title 字符串

    ¥title string

  • options 对象（可选）

    ¥options Object (optional)

    • fontType 字符串（可选） - 要显示的字体系列变体可以是 monospaced 或 monospacedDigit。monospaced 在 macOS 10.15+ 中可用。留空时，标题使用默认系统字体。

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

设置状态栏中托盘图标旁边显示的标题（支持 ANSI 颜色）。

¥Sets the title displayed next to the tray icon in the status bar (Support ANSI colors).

tray.getTitle() macOS​

返回 string - 状态栏中托盘图标旁边显示的标题

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

tray.setIgnoreDoubleClickEvents(ignore) macOS​

  • ignore 布尔值

    ¥ignore boolean

设置忽略双击事件的选项。忽略这些事件可以让你检测到托盘图标的每次单击。

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

该值默认设置为 false。

¥This value is set to false by default.

tray.getIgnoreDoubleClickEvents() macOS​

返回 boolean - 是否忽略双击事件。

¥Returns boolean - Whether double click events will be ignored.

tray.displayBalloon(options) Windows​

  • options 对象

    ¥options Object

    • icon（NativeImage | 字符串）（可选） - 当 iconType 为 custom 时使用的图标。

      ¥icon (NativeImage | string) (optional) - Icon to use when iconType is custom.

    • iconType 字符串（可选） - 可以是 none、info、warning、error 或 custom。默认为 custom。

      ¥iconType string (optional) - Can be none, info, warning, error or custom. Default is custom.

    • title 字符串

      ¥title string

    • content 字符串

      ¥content string

    • largeIcon 布尔值（可选） - 应使用大版本的图标。默认为 true。映射到 NIIF_LARGE_ICON。

      ¥largeIcon boolean (optional) - The large version of the icon should be used. Default is true. Maps to NIIF_LARGE_ICON.

    • noSound 布尔值（可选） - 不播放相关声音。默认为 false。映射到 NIIF_NOSOUND。

      ¥noSound boolean (optional) - Do not play the associated sound. Default is false. Maps to NIIF_NOSOUND.

    • respectQuietTime 布尔值（可选） - 如果当前用户位于 "安静的时光"，则不显示气球通知。默认为 false。映射到 NIIF_RESPECT_QUIET_TIME。

      ¥respectQuietTime boolean (optional) - Do not display the balloon notification if the current user is in "quiet time". Default is false. Maps to NIIF_RESPECT_QUIET_TIME.

显示托盘气球。

¥Displays a tray balloon.

tray.removeBalloon() Windows​

移除托盘气球。

¥Removes a tray balloon.

tray.focus() Windows​

将焦点返回到任务栏通知区域。通知区域图标在完成其 UI 操作后应使用此消息。例如，如果图标显示快捷菜单，但用户按 ESC 键取消它，则使用 tray.focus() 将焦点返回到通知区域。

¥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 Menu (optional)

  • position 观点（可选） - 弹出位置。

    ¥position Point (optional) - The pop up position.

弹出托盘图标的上下文菜单。当 menu 被传递时，将显示 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.

position 仅在 Windows 上可用，默认为 (0, 0)。

¥The position is only available on Windows, and it is (0, 0) by default.

tray.closeContextMenu() macOS Windows​

关闭由 tray.setContextMenu() 设置的打开的上下文菜单。

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

tray.setContextMenu(menu)​

  • menu Menu | null

设置此图标的上下文菜单。

¥Sets the context menu for this icon.

tray.getBounds() macOS Windows​

返回 Rectangle

¥Returns Rectangle

该托盘图标的 bounds 为 Object。

¥The bounds of this tray icon as Object.

tray.isDestroyed()​

返回 boolean - 托盘图标是否被破坏。

¥Returns boolean - Whether the tray icon is destroyed.