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

• 传递给 Tray 构造函数的图标应为模板图像。
• 为确保您的图标在视网膜显示器上不出现颗粒感，请确保您的 @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 参数。如果一个 App 定义了多个系统托盘图标，则每个图标必须使用单独的 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 而非系统托盘图标的上下文菜单。

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

tray.closeContextMenu() macOS Windows

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

tray.setContextMenu(menu)

• menu Menu | null

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

tray.getBounds() macOS Windows

返回 Rectangle

此系统托盘图标的 bounds (以 Object 形式)。

tray.isDestroyed()

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