Tray

类：Tray

🌐 Class: Tray

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

进程：主进程

🌐 Process: Main

Tray 是一个 事件触发器。

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

另请参阅：关于如何实现托盘菜单的详细指南。

warning

Electron 内置的类不能在用户代码中被继承。 欲了解更多信息，请参见 常见问题。

平台考虑因素

Linux

• 托盘图标默认使用 StatusNotifierItem，当用户的桌面环境中不可用时，将改用 GtkStatusIcon。
• click 事件在托盘图标受到用户激活时触发，然而 StatusNotifierItem 规范并未指定哪种操作会导致激活，对于某些环境来说是左键单击，但在某些环境中可能是双击左键。
• 为了使对各个 MenuItem 所做的更改生效，你必须再次调用 setContextMenu。例如：

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

• 传递给托盘构造函数的图标应该是模板图片。
• 为了确保你的图标在视网膜显示器上不会出现颗粒感，请确保你的 @2x 图片为 144dpi。
• 如果你正在打包你的应用（例如，使用 webpack 进行开发），请确保文件名没有被混淆或哈希。文件名需要以 Template 结尾，并且 @2x 图片的文件名需要与标准图片相同，否则 MacOS 不会自动反转你的图片颜色或使用高分辨率图片。
• 16x16 (72dpi) 和 32x32@2x (144dpi) 适用于大多数图标。

Windows（视窗）

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

new Tray(image, [guid])

• image (本地图片 | 字符串)
• guid 字符串（可选） Windows macOS - 用于识别托盘图标的唯一字符串。必须符合 UUID 格式。

Windows（视窗）

在 Windows 系统上，如果可执行文件已签名，并且签名中主题行包含组织信息，那么 GUID 将永久与该签名关联。操作系统级的设置，例如系统托盘中图标的位置，即使可执行文件的路径发生变化，也会保留。如果可执行文件未签名，则 GUID 将永久与可执行文件的路径关联。更改可执行文件的路径将导致托盘图标无法创建，必须使用新的 GUID。然而，强烈建议仅在可执行文件已签名的情况下使用 GUID 参数。如果一个应用定义了多个托盘图标，则每个图标必须使用不同的 GUID。

🌐 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

在 macOS 上，guid 是一个用于唯一标识托盘图标的字符串，并允许它在重新启动之间保持其位置。对新的托盘项目使用相同的字符串将使其在与之前的托盘项目相同的位置创建，以使用该字符串。

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

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

🌐 Creates a new tray icon associated with the image.

实例事件

🌐 Instance Events

Tray 模块会触发以下事件：

🌐 The Tray module emits the following events:

Event: 'click'

返回：

🌐 Returns:

• event 键盘事件
• bounds 矩形 - 托盘图标的边界。
• position 点 - 事件的位置。

单击托盘图标时发出。

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

Event: 'right-click' macOS Windows

返回：

🌐 Returns:

• event 键盘事件
• bounds 矩形 - 托盘图标的边界。

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

🌐 Emitted when the tray icon is right clicked.

Event: 'double-click' macOS Windows

返回：

🌐 Returns:

• event 键盘事件
• bounds 矩形 - 托盘图标的边界。

双击托盘图标时发出。

🌐 Emitted when the tray icon is double clicked.

Event: 'middle-click' Windows

返回：

🌐 Returns:

• event 键盘事件
• bounds 矩形 - 托盘图标的边界。

单击托盘图标时发出。

🌐 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

返回：

🌐 Returns:

• event 活动
• files string[] - 拖放文件的路径。

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

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

Event: 'drop-text' macOS

返回：

🌐 Returns:

• event 活动
• text 字符串 - 被丢弃的文本字符串。

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

🌐 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

返回：

🌐 Returns:

• event 键盘事件
• position 点 - 事件的位置。

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

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

note

如果你使用 tray.setContextMenu 为托盘设置了上下文菜单，由于 macOS 的限制，这将不会被触发。

Event: 'mouse-down' macOS

返回：

🌐 Returns:

• event 键盘事件
• position 点 - 事件的位置。

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

🌐 Emitted when the mouse clicks the tray icon.

Event: 'mouse-enter' macOS Windows

返回：

🌐 Returns:

• event 键盘事件
• position 点 - 事件的位置。

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

🌐 Emitted when the mouse enters the tray icon.

Event: 'mouse-leave' macOS Windows

返回：

🌐 Returns:

• event 键盘事件
• position 点 - 事件的位置。

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

🌐 Emitted when the mouse exits the tray icon.

Event: 'mouse-move' macOS Windows

返回：

🌐 Returns:

• event 键盘事件
• position 点 - 事件的位置。

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

🌐 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 (本地图片 | 字符串)

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

🌐 Sets the image associated with this tray icon.

tray.setPressedImage(image) macOS

• image (本地图片 | 字符串)

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

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

tray.setToolTip(toolTip)

• toolTip 字符串

设置此托盘图标的悬停文本。将文本设置为空字符串将移除工具提示。

🌐 Sets the hover text for this tray icon. Setting the text to an empty string will remove the tooltip.

tray.setTitle(title[, options]) macOS

• title 字符串
• options 对象（可选）
  • fontType 字符串（可选）- 要显示的字体系列变体，可以是 monospaced 或 monospacedDigit。monospaced 在 macOS 10.15 及以上版本可用。如果留空，标题将使用系统默认字体。

设置状态栏中托盘图标旁边显示的标题（支持 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 布尔值

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

🌐 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 对象
  • icon (NativeImage | string)（可选）- 当 iconType 为 custom 时使用的图标。
  • iconType 字符串（可选）- 可以是 none、info、warning、error 或 custom。默认值是 custom。
  • title 字符串
  • content 字符串
  • largeIcon 布尔值（可选）- 应使用图标的大版本。默认值为 true。映射到 NIIF_LARGE_ICON。
  • noSound 布尔值（可选）- 不播放关联的声音。默认值为 false。对应 NIIF_NOSOUND。
  • respectQuietTime 布尔值（可选）- 如果当前用户处于“静音时间”，则不显示气泡通知。默认值为 false。对应 NIIF_RESPECT_QUIET_TIME。

显示托盘气球。

🌐 Displays a tray balloon.

tray.removeBalloon() Windows

移除托盘气球。

🌐 Removes a tray balloon.

tray.focus() Windows

将焦点返回到任务栏通知区域。通知区域图标在完成其用户界面操作后应使用此消息。例如，如果图标显示快捷菜单，但用户按下 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 菜单（可选）
• 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 菜单 | 空

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

🌐 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.getGUID() macOS Windows

返回 string | null - 用于唯一标识托盘图标并允许其在重新启动之间保留位置的 GUID，如果未设置则返回 null。

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

返回 boolean - 托盘图标是否已被销毁。

🌐 Returns boolean - Whether the tray icon is destroyed.

平台注意事项

🌐 Platform considerations

Linux

• 托盘图标默认使用 StatusNotifierItem，当用户的桌面环境中不可用时，将改用 GtkStatusIcon。
• click 事件在托盘图标受到用户激活时触发，然而 StatusNotifierItem 规范并未指定哪种操作会导致激活，对于某些环境来说是左键单击，但在某些环境中可能是双击左键。
• 为了使对各个 MenuItem 所做的更改生效，你必须再次调用 setContextMenu。例如：

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

• 传递给托盘构造函数的图标应该是模板图片。
• 为了确保你的图标在视网膜显示器上不会出现颗粒感，请确保你的 @2x 图片为 144dpi。
• 如果你正在打包你的应用（例如，使用 webpack 进行开发），请确保文件名没有被混淆或哈希。文件名需要以 Template 结尾，并且 @2x 图片的文件名需要与标准图片相同，否则 MacOS 不会自动反转你的图片颜色或使用高分辨率图片。
• 16x16 (72dpi) 和 32x32@2x (144dpi) 适用于大多数图标。

Windows

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