名称: electron-tray-menu-builder description: 为Electron应用程序生成系统托盘和上下文菜单配置。此技能处理跨Windows、macOS和Linux的平台特定图标要求、菜单模板创建和托盘事件处理。允许使用的工具: Read, Write, Edit, Bash, Glob, Grep tags: [electron, tray, menu, system-tray, desktop]

electron-tray-menu-builder

为Electron应用程序生成系统托盘和上下文菜单配置。此技能处理跨Windows、macOS和Linux的平台特定图标要求、菜单模板创建和托盘事件处理。

能力

生成具有正确生命周期的Tray类实现
创建平台特定的图标集（ICO, ICNS, PNG）
构建带有子菜单和分隔符的菜单模板
处理点击事件（单击、双击、右键单击）
实现工具提示和气泡通知
支持动态菜单更新
处理托盘图标状态变化（正常、活动、高亮）
为菜单项生成TypeScript类型

输入模式

{
  "type": "object",
  "properties": {
    "projectPath": {
      "type": "string",
      "description": "Electron项目根目录的路径"
    },
    "menuStructure": {
      "type": "array",
      "description": "菜单项定义",
      "items": {
        "type": "object",
        "properties": {
          "label": { "type": "string" },
          "type": { "enum": ["normal", "separator", "submenu", "checkbox", "radio"] },
          "accelerator": { "type": "string" },
          "enabled": { "type": "boolean" },
          "visible": { "type": "boolean" },
          "click": { "type": "string", "description": "处理函数名称" },
          "submenu": { "type": "array" }
        }
      }
    },
    "iconPaths": {
      "type": "object",
      "properties": {
        "default": { "type": "string" },
        "pressed": { "type": "string" },
        "highlighted": { "type": "string" }
      }
    },
    "features": {
      "type": "array",
      "items": {
        "enum": ["tooltip", "balloon", "click-handler", "double-click", "context-menu", "dynamic-update"]
      }
    },
    "targetPlatforms": {
      "type": "array",
      "items": { "enum": ["win32", "darwin", "linux"] }
    }
  },
  "required": ["projectPath", "menuStructure"]
}

输出模式

{
  "type": "object",
  "properties": {
    "success": { "type": "boolean" },
    "files": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "description": { "type": "string" }
        }
      }
    },
    "iconRequirements": {
      "type": "object",
      "description": "每个平台所需的图标文件"
    },
    "warnings": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["success"]
}

平台注意事项

Windows

图标格式: ICO (16x16, 32x32, 48x48, 256x256)
支持气泡通知
双击显示主窗口（惯例）
托盘图标常驻系统托盘

macOS

图标格式: PNG (16x16, 32x32 @1x 和 @2x)
必须是模板图像以支持深色/浅色模式
使用菜单栏（非系统托盘）
pressedImage用于点击状态
无气泡通知（使用通知中心）

Linux

图标格式: PNG（各种尺寸）
行为因桌面环境而异
推荐支持AppIndicator
可能需要libappindicator

生成代码示例

// tray-manager.js
const { app, Tray, Menu, nativeImage } = require('electron');
const path = require('path');

class TrayManager {
  constructor(mainWindow) {
    this.mainWindow = mainWindow;
    this.tray = null;
  }

  create() {
    const iconPath = this.getIconPath();
    this.tray = new Tray(iconPath);

    this.tray.setToolTip('我的应用程序');
    this.tray.setContextMenu(this.buildMenu());

    // 平台特定行为
    if (process.platform === 'win32') {
      this.tray.on('double-click', () => this.showWindow());
    } else if (process.platform === 'darwin') {
      this.tray.on('click', () => this.toggleWindow());
    }
  }

  getIconPath() {
    const iconName = process.platform === 'win32'
      ? 'tray.ico'
      : process.platform === 'darwin'
        ? 'trayTemplate.png'  // macOS的模板图像
        : 'tray.png';
    return path.join(__dirname, '../assets/icons', iconName);
  }

  buildMenu() {
    const template = [
      {
        label: '显示应用',
        click: () => this.showWindow()
      },
      { type: 'separator' },
      {
        label: '状态',
        submenu: [
          { label: '在线', type: 'radio', checked: true },
          { label: '离开', type: 'radio' },
          { label: '忙碌', type: 'radio' }
        ]
      },
      { type: 'separator' },
      {
        label: '退出',
        accelerator: process.platform === 'darwin' ? 'Cmd+Q' : 'Ctrl+Q',
        click: () => app.quit()
      }
    ];

    return Menu.buildFromTemplate(template);
  }

  showWindow() {
    if (this.mainWindow) {
      this.mainWindow.show();
      this.mainWindow.focus();
    }
  }

  toggleWindow() {
    if (this.mainWindow.isVisible()) {
      this.mainWindow.hide();
    } else {
      this.showWindow();
    }
  }

  updateMenu(newTemplate) {
    this.tray.setContextMenu(Menu.buildFromTemplate(newTemplate));
  }

  setIcon(iconPath) {
    this.tray.setImage(iconPath);
  }

  destroy() {
    if (this.tray) {
      this.tray.destroy();
      this.tray = null;
    }
  }
}

module.exports = TrayManager;

图标要求

模板图像（macOS）

// 用于macOS深色/浅色模式支持
const icon = nativeImage.createFromPath('trayTemplate.png');
icon.setTemplateImage(true);

多分辨率图标

assets/icons/
├── tray.ico           # Windows（多分辨率）
├── trayTemplate.png   # macOS @1x (16x16 或 22x22)
├── trayTemplate@2x.png # macOS @2x
├── tray.png           # Linux (24x24 或 22x22)
└── tray-active.png    # 状态变体

最佳实践

在macOS上使用模板图像：自动适应深色/浅色模式
提供多种分辨率：支持高DPI显示器
处理托盘销毁：在应用退出时清理
最小化托盘更新：批量更新菜单以避免闪烁
遵循平台惯例：Windows上双击，macOS上单击
在所有平台上测试：行为差异显著

Electron系统托盘菜单构建器 electron-tray-menu-builder

electron-tray-menu-builder

能力

输入模式

输出模式

平台注意事项

Windows

macOS

Linux

生成代码示例

图标要求

模板图像（macOS）

多分辨率图标

最佳实践

相关技能

相关代理