Electron Tray API 详解：托盘图标、右键菜单、气泡通知

七十二時_阿川
0 阅读6分钟

Electron Tray API 知识点总结

目录

1. 概述

什么是系统托盘？

系统托盘是位于屏幕底部（Windows/Linux）或顶部菜单栏右侧（macOS）的常驻图标。

┌─────────────────────────────────────────────────────────────┐
│  Windows/Linux                                            │
│  ┌──────┐ ┌──────────────────────────────────────────┐  │
│  │ 📁   │ │ 应用程序区域                               │  │
│  └──────┘ └──────────────────────────────────────────┘  │
│    ↑                                                      │
│  系统托盘                                                 │
├─────────────────────────────────────────────────────────────┤
│  macOS                                                    │
│  ┌──────────────────────────────┐ ┌────┐ ┌────┐           │
│  │     应用程序菜单              │ │ 📁 │ │ 🔊 │  ← 托盘    │
│  └──────────────────────────────┘ └────┘ └────┘           │
└─────────────────────────────────────────────────────────────┘

Tray 模块作用

  • 在系统托盘区域显示图标
  • 提供右键上下文菜单
  • 处理点击事件（单击、双击、右键）
  • 显示气泡通知（Windows）
  • 支持拖拽操作（macOS）

2. 创建托盘

2.1 基本创建

const { app, Tray, Menu } = require('electron')

let tray = null

app.whenReady().then(() => {
  tray = new Tray('/path/to/icon.png')
  
  // 设置提示文本
  tray.setToolTip('我的应用')
  
  // 设置右键菜单
  const contextMenu = Menu.buildFromTemplate([
    { label: '显示窗口', click: () => mainWindow.show() },
    { label: '隐藏窗口', click: () => mainWindow.hide() },
    { type: 'separator' },
    { label: '退出', click: () => app.quit() }
  ])
  
  tray.setContextMenu(contextMenu)
})

2.2 构造函数参数

new Tray(image, [guid])
参数类型说明平台
imageNativeImage/string托盘图标全部
guidstring唯一标识符Windows/macOS

2.3 图标要求

平台推荐格式尺寸要求
WindowsICO16x16, 32x32 等多尺寸
macOSTemplate Image16x16 @1x, 32x32 @2x (144dpi)
LinuxPNG16x16 或 22x22

2.4 macOS 模板图片

const { nativeImage } = require('electron')

// 创建模板图片（白色/透明，适合深色/浅色模式）
const icon = nativeImage.createFromPath('icon.png')
icon.setTemplateImage(true)

const tray = new Tray(icon)

3. 实例事件

3.1 鼠标点击事件

事件触发条件平台
click单击图标全部
right-click右键点击macOS/Windows
double-click双击图标macOS/Windows
middle-click中键点击Windows
tray.on('click', (event, bounds) => {
  // bounds: { x, y, width, height }
  mainWindow.show()
})

tray.on('right-click', (event, bounds) => {
  // 显示自定义菜单
  tray.popUpContextMenu(customMenu)
})

tray.on('double-click', () => {
  // 打开主窗口
  mainWindow.show()
  mainWindow.focus()
})

3.2 鼠标移动事件

事件触发条件平台
mouse-enter鼠标进入图标区域macOS/Windows
mouse-leave鼠标离开图标区域macOS/Windows
mouse-move鼠标在图标上移动macOS/Windows
mouse-down鼠标按下macOS
mouse-up鼠标释放macOS
tray.on('mouse-enter', () => {
  // 显示提示或预览
})

tray.on('mouse-leave', () => {
  // 隐藏预览
})

3.3 拖拽事件 (macOS)

事件触发条件
drop有拖拽项进入图标区域
drop-files文件拖入图标
drop-text文本拖入图标
drag-enter拖拽进入
drag-leave拖拽离开
drag-end拖拽结束
tray.on('drop-files', (event, files) => {
  console.log('拖放的文件:', files)
  files.forEach(file => processFile(file))
})

tray.on('drop-text', (event, text) => {
  console.log('拖放的文本:', text)
})

3.4 气泡通知事件 (Windows)

事件触发条件
balloon-show气泡显示
balloon-click气泡被点击
balloon-closed气泡关闭

4. 实例方法

4.1 图标操作

// 设置图标
tray.setImage(icon)

// macOS：设置按下时的图标
tray.setPressedImage(icon)

// 获取图标是否已销毁
tray.isDestroyed()  // boolean

// 销毁托盘图标
tray.destroy()

4.2 提示文本

// 设置悬停提示
tray.setToolTip('这是我的应用程序')

// 获取提示文本
const tooltip = tray.getToolTip()

4.3 macOS 特有方法

// 设置标题
tray.setTitle('App Name')

// 获取标题
const title = tray.getTitle()

// 忽略双击事件（用于区分单击和双击）
tray.setIgnoreDoubleClickEvents(true)
const isIgnored = tray.getIgnoreDoubleClickEvents()

// 获取托盘边界
const bounds = tray.getBounds()
// bounds: { x: number, y: number, width: number, height: number }

4.4 菜单操作

// 设置右键菜单
tray.setContextMenu(menu)

// 弹出右键菜单
tray.popUpContextMenu([menu, position])

// 关闭右键菜单
tray.closeContextMenu()

4.5 Windows 气泡通知

// 显示气泡通知
tray.displayBalloon({
  iconType: 'info',           // none, info, warning, error, custom
  title: '新消息',
  content: '您有一条新通知',
  largeIcon: true,            // 使用大图标
  noSound: false,             // 不播放声音
  respectQuietTime: false      // 休息时间不显示
})

// 移除气泡
tray.removeBalloon()

// 聚焦到托盘
tray.focus()

5. 托盘菜单

5.1 基本菜单

const contextMenu = Menu.buildFromTemplate([
  { label: '显示主窗口', click: () => showWindow() },
  { label: '设置', click: () => openSettings() },
  { type: 'separator' },
  { label: '关于', click: () => showAbout() },
  { type: 'separator' },
  { label: '退出', click: () => app.quit() }
])

tray.setContextMenu(contextMenu)

5.2 动态菜单

// 创建菜单模板
function buildContextMenu() {
  return Menu.buildFromTemplate([
    {
      label: '通知',
      submenu: [
        { label: '启用通知', type: 'checkbox', checked: true },
        { label: '静默模式', type: 'checkbox', checked: false }
      ]
    },
    { type: 'separator' },
    {
      label: `状态: ${isRunning ? '运行中' : '已停止'}`,
      enabled: false
    },
    { type: 'separator' },
    { label: '退出', click: () => app.quit() }
  ])
}

// Linux 需要重新设置菜单才能生效
tray.setContextMenu(buildContextMenu())

5.3 根据状态动态切换图标

function updateTrayIcon(isActive) {
  const icon = isActive ? 'active.png' : 'inactive.png'
  tray.setImage(icon)
  tray.setToolTip(isActive ? '应用运行中' : '应用已停止')
}

6. 托盘气泡通知

6.1 Windows 气泡通知

// 显示气泡
tray.displayBalloon({
  iconType: 'info',
  title: '下载完成',
  content: '文件已成功下载到 Downloads 文件夹'
})

// 带图标的气泡
tray.displayBalloon({
  icon: path.join(__dirname, 'custom-icon.png'),
  iconType: 'custom',
  title: '自定义通知',
  content: '这是一条自定义通知'
})

6.2 监听气泡事件

tray.on('balloon-click', () => {
  // 点击气泡后打开相关窗口
  mainWindow.show()
  mainWindow.focus()
})

tray.on('balloon-closed', () => {
  console.log('气泡通知已关闭')
})

7. 实际应用示例

7.1 完整的托盘应用

const { app, Tray, Menu, nativeImage, BrowserWindow } = require('electron')

let tray = null
let mainWindow = null

function createTray() {
  // 创建托盘图标
  const icon = nativeImage.createFromPath('icon.png')
  tray = new Tray(icon.resize({ width: 16 }))
  
  // 设置提示
  tray.setToolTip('我的 Electron 应用')
  
  // 创建菜单
  const contextMenu = Menu.buildFromTemplate([
    {
      label: '显示窗口',
      click: () => {
        if (mainWindow) {
          mainWindow.show()
          mainWindow.focus()
        }
      }
    },
    {
      label: '隐藏窗口',
      click: () => {
        if (mainWindow) {
          mainWindow.hide()
        }
      }
    },
    { type: 'separator' },
    {
      label: '运行状态',
      submenu: [
        { label: '● 运行中', type: 'radio', checked: true },
        { label: '○ 已暂停', type: 'radio', checked: false }
      ]
    },
    { type: 'separator' },
    {
      label: '退出',
      click: () => {
        app.quit()
      }
    }
  ])
  
  tray.setContextMenu(contextMenu)
  
  // 点击事件：显示/隐藏窗口
  tray.on('click', () => {
    if (mainWindow) {
      if (mainWindow.isVisible()) {
        mainWindow.hide()
      } else {
        mainWindow.show()
        mainWindow.focus()
      }
    }
  })
  
  // 右键事件：显示菜单
  tray.on('right-click', () => {
    tray.popUpContextMenu(contextMenu)
  })
}

function showNotification(message) {
  // Windows 气泡通知
  if (process.platform === 'win32') {
    tray.displayBalloon({
      iconType: 'info',
      title: '通知',
      content: message
    })
  }
}

// 创建窗口
app.whenReady().then(() => {
  mainWindow = new BrowserWindow()
  mainWindow.loadURL('https://example.com')
  
  createTray()
})

// 关闭窗口时隐藏（不退出应用）
mainWindow.on('close', (event) => {
  if (!app.isQuitting) {
    event.preventDefault()
    mainWindow.hide()
  }
})

// 应用退出时清理
app.on('before-quit', () => {
  app.isQuitting = true
})

7.2 音乐播放器托盘

class MusicPlayerTray {
  constructor(player) {
    this.player = player
    this.tray = null
    this.init()
  }
  
  init() {
    this.tray = new Tray(this.getIcon())
    this.tray.setToolTip('音乐播放器')
    this.updateMenu()
    
    this.tray.on('click', () => this.togglePlay())
  }
  
  getIcon() {
    return this.player.isPlaying ? 'playing.png' : 'paused.png'
  }
  
  updateMenu() {
    const menu = Menu.buildFromTemplate([
      {
        label: this.player.isPlaying ? '⏸ 暂停' : '▶ 播放',
        click: () => this.togglePlay()
      },
      { type: 'separator' },
      {
        label: '上一首',
        click: () => this.player.previous()
      },
      {
        label: '下一首',
        click: () => this.player.next()
      },
      { type: 'separator' },
      {
        label: `正在播放: ${this.player.currentSong}`,
        enabled: false
      },
      { type: 'separator' },
      {
        label: '退出',
        click: () => app.quit()
      }
    ])
    
    this.tray.setContextMenu(menu)
    this.tray.setImage(this.getIcon())
  }
  
  togglePlay() {
    this.player.isPlaying ? this.player.pause() : this.player.play()
    this.updateMenu()
  }
}

7.3 下载管理器托盘

class DownloadManagerTray {
  constructor(downloadManager) {
    this.downloadManager = downloadManager
    this.tray = null
    this.init()
  }
  
  init() {
    this.tray = new Tray('download-icon.png')
    this.updateTray()
    
    // macOS: 拖拽文件下载
    this.tray.on('drop-files', (event, files) => {
      files.forEach(file => this.downloadManager.add(file))
    })
  }
  
  updateTray() {
    const active = this.downloadManager.getActiveDownloads()
    
    // 根据下载数量显示不同提示
    const tooltip = active.length > 0
      ? `正在下载 ${active.length} 个文件`
      : '没有正在下载'
    
    this.tray.setToolTip(tooltip)
    
    // 更新菜单
    const menu = Menu.buildFromTemplate([
      {
        label: `下载中 (${active.length})`,
        submenu: active.map(d => ({
          label: `${d.name} - ${d.progress}%`,
          enabled: false
        }))
      },
      { type: 'separator' },
      {
        label: '全部暂停',
        click: () => this.downloadManager.pauseAll(),
        enabled: active.length > 0
      },
      {
        label: '全部取消',
        click: () => this.downloadManager.cancelAll(),
        enabled: active.length > 0
      },
      { type: 'separator' },
      {
        label: '打开下载文件夹',
        click: () => shell.openPath(app.getPath('downloads'))
      },
      { type: 'separator' },
      {
        label: '退出',
        click: () => app.quit()
      }
    ])
    
    this.tray.setContextMenu(menu)
  }
}

8. 平台差异

8.1 功能支持

功能macOSWindowsLinux
单击事件✅✅⚠️
右键菜单✅✅✅
双击事件✅✅❌
气泡通知❌✅❌
拖拽支持✅❌❌
标题显示✅❌❌
模板图片✅❌❌
GUID 持久化✅✅❌

8.2 图标要求

平台推荐格式尺寸备注
WindowsICO16x16, 32x32多尺寸 ICO 最佳
macOSPNG (模板)16x16 @1x, 32x32 @2x白色透明图
LinuxPNG22x22取决于桌面环境

8.3 macOS 模板图片注意事项

✅ 正确：
   icon.png (16x16)
   icon@2x.png (32x32, 144dpi)
   文件名包含 "Template" 或设置 setTemplateImage(true)

❌ 错误：
   icon-hashed.png (文件名被 webpack 哈希)
   icon@3x.png (不支持的分辨率)

8.4 Linux 特殊处理

// Linux 修改菜单项后需要重新设置
const contextMenu = Menu.buildFromTemplate([...])
tray.setContextMenu(contextMenu)

// 修改某个菜单项
contextMenu.items[0].checked = false

// 必须再次调用才能生效
tray.setContextMenu(contextMenu)

8.5 Windows GUID

// Windows 使用 GUID 保持托盘位置
const tray = new Tray(icon, {
  guid: 'my-app-tray-uuid'  // 建议使用 UUID 格式
})

// macOS 也可以使用 guid
const tray = new Tray(icon, {
  guid: 'my-app-tray-uuid'  // 保持托盘位置
})

最佳实践

✅ 推荐做法

// 1. 应用退出时清理托盘
app.on('before-quit', () => {
  app.isQuitting = true
  if (tray) {
    tray.destroy()
  }
})

// 2. 窗口关闭时隐藏而非退出
mainWindow.on('close', (event) => {
  if (!app.isQuitting) {
    event.preventDefault()
    mainWindow.hide()
  }
})

// 3. 使用原生图片
const icon = nativeImage.createFromPath('icon.png')

// 4. macOS 使用模板图片
icon.setTemplateImage(true)

// 5. 正确处理平台差异
if (process.platform === 'win32') {
  tray.displayBalloon({ ... })
}

❌ 避免做法

// 1. 不要忘记处理窗口关闭事件
mainWindow.on('close', (event) => {
  // 防止用户直接关闭窗口导致应用退出
  event.preventDefault()
  mainWindow.hide()
})

// 2. macOS 不要用彩色图标
// 应该用白色透明图作为模板图片

// 3. 不要忘记销毁托盘
app.on('quit', () => {
  if (tray) {
    tray.destroy()
  }
})

事件速查表

点击事件

click                 单击（全部平台）
right-click           右键（macOS/Windows）
double-click          双击（macOS/Windows）
middle-click          中键（Windows）

鼠标事件

mouse-enter           进入图标区域（macOS/Windows）
mouse-leave           离开图标区域（macOS/Windows）
mouse-move            鼠标移动（macOS/Windows）
mouse-down            鼠标按下（macOS）
mouse-up              鼠标释放（macOS）

拖拽事件 (macOS)

drop                  拖拽进入
drop-files            拖拽文件
drop-text             拖拽文本
drag-enter            拖入
drag-leave            拖出
drag-end              拖拽结束

气泡事件 (Windows)

balloon-show          气泡显示
balloon-click         气泡点击
balloon-closed        气泡关闭

方法速查表

基础

new Tray(image, [guid])    创建托盘
tray.destroy()            销毁托盘
tray.isDestroyed()        检查是否已销毁

外观

tray.setImage(image)              设置图标
tray.setToolTip(text)             设置提示
tray.setTitle(title)              设置标题（macOS）
tray.getTitle()                   获取标题（macOS）

菜单

tray.setContextMenu(menu)         设置右键菜单
tray.popUpContextMenu([menu])    弹出菜单
tray.closeContextMenu()           关闭菜单

气泡 (Windows)

tray.displayBalloon(options)       显示气泡
tray.removeBalloon()              移除气泡
tray.focus()                      聚焦托盘

文档基于 Electron v28+ Tray API 编写

avatar
文章
阅读
粉丝