Tray

Class: Tray

Add icons and context menus to the system's notification area.将图标和上下文菜单添加到系统的通知区域。

Process:进程：Main

Tray is an EventEmitter.是一个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)
})

Platform Considerations平台注意事项

If you want to keep exact same behaviors on all platforms, you should not rely on the click event; instead, always attach a context menu to the tray icon.如果你想在所有平台上保持完全相同的行为，你不应该依赖click事件；相反，请始终将上下文菜单附加到任务栏图标。

Linux

• On Linux distributions that only have app indicator support, you have to install libappindicator1 to make the tray icon work.在只支持应用程序指示器的Linux发行版上，必须安装libappindicator1才能使托盘图标工作。
• The app indicator will be used if it is supported, otherwise GtkStatusIcon will be used instead.如果支持，将使用应用程序指示符，否则将使用GtkStatusIcon。
• App indicator will only be shown when it has a context menu.应用程序指示器只有在具有上下文菜单时才会显示。
• The click event is ignored when using the app indicator.使用应用程序指示器时会忽略click事件。
• In order for changes made to individual MenuItems to take effect, you have to call setContextMenu again. 为了使对单个MenuItems所做的更改生效，您必须再次调用setContextMenu。For example:例如：

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.传递给Tray构造函数的图标应该是模板图像。
• To make sure your icon isn't grainy on retina monitors, be sure your @2x image is 144dpi.为了确保你的图标在视网膜监视器上没有颗粒，请确保你的@2x图像是144dpi。
• If you are bundling your application (e.g., with webpack for development), be sure that the file names are not being mangled or hashed. 如果您正在捆绑应用程序（例如，与用于开发的webpack捆绑），请确保文件名没有被篡改或散列。The filename needs to end in Template, and the @2x image needs to have the same filename as the standard image, or MacOS will not magically invert your image's colors or use the high density image.文件名需要以Template结尾，@2x图像需要与标准图像具有相同的文件名，否则MacOS将无法神奇地反转图像的颜色或使用高密度图像。
• 16x16 (72dpi) and 32x32@2x (144dpi) work well for most icons.16x16(72dpi)和32x32@2x(144dpi)适用于大多数图标。

Windows

• It is recommended to use ICO icons to get best visual effects.建议使用ICO图标以获得最佳视觉效果。

new Tray(image, [guid])

• image (NativeImage | string)
• guid string (optional) Windows - Assigns a GUID to the tray icon. 为托盘图标指定GUID。If the executable is signed and the signature contains an organization in the subject line then the GUID is permanently associated with that signature. 如果对可执行文件进行了签名，并且签名在主题行中包含一个组织，则GUID将与该签名永久关联。OS level settings like the position of the tray icon in the system tray will persist even if the path to the executable changes. 即使可执行文件的路径发生更改，操作系统级别的设置（如任务栏图标在系统任务栏中的位置）也将保持不变。If the executable is not code-signed then the GUID is permanently associated with the path to the executable. 如果可执行文件不是代码签名的，则GUID与可执行文件的路径永久关联。Changing the path to the executable will break the creation of the tray icon and a new GUID must be used. 更改可执行文件的路径将中断托盘图标的创建，并且必须使用新的GUID。However, it is highly recommended to use the GUID parameter only in conjunction with code-signed executable. 但是，强烈建议仅将GUID参数与代码签名的可执行文件结合使用。If an App defines multiple tray icons then each icon must use a separate GUID.如果一个应用程序定义了多个托盘图标，那么每个图标都必须使用一个单独的GUID。

Creates a new tray icon associated with the image.创建与image关联的新托盘图标。

Instance Events实例事件

The Tray module emits the following events:Tray模块发出以下事件：

Event: 'click'

Returns:返回：

• event KeyboardEvent
• bounds Rectangle - The bounds of tray icon.托盘图标的边界。
• position Point - The position of the event.事件的位置。

Emitted when the tray icon is clicked.单击托盘图标时发出。

Event: 'right-click' macOS Windows

Returns:返回：

• event KeyboardEvent
• bounds Rectangle - The bounds of tray icon.托盘图标的边界。

Emitted when the tray icon is right clicked.右键单击托盘图标时发出。

Event: 'double-click' macOS Windows

Returns:返回：

• event KeyboardEvent
• bounds Rectangle - The bounds of tray icon.托盘图标的边界。

Emitted when the tray icon is double clicked.双击托盘图标时发出。

Event: 'balloon-show' Windows

Emitted when the tray balloon shows.当托盘引出序号显示时发出。

Event: 'balloon-click' Windows

Emitted when the tray balloon is clicked.单击托盘引出序号时发出。

Event: 'balloon-closed' Windows

Emitted when the tray balloon is closed because of timeout or user manually closes it.当托盘引出序号因超时而关闭或用户手动关闭时发出。

Event: 'drop' macOS

Emitted when any dragged items are dropped on the tray icon.当任何拖动的项目都放在托盘图标上时发出。

Event: 'drop-files' macOS

Returns:返回：

• event Event
• files string[] - The paths of the dropped files.删除的文件的路径。

Emitted when dragged files are dropped in the tray icon.当拖动的文件被放入托盘图标时发出。

Event: 'drop-text' macOS

Returns:返回：

• event Event
• text string - the dropped text string.删除的文本字符串。

Emitted when dragged text is dropped in the tray icon.当拖动的文本被放入任务栏图标时发出。

Event: 'drag-enter' macOS

Emitted when a drag operation enters the tray icon.当拖动操作进入托盘图标时发出。

Event: 'drag-leave' macOS

Emitted when a drag operation exits the tray icon.当拖动操作退出托盘图标时发出。

Event: 'drag-end' macOS

Emitted when a drag operation ends on the tray or ends at another location.当拖动操作在托盘上结束或在其他位置结束时发出。

Event: 'mouse-up' macOS

Returns:返回：

• event KeyboardEvent
• position Point - The position of the event.事件的位置。

Emitted when the mouse is released from clicking the tray icon.当鼠标从托盘图标上松开时发出。

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.注意：由于macOS级别的限制，如果您使用tray.setContextMenu为托盘设置了上下文菜单，则不会发出此消息。

Event: 'mouse-down' macOS

Returns:返回：

• event KeyboardEvent
• position Point - The position of the event.事件的位置。

Emitted when the mouse clicks the tray icon.当鼠标单击托盘图标时发出。

Event: 'mouse-enter' macOS

Returns:返回：

• event KeyboardEvent
• position Point - The position of the event.事件的位置。

Emitted when the mouse enters the tray icon.当鼠标进入托盘图标时发出。

Event: 'mouse-leave' macOS

Returns:返回：

• event KeyboardEvent
• position Point - The position of the event.事件的位置。

Emitted when the mouse exits the tray icon.当鼠标退出托盘图标时发出。

Event: 'mouse-move' macOS Windows

Returns:返回：

• event KeyboardEvent
• position Point - The position of the event.事件的位置。

Emitted when the mouse moves in the tray icon.当鼠标在托盘图标中移动时发出。

Instance Methods实例方法

The Tray class has the following methods:Tray类具有以下方法：

tray.destroy()

Destroys the tray icon immediately.立即销毁托盘图标。

tray.setImage(image)

• image (NativeImage | string)

Sets the image associated with this tray icon.设置与此托盘图标关联的image。

tray.setPressedImage(image) macOS

• image (NativeImage | string)

Sets the image associated with this tray icon when pressed on macOS.设置在macOS上按下时与此托盘图标关联的image。

tray.setToolTip(toolTip)

• toolTip string

Sets the hover text for this tray icon.设置此任务栏图标的悬停文本。

tray.setTitle(title[, options]) macOS

• title string
• options Object (optional)
  • fontType string (optional) - The font family variant to display, can be monospaced or monospacedDigit. 要显示的字体系列变体可以是monospaced或monospacedDigit。monospaced is available in macOS 10.15+ and monospacedDigit is available in macOS 10.11+. monospaced可在macOS 10.15+中使用，monospacedDigit可在macOS10.11+中使用。When left blank, the title uses the default system font.保留为空时，标题将使用默认的系统字体。

Sets the title displayed next to the tray icon in the status bar (Support ANSI colors).设置状态栏中托盘图标旁边显示的标题（支持ANSI颜色）。

tray.getTitle() macOS

Returns返回string - the title displayed next to the tray icon in the status bar状态栏中托盘图标旁边显示的标题

tray.setIgnoreDoubleClickEvents(ignore) macOS

• ignore boolean

Sets the option to ignore double click events. 设置忽略双击事件的选项。Ignoring these events allows you to detect every individual click of the tray icon.忽略这些事件可以检测托盘图标的每一次单击。

This value is set to false by default.默认情况下，此值设置为false。

tray.getIgnoreDoubleClickEvents() macOS

Returns返回boolean - Whether double click events will be ignored.是否会忽略双击事件。

tray.displayBalloon(options) Windows

• options Object
  • icon (NativeImage | string) (optional) - Icon to use when iconType is custom.当iconType为custom时要使用的图标。
  • iconType string (optional) - Can be none, info, warning, error or custom. 可以是none、info、warning、error或custom。Default is custom.默认为custom。
  • title string
  • content string
  • largeIcon boolean (optional) - The large version of the icon should be used. Default is true. 应该使用大版本的图标。默认值为true。Maps to NIIF_LARGE_ICON.映射到NIIF_LARGE_ICON。
  • noSound boolean (optional) - Do not play the associated sound. 不要播放相关的声音。Default is false. 默认值为false。Maps to NIIF_NOSOUND.映射到NIIF_NOSOUND。
  • respectQuietTime boolean (optional) - Do not display the balloon notification if the current user is in "quiet time". 如果当前用户处于“安静时间”，则不要显示气球通知。Default is false. 默认值为false。Maps to NIIF_RESPECT_QUIET_TIME.映射到NIIF_RESPECT_QUIET_TIME。

Displays a tray balloon.显示托盘引出序号。

tray.removeBalloon() Windows

Removes a tray balloon.删除托盘引出序号。

tray.focus() Windows

Returns focus to the taskbar notification area. 将焦点返回到任务栏通知区域。Notification area icons should use this message when they have completed their UI operation. 通知区域图标在完成UI操作后应使用此消息。For example, if the icon displays a shortcut menu, but the user presses ESC to cancel it, use tray.focus() to return focus to the notification area.例如，如果图标显示快捷菜单，但用户按ESC键取消，请使用tray.focus()将焦点返回到通知区域。

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

• menu Menu (optional)
• position Point (optional) - The pop up position.弹出位置。

Pops up the context menu of the tray icon. 弹出托盘图标的上下文菜单。When menu is passed, the menu will be shown instead of the tray icon's context menu.传递菜单时，将显示菜单，而不是托盘图标的上下文菜单。

The position is only available on Windows, and it is (0, 0) by default.该position仅在Windows上可用，默认情况下为(0, 0)。

tray.closeContextMenu() macOS Windows

Closes an open context menu, as set by tray.setContextMenu().按照tray.setContextMenu()的设置，关闭打开的上下文菜单。

tray.setContextMenu(menu)

• menu Menu | null

Sets the context menu for this icon.设置此图标的上下文菜单。

tray.getBounds() macOS Windows

Returns 返回Rectangle

The bounds of this tray icon as Object.此托盘图标作为Object的bounds。

tray.isDestroyed()

Returns返回boolean - Whether the tray icon is destroyed.托盘图标是否已损坏。