Tray

类: Tray

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

进程: 主

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

平台注意事项

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 (NativeImage | string)
• guid string (可选) Windows - 为托盘图标分配 GUID。如果可执行文件已签名，并且签名在主题行中包含组织，则 GUID 将永久关联到该签名。即使可执行文件路径发生更改，系统级设置（如系统托盘中托盘图标的位置）也会保留。如果可执行文件未签名，则 GUID 将永久关联到可执行文件路径。更改可执行文件路径将中断托盘图标的创建，必须使用新的 GUID。但是，强烈建议仅在与代码签名可执行文件结合使用时使用 GUID 参数。如果应用程序定义了多个托盘图标，则每个图标都必须使用单独的 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 事件
• files string[] - 放置文件的路径。

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

事件: 'drop-text' macOS

返回值

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

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

tray.getTitle() macOS

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

tray.setIgnoreDoubleClickEvents(ignore) macOS

• ignore 布尔值

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

此值默认设置为 false。

tray.getIgnoreDoubleClickEvents() macOS

返回 布尔值 - 是否会忽略双击事件。

tray.displayBalloon(options) Windows

• options 对象
  • icon (NativeImage | 字符串)（可选） - 当 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.

显示托盘气球。

tray.removeBalloon() Windows

删除托盘气球。

tray.focus() Windows

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

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

• menu 菜单（可选）
• position Point（可选） - 弹出位置。

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

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

tray.closeContextMenu() macOS Windows

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

tray.setContextMenu(menu)

• menu 菜单 | null

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

tray.getBounds() macOS Windows

返回 Rectangle

此托盘图标的 bounds 作为 对象。

tray.isDestroyed()

返回 布尔值 - 托盘图标是否已销毁。