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上，如果支持，就使用应用程序指示器，否则将使用GtkStatusIcon。
• 在仅支持应用程序指标的Linux发行版中，必须安装libappindicator1才能使任务栏图标正常工作。
• 应用程序指标只有当它有一个上下文菜单时才会显示。
• 当在Linux上使用应用程序指标时，它的 click事件将被忽略
• 在 Linux 上，为了使对 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)
})

• 在 Windows 上, 建议使用 ICO 图标来获得最佳视觉效果。

如果要在所有平台上保持完全相同的行为, 则不应依赖 click 事件, 并且始终将上下文菜单附加到任务栏图标。

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 - 事件的位置信息。

当该图标被点击时触发。

Event: 'right-click' macOS Windows

返回:

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

当该图标被右击时触发。

Event: 'double-click' macOS Windows

返回:

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

当该图标被双击时触发。

Event: 'balloon-show' Windows

当系统托盘图标气泡显示时，触发该事件。

Event: 'balloon-click' Windows

当系统托盘气泡被点击时，触发该事件。

Event: 'balloon-closed' Windows

当系统托盘气泡因为超时被关闭或者用户手动关闭时，触发该事件。

Event: 'drop' macOS

当有任何拖动项拖到该任务栏图标上时，触发该事件。

Event: 'drop-files' macOS

返回:

• event Event
• files string[] - 拖至任务栏图标上的文件的路径。

当有任何文件被拖到该任务栏图标上时，触发该事件。

Event: 'drop-text' macOS

返回:

• event Event
• text string - 拖至任务栏图标上的文字内容。

当有任何文字被拖到该任务栏图标上时，触发该事件。

Event: 'drag-enter' macOS

当有任何拖动操作进入（拖动未结束）该任务栏图标时，触发该事件。

Event: 'drag-leave' macOS

当有任何拖动操作离开该任务栏图标时，触发该事件。

Event: 'drag-end' macOS

当有任何拖动操作在托盘或其他地方结束时，触发该事件。

Event: 'mouse-up' macOS

返回:

• event KeyboardEvent
• position Point - 事件的位置信息。

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

注意：如果您使用 tray.setContextMenu 为托盘设置了右键菜单，则不会触发此事件，这是由于 macOS-level 的约束。

Event: 'mouse-down' macOS

返回:

• event KeyboardEvent
• position Point - 事件的位置信息。

鼠标点击托盘图标时触发。

Event: 'mouse-enter' macOS

返回:

• event KeyboardEvent
• position Point - 事件的位置信息。

当鼠标进入该任务栏图标时，触发该事件。

Event: 'mouse-leave' macOS

返回:

• event KeyboardEvent
• position Point - 事件的位置信息。

当鼠标离开该任务栏图标时，触发该事件。

Event: '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+ 中可用， monospacedDigit 在 macOS 10.11+ 中可用。 当为空时，标题使用默认系统字体。

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

tray.getTitle() macOS

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

tray.setIgnoreDoubleClickEvents(ignore) macOS

• ignore boolean

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

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

tray.getIgnoreDoubleClickEvents() macOS

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

tray.displayBalloon(options) Windows

• 选项 对象
  • 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

以Object类型返回托盘图标的bounds

tray.isDestroyed()

返回 boolean -判断托盘图标是否被销毁