当前位置：首页 > news >正文

Electron鸿蒙PC上的系统托盘，坑比我想象的多三倍

news 2026/5/16 2:10:38

Electron鸿蒙PC上的系统托盘，坑比我想象的多三倍

上个月我在做一个企业内部工具，需要在鸿蒙PC上实现系统托盘常驻和原生通知推送。本来以为这是个小功能，两三个小时搞定，结果愣是折腾了两天半。把过程记录下来，希望后来人少走弯路。

先说结论：Electron托盘在鸿蒙上的兼容性现状

老实说，截止我写这篇文章，Electron的TrayAPI在鸿蒙PC（HarmonyOS NEXT，PC版本）上的行为和在Windows、macOS上差异不小。官方适配文档这块写得很薄，基本靠自己试。

核心差异有这么几点：

托盘图标的显示区域走的是状态栏右侧系统图标区，和Windows任务栏托盘概念接近，但Z轴层级管理完全不同。我第一次实现时，托盘菜单弹出来之后点击无效，查了半天才发现是焦点管理的问题——鸿蒙的窗口焦点调度和Electron的预设不太一样。

原生通知方面，鸿蒙PC走的是NotificationCenter而不是Win32的WinAPI通知，Electron底层调的是平台原生接口，这里有个关键细节文档上没说清楚：鸿蒙PC需要应用具备ohos.permission.NOTIFICATION_CONTROLLER权限，否则通知静默失败，不报错，就是没动静。我反复试了五六次，以为是代码写错了，最后去翻鸿蒙开发者文档才找到这个权限描述，当时真是一言难尽。

系统托盘：从零开始

先讲托盘图标的基础实现，再说鸿蒙上特有的问题。

// main/tray.jsconst{app,Tray,Menu,nativeImage,BrowserWindow}=require('electron');constpath=require('path');lettray=null;functioncreateTray(mainWindow){// 鸿蒙上建议使用 PNG，SVG支持不稳定consticonPath=path.join(__dirname,'../assets/tray-icon.png');consticon=nativeImage.createFromPath(iconPath);// 鸿蒙PC上托盘图标推荐尺寸：32x32，过大会被裁剪tray=newTray(icon.resize({width:32,height:32}));constcontextMenu=Menu.buildFromTemplate([{label:'显示主窗口',click:()=>{if(mainWindow){mainWindow.show();mainWindow.focus();}}},{type:'separator'},{label:'退出',click:()=>{app.quit();}}]);tray.setToolTip('我的应用');tray.setContextMenu(contextMenu);// 双击托盘图标显示窗口tray.on('double-click',()=>{if(mainWindow){mainWindow.show();}});returntray;}module.exports={createTray};

这段代码在Windows上跑得很顺，但放到鸿蒙PC上，double-click事件根本不触发。排查了很久，发现鸿蒙PC的触控板默认手势和鼠标双击在Electron底层的事件映射有出入。改成监听click然后自己做防抖处理才解决：

// 鸿蒙PC兼容写法：用click + 防抖代替double-clickletlastClickTime=0;tray.on('click',()=>{constnow=Date.now();if(now-lastClickTime<500){// 双击逻辑if(mainWindow){mainWindow.show();mainWindow.focus();}}lastClickTime=now;});

说白了就是手动实现双击判断，有点蠢但能用。

托盘菜单弹出后焦点失控的问题

这个坑花了我最多时间。现象是：点击托盘图标，菜单弹出，点菜单项——没反应。不是事件没触发，而是窗口焦点跑了，菜单的点击事件被吞掉了。

根本原因是：鸿蒙PC的窗口管理器在处理托盘菜单弹出时，会先把当前焦点窗口置为非活跃状态，然后菜单作为一个浮层窗口接管焦点。但Electron在鸿蒙上的菜单浮层有时候拿不到焦点，点击就自然没反应了。

解决方案是在菜单显示前后手动管理焦点：

// 修复鸿蒙PC托盘菜单焦点问题tray.on('right-click',(event,bounds)=>{// 临时创建一个透明的焦点窗口来承接菜单交互constfocusWindow=newBrowserWindow({width:1,height:1,x:bounds.x,y:bounds.y,transparent:true,frame:false,alwaysOnTop:true,skipTaskbar:true,show:false,webPreferences:{nodeIntegration:false}});focusWindow.show();focusWindow.focus();tray.popUpContextMenu();focusWindow.on('blur',()=>{focusWindow.close();});});

这个方案是我在Electron GitHub Issues上翻到的一个workaround，原本是给Linux用的，拿到鸿蒙上居然也管用。官方后续版本应该会修，但现在只能先这么处理。

原生通知：权限是第一道坎

说回通知。Electron的Notification模块在鸿蒙上调用方式和桌面端一样：

const{Notification}=require('electron');functionsendNotification(title,body){if(Notification.isSupported()){constnotification=newNotification({title:title,body:body,// 鸿蒙PC上icon字段影响通知中心显示的应用图标icon:path.join(__dirname,'../assets/app-icon.png')});notification.on('click',()=>{console.log('用户点击了通知');// 唤起主窗口if(mainWindow){mainWindow.show();mainWindow.focus();}});notification.show();}}

代码本身没问题，但就是发不出去。isSupported()返回true，show()也不报错，但通知中心里什么都没有。

后来翻鸿蒙文档才发现，打包鸿蒙应用时需要在module.json5里声明通知权限：

{"module":{"requestPermissions":[{"name":"ohos.permission.NOTIFICATION_CONTROLLER","reason":"$string:permission_reason","usedScene":{"abilities":["EntryAbility"],"when":"always"}}]}}

光声明还不够，运行时还要动态申请（鸿蒙NEXT的权限模型是这样的）。如果你的Electron应用通过鸿蒙桌面适配层跑，这个权限申请逻辑要在原生层做，不能直接在Electron里调——这玩意儿绕了一大圈，文档上没有完整的例子。

我最后的方案是在应用启动时，通过ipcMain触发原生层（HAP壳）的权限申请，拿到授权后再启用通知功能：

// main/notification.jsconst{ipcMain,Notification}=require('electron');letnotificationEnabled=false;// 监听原生层的权限结果回调ipcMain.on('notification-permission-result',(event,granted)=>{notificationEnabled=granted;console.log('通知权限状态:',granted?'已获取':'被拒绝');});// 安全的通知发送函数functionsendNotificationSafe(title,body,options={}){if(!notificationEnabled){console.warn('通知权限未获取，跳过发送');return;}constnotification=newNotification({title,body,silent:options.silent||false,timeoutType:options.timeoutType||'default',...options});notification.show();returnnotification;}module.exports={sendNotificationSafe};

通知点击跳转：还有一个小坑

通知点击之后如果要跳转到应用内某个页面，我个人推荐把路由信息塞在通知的data字段里（虽然Electron的Notification API没有标准的data属性，但可以用闭包捕获）：

functioncreateRouteNotification(title,body,route){constnotification=newNotification({title,body});notification.on('click',()=>{if(mainWindow){mainWindow.show();mainWindow.focus();// 通过webContents向渲染进程发送路由跳转指令mainWindow.webContents.send('navigate-to',route);}});notification.show();}// 渲染进程接收const{ipcRenderer}=require('electron');ipcRenderer.on('navigate-to',(event,route)=>{router.push(route);// Vue Router 或 React Router});

这个方案比较稳，鸿蒙PC上测试没问题。

一个实用技巧：托盘图标动态更新

这个算是奇技淫巧了。如果你需要在托盘图标上显示消息数量（类似未读消息红点），鸿蒙PC上没有badge API，只能手动画图标：

const{nativeImage}=require('electron');const{createCanvas}=require('canvas');// 需要安装 canvas 包functioncreateBadgeIcon(count){constsize=32;constcanvas=createCanvas(size,size);constctx=canvas.getContext('2d');// 画基础图标（用你的应用图标）// ctx.drawImage(baseIcon, 0, 0, size, size);if(count>0){// 画红色圆点constbadgeSize=12;ctx.beginPath();ctx.arc(size-badgeSize/2,badgeSize/2,badgeSize/2,0,Math.PI*2);ctx.fillStyle='#FF4444';ctx.fill();// 画数字ctx.fillStyle='#FFFFFF';ctx.font='bold 8px Arial';ctx.textAlign='center';ctx.textBaseline='middle';constlabel=count>99?'99+':String(count);ctx.fillText(label,size-badgeSize/2,badgeSize/2);}constbuffer=canvas.toBuffer('image/png');returnnativeImage.createFromBuffer(buffer);}// 使用functionupdateTrayBadge(count){if(tray){tray.setImage(createBadgeIcon(count));}}