托盘

类: 托盘

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

Tray 是一个 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)
})

提示

更多信息: 关于如何实现托盘菜单的详细指南。

警告

Electron 的内置类不能在用户代码中被继承。有关更多信息，请参阅 FAQ。

平台注意事项

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

传递给 Tray 构造函数的图标应该是模板图像。
为了确保您的图标在视网膜显示器上不模糊，请确保您的 @2x 图像是 144dpi。
如果您正在打包您的应用程序（例如，使用 webpack 进行开发），请确保文件名没有被混淆或哈希化。文件名需要以 Template 结尾，并且 @2x 图像需要与标准图像具有相同的名称，否则 MacOS 将无法神奇地反转图像的颜色或使用高密度图像。
16x16 (72dpi) 和 32x32@2x (144dpi) 适用于大多数图标。

Windows

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

`new Tray(image, [guid])`

image (NativeImage | string)
guid string (可选) Windows macOS - 用于标识托盘图标的唯一字符串。必须符合 UUID 格式。

Windows

在 Windows 上，如果可执行文件已签名并且签名的主题行包含组织，则 GUID 将永久与该签名关联。操作系统级别的设置（例如托盘图标在系统托盘中的位置）即使可执行文件的路径发生更改也会保留。如果可执行文件未进行代码签名，则 GUID 将永久与可执行文件的路径关联。更改可执行文件的路径将导致创建托盘图标失败，并且必须使用新的 GUID。但是，强烈建议仅在与代码签名可执行文件一起使用时才使用 GUID 参数。如果应用程序定义了多个托盘图标，则每个图标必须使用单独的 GUID。

macOS

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

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

实例事件

Tray 模块会发出以下事件

事件: 'click'

event KeyboardEvent
bounds Rectangle - 托盘图标的边界。
position Point - 事件的位置。

当托盘图标被点击时发出。

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

事件: 'right-click' macOS Windows

event KeyboardEvent
bounds Rectangle - 托盘图标的边界。

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

事件: 'double-click' macOS Windows

event KeyboardEvent
bounds Rectangle - 托盘图标的边界。

当托盘图标被双击时发出。

事件: 'middle-click' Windows

event KeyboardEvent
bounds Rectangle - 托盘图标的边界。

当托盘图标被中键单击时发出。

事件: 'balloon-show' Windows

当托盘气球显示时发出。

事件: 'balloon-click' Windows

当托盘气球被点击时发出。

事件: 'balloon-closed' Windows

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

事件: 'drop' macOS

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

事件: 'drop-files' macOS

event Event
files string[] - 拖放文件的路径。

当拖动文件被拖放到托盘图标上时发出。

事件: 'drop-text' macOS

event Event
text string - 拖放的文本字符串。

当拖动文本被拖放到托盘图标上时发出。

事件: 'drag-enter' macOS

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

事件: 'drag-leave' macOS

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

事件: 'drag-end' macOS

当拖动操作在托盘上结束或在其他位置结束时发出。

事件: 'mouse-up' macOS

event KeyboardEvent
position Point - 事件的位置。

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

注意

如果您使用 tray.setContextMenu 为您的托盘设置了上下文菜单，则不会发出此事件，这是由于 macOS 级别的限制。

事件: 'mouse-down' macOS

event KeyboardEvent
position Point - 事件的位置。

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

事件: 'mouse-enter' macOS Windows

event KeyboardEvent
position Point - 事件的位置。

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

事件: 'mouse-leave' macOS Windows

event KeyboardEvent
position Point - 事件的位置。

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

事件: 'mouse-move' macOS Windows

event KeyboardEvent
position Point - 事件的位置。

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

实例方法

Tray 类具有以下方法

`tray.destroy()`

立即销毁托盘图标。

`tray.setImage(image)`

image (NativeImage | string)

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

`tray.setPressedImage(image)` macOS

image (NativeImage | string)

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

`tray.setToolTip(toolTip)`

toolTip string

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

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

title string
options Object (可选)
- fontType string (可选) - 要显示的字体系列变体，可以是 monospaced 或 monospacedDigit。monospaced 在 macOS 10.15+ 中可用。留空时，标题使用默认系统字体。

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

`tray.getTitle()` macOS

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

`tray.setIgnoreDoubleClickEvents(ignore)` macOS

ignore boolean

设置忽略双击事件的选项。忽略这些事件允许您检测托盘图标的每次单击。

默认情况下，此值设置为 false。

`tray.getIgnoreDoubleClickEvents()` macOS

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

`tray.displayBalloon(options)` Windows

options Object
- icon (NativeImage | string) (可选) - 当 iconType 为 custom 时使用的图标。
- iconType string (可选) - 可以是 none、info、warning、error 或 custom。默认值为 custom。
- title string
- content string
- largeIcon boolean (可选) - 应该使用图标的大版本。默认值为 true。映射到 NIIF_LARGE_ICON。
- noSound boolean (可选) - 不播放关联的声音。默认值为 false。映射到 NIIF_NOSOUND。
- respectQuietTime boolean (可选) - 如果当前用户处于“静默时间”，则不显示气泡通知。默认值为 false。映射到 NIIF_RESPECT_QUIET_TIME。

显示一个托盘气泡。

`tray.removeBalloon()` Windows

移除一个托盘气泡。

`tray.focus()` Windows

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

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

menu Menu (可选)
position Point (可选) - 弹出位置。

弹出托盘图标的上下文菜单。当传递 menu 时，将显示 menu 而不是托盘图标的上下文菜单。

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

`tray.closeContextMenu()` macOS Windows

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

`tray.setContextMenu(menu)`

menu Menu | null

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

`tray.getBounds()` macOS Windows

返回 Rectangle

此托盘图标的 bounds，为 Object 类型。

`tray.getGUID()` macOS Windows

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

`tray.isDestroyed()`

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

平台注意事项

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

传递给 Tray 构造函数的图标应该是模板图像。
为了确保您的图标在视网膜显示器上不模糊，请确保您的 @2x 图像是 144dpi。
如果您正在打包您的应用程序（例如，使用 webpack 进行开发），请确保文件名没有被混淆或哈希化。文件名需要以 Template 结尾，并且 @2x 图像需要与标准图像具有相同的名称，否则 MacOS 将无法神奇地反转图像的颜色或使用高密度图像。
16x16 (72dpi) 和 32x32@2x (144dpi) 适用于大多数图标。

Windows

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

类: 托盘​

new Tray(image, [guid])​

实例事件​

事件: 'click'​

事件: 'right-click' macOS Windows​

事件: 'double-click' macOS Windows​

事件: 'middle-click' Windows​

事件: 'balloon-show' Windows​

事件: 'balloon-click' Windows​

事件: 'balloon-closed' Windows​

事件: 'drop' macOS​

事件: 'drop-files' macOS​

事件: 'drop-text' macOS​

事件: 'drag-enter' macOS​

事件: 'drag-leave' macOS​

事件: 'drag-end' macOS​

事件: 'mouse-up' macOS​

事件: 'mouse-down' macOS​

事件: 'mouse-enter' macOS Windows​

事件: 'mouse-leave' macOS Windows​

事件: 'mouse-move' macOS Windows​

实例方法​

tray.destroy()​

tray.setImage(image)​

tray.setPressedImage(image) macOS​

tray.setToolTip(toolTip)​

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

tray.getTitle() macOS​

tray.setIgnoreDoubleClickEvents(ignore) macOS​

tray.getIgnoreDoubleClickEvents() macOS​

tray.displayBalloon(options) Windows​

tray.removeBalloon() Windows​

tray.focus() Windows​

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

tray.closeContextMenu() macOS Windows​

tray.setContextMenu(menu)​

tray.getBounds() macOS Windows​

tray.getGUID() macOS Windows​

tray.isDestroyed()​

平台注意事项​

Linux​

macOS​

Windows​