Tray

系统托盘

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

Process: Main

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

[!WARNING] Electron's built-in classes cannot be subclassed in user code. For more information, see the FAQ.

平台注意事项

Linux

• Tray icon uses StatusNotifierItem by default, when it is not available in user's desktop environment the GtkStatusIcon will be used instead.
• The click event is emitted when the tray icon receives activation from user, however the StatusNotifierItem spec does not specify which action would cause an activation, for some environments it is left mouse click, but for some it might be double left mouse click.
• 为了使改变对个别的 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

• Icons passed to the Tray constructor should be Template Images.
• 为了确保您的图标在视网膜监视器不模糊，请确认你的 @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 - The bounds of tray icon.
• position Point - The position of the event.

当该图标被点击时触发。

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

返回:

• event KeyboardEvent
• bounds Rectangle - The bounds of tray icon.

当该图标被右击时触发。

Event: 'double-click' macOS Windows

返回:

• event KeyboardEvent
• bounds Rectangle - The bounds of tray icon.

当该图标被双击时触发。

Event: 'middle-click' Windows

返回:

• event KeyboardEvent
• bounds Rectangle - The bounds of tray icon.

Emitted when the tray icon is middle clicked.

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 - The position of the event.

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

[!NOTE] This will not be emitted if you have set a context menu for your Tray using tray.setContextMenu, as a result of macOS-level constraints.

Event: 'mouse-down' macOS

返回:

• event KeyboardEvent
• position Point - The position of the event.

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

Event: 'mouse-enter' macOS Windows

返回:

• event KeyboardEvent
• position Point - The position of the event.

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

Event: 'mouse-leave' macOS Windows

返回:

• event KeyboardEvent
• position Point - The position of the event.

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

Event: 'mouse-move' macOS Windows

返回:

• event KeyboardEvent
• position Point - The position of the event.

当鼠标在该任务栏图标上移动时，触发该事件。

实例方法

Tray 类拥有以下方法:

tray.destroy()

立即销毁该任务栏图标

tray.setImage(image)

• image (NativeImage | string)

设置image作为托盘中显示的图标

tray.setPressedImage(image) macOS

• image (NativeImage | string)

在 macOS 中，设置image作为托盘图标被按下时显示的图标

tray.setToolTip(toolTip)

• toolTip string

设置鼠标指针在托盘图标上悬停时显示的文本 Setting the text to an empty string will remove the tooltip.

tray.setTitle(title[, options]) macOS

• title string
• options Object (可选)
  • fontType string (可选) - 字体变形显示，可以是 monospaced 或 monospacedDigit。 monospaced is available in macOS 10.15+ When left blank, the title uses the default system font.

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

tray.getTitle() macOS

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

tray.setIgnoreDoubleClickEvents(ignore) macOS

• ignore boolean

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

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

tray.getIgnoreDoubleClickEvents() macOS

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

tray.displayBalloon(options) Windows

• 选项 对象
  • icon (NativeImage | string) (optional) - Icon to use when iconType is 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 (optional) - The pop up position.

弹出托盘图标的右键菜单。 当传入了 menu ，menu 将替代托盘图标的右键菜单显示 。

参数 position 只在 Windows 上可用， 并拥有默认值 (0, 0)。

tray.closeContextMenu() macOS Windows

关闭打开的右键菜单，如 tray.setContextMenu() 那样设置。

tray.setContextMenu(menu)

• menu Menu | null

设置这个图标的内容菜单

tray.getBounds() macOS Windows

Returns Rectangle

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

tray.isDestroyed()

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