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 构造函数的图标应该是 模板图像。
- 为了确保您的图标在 retina 显示器上不显得颗粒感,请确保您的
@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
KeyboardEventbounds
Rectangle - 托盘图标的边界。position
Point - 事件的位置。
当托盘图标被单击时发出。
请注意,在 Linux 上,当托盘图标收到激活时会发出此事件,这不一定是鼠标左键单击。
事件:'right-click' macOS Windows
返回值
event
KeyboardEventbounds
Rectangle - 托盘图标的边界。
当托盘图标被右键单击时发出。
事件:'double-click' macOS Windows
返回值
event
KeyboardEventbounds
Rectangle - 托盘图标的边界。
当托盘图标被双击时发出。
事件:'middle-click' Windows
返回值
event
KeyboardEventbounds
Rectangle - 托盘图标的边界。
当托盘图标被鼠标中键单击时发出。
事件:'balloon-show' Windows
当托盘气泡显示时发出。
事件:'balloon-click' Windows
当托盘气泡被单击时发出。
事件:'balloon-closed' Windows
当托盘气泡因超时或用户手动关闭而关闭时发出。
事件:'drop' macOS
当任何拖动的项目被放到托盘图标上时发出。
事件:'drop-files' macOS
返回值
event
Eventfiles
string[] - 拖放文件的路径。
当拖放文件到托盘图标中时发出。
事件:'drop-text' macOS
返回值
event
Eventtext
string - 拖放的文本字符串。
当拖放文本到托盘图标中时发出。
事件:'drag-enter' macOS
当拖动操作进入托盘图标时发出。
事件:'drag-leave' macOS
当拖动操作退出托盘图标时发出。
事件:'drag-end' macOS
当拖动操作在托盘上结束或在另一个位置结束时发出。
事件:'mouse-up' macOS
返回值
event
KeyboardEventposition
Point - 事件的位置。
当鼠标从单击托盘图标释放时发出。
注意:如果您使用 tray.setContextMenu
为您的 Tray 设置了上下文菜单,则不会发出此事件,这是由于 macOS 级别的约束。
事件:'mouse-down' macOS
返回值
event
KeyboardEventposition
Point - 事件的位置。
当鼠标单击托盘图标时发出。
事件:'mouse-enter' macOS Windows
返回值
event
KeyboardEventposition
Point - 事件的位置。
当鼠标进入托盘图标时发出。
事件:'mouse-leave' macOS Windows
返回值
event
KeyboardEventposition
Point - 事件的位置。
当鼠标退出托盘图标时发出。
事件:'mouse-move' macOS Windows
返回值
event
KeyboardEventposition
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
设置显示在状态栏中托盘图标旁边的标题(支持 ANSI 颜色)。
tray.getTitle()
macOS
返回 string
- 显示在状态栏中托盘图标旁边的标题
tray.setIgnoreDoubleClickEvents(ignore)
macOS
ignore
boolean
设置忽略双击事件的选项。忽略这些事件允许您检测托盘图标的每次单独点击。
此值默认设置为 false。
tray.getIgnoreDoubleClickEvents()
macOS
返回 boolean
- 是否将忽略双击事件。
tray.displayBalloon(options)
Windows
显示一个托盘气泡。
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
- 托盘图标是否被销毁。