Electron鸿蒙PC上的系统托盘坑比我想象的多三倍上个月我在做一个企业内部工具需要在鸿蒙PC上实现系统托盘常驻和原生通知推送。本来以为这是个小功能两三个小时搞定结果愣是折腾了两天半。把过程记录下来希望后来人少走弯路。先说结论Electron托盘在鸿蒙上的兼容性现状老实说截止我写这篇文章Electron的TrayAPI在鸿蒙PCHarmonyOS NEXTPC版本上的行为和在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);constpathrequire(path);lettraynull;functioncreateTray(mainWindow){// 鸿蒙上建议使用 PNGSVG支持不稳定consticonPathpath.join(__dirname,../assets/tray-icon.png);consticonnativeImage.createFromPath(iconPath);// 鸿蒙PC上托盘图标推荐尺寸32x32过大会被裁剪traynewTray(icon.resize({width:32,height:32}));constcontextMenuMenu.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-clickletlastClickTime0;tray.on(click,(){constnowDate.now();if(now-lastClickTime500){// 双击逻辑if(mainWindow){mainWindow.show();mainWindow.focus();}}lastClickTimenow;});说白了就是手动实现双击判断有点蠢但能用。托盘菜单弹出后焦点失控的问题这个坑花了我最多时间。现象是点击托盘图标菜单弹出点菜单项——没反应。不是事件没触发而是窗口焦点跑了菜单的点击事件被吞掉了。根本原因是鸿蒙PC的窗口管理器在处理托盘菜单弹出时会先把当前焦点窗口置为非活跃状态然后菜单作为一个浮层窗口接管焦点。但Electron在鸿蒙上的菜单浮层有时候拿不到焦点点击就自然没反应了。解决方案是在菜单显示前后手动管理焦点// 修复鸿蒙PC托盘菜单焦点问题tray.on(right-click,(event,bounds){// 临时创建一个透明的焦点窗口来承接菜单交互constfocusWindownewBrowserWindow({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()){constnotificationnewNotification({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()返回trueshow()也不报错但通知中心里什么都没有。后来翻鸿蒙文档才发现打包鸿蒙应用时需要在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);letnotificationEnabledfalse;// 监听原生层的权限结果回调ipcMain.on(notification-permission-result,(event,granted){notificationEnabledgranted;console.log(通知权限状态:,granted?已获取:被拒绝);});// 安全的通知发送函数functionsendNotificationSafe(title,body,options{}){if(!notificationEnabled){console.warn(通知权限未获取跳过发送);return;}constnotificationnewNotification({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){constnotificationnewNotification({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){constsize32;constcanvascreateCanvas(size,size);constctxcanvas.getContext(2d);// 画基础图标用你的应用图标// ctx.drawImage(baseIcon, 0, 0, size, size);if(count0){// 画红色圆点constbadgeSize12;ctx.beginPath();ctx.arc(size-badgeSize/2,badgeSize/2,badgeSize/2,0,Math.PI*2);ctx.fillStyle#FF4444;ctx.fill();// 画数字ctx.fillStyle#FFFFFF;ctx.fontbold 8px Arial;ctx.textAligncenter;ctx.textBaselinemiddle;constlabelcount99?99:String(count);ctx.fillText(label,size-badgeSize/2,badgeSize/2);}constbuffercanvas.toBuffer(image/png);returnnativeImage.createFromBuffer(buffer);}// 使用functionupdateTrayBadge(count){if(tray){tray.setImage(createBadgeIcon(count));}}canvas这个npm包需要额外安装在鸿蒙PC的Electron环境里编译可能要多折腾一下原生模块的构建工具链但整体是可行的。小结做这个功能之前我以为托盘和通知是随手就能实现的边角功能没想到在鸿蒙PC上各有各的坑。我个人建议如果你的应用要上鸿蒙PC并且用到了系统级UI托盘、通知、文件选择器这类提前留出至少两倍的调试时间。鸿蒙PC适配Electron的路径目前还不算成熟很多问题只能靠翻issues和试错解决。权限问题一定要优先排查很多功能没效果的问题根源是权限没申请到而不是代码逻辑有误。版权声明本文遵循 MIT License 协议。欢迎转载转载请注明原文链接及作者信息。未经授权不得将本文用于商业用途。
Electron鸿蒙PC上的系统托盘，坑比我想象的多三倍
Electron鸿蒙PC上的系统托盘坑比我想象的多三倍上个月我在做一个企业内部工具需要在鸿蒙PC上实现系统托盘常驻和原生通知推送。本来以为这是个小功能两三个小时搞定结果愣是折腾了两天半。把过程记录下来希望后来人少走弯路。先说结论Electron托盘在鸿蒙上的兼容性现状老实说截止我写这篇文章Electron的TrayAPI在鸿蒙PCHarmonyOS NEXTPC版本上的行为和在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);constpathrequire(path);lettraynull;functioncreateTray(mainWindow){// 鸿蒙上建议使用 PNGSVG支持不稳定consticonPathpath.join(__dirname,../assets/tray-icon.png);consticonnativeImage.createFromPath(iconPath);// 鸿蒙PC上托盘图标推荐尺寸32x32过大会被裁剪traynewTray(icon.resize({width:32,height:32}));constcontextMenuMenu.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-clickletlastClickTime0;tray.on(click,(){constnowDate.now();if(now-lastClickTime500){// 双击逻辑if(mainWindow){mainWindow.show();mainWindow.focus();}}lastClickTimenow;});说白了就是手动实现双击判断有点蠢但能用。托盘菜单弹出后焦点失控的问题这个坑花了我最多时间。现象是点击托盘图标菜单弹出点菜单项——没反应。不是事件没触发而是窗口焦点跑了菜单的点击事件被吞掉了。根本原因是鸿蒙PC的窗口管理器在处理托盘菜单弹出时会先把当前焦点窗口置为非活跃状态然后菜单作为一个浮层窗口接管焦点。但Electron在鸿蒙上的菜单浮层有时候拿不到焦点点击就自然没反应了。解决方案是在菜单显示前后手动管理焦点// 修复鸿蒙PC托盘菜单焦点问题tray.on(right-click,(event,bounds){// 临时创建一个透明的焦点窗口来承接菜单交互constfocusWindownewBrowserWindow({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()){constnotificationnewNotification({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()返回trueshow()也不报错但通知中心里什么都没有。后来翻鸿蒙文档才发现打包鸿蒙应用时需要在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);letnotificationEnabledfalse;// 监听原生层的权限结果回调ipcMain.on(notification-permission-result,(event,granted){notificationEnabledgranted;console.log(通知权限状态:,granted?已获取:被拒绝);});// 安全的通知发送函数functionsendNotificationSafe(title,body,options{}){if(!notificationEnabled){console.warn(通知权限未获取跳过发送);return;}constnotificationnewNotification({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){constnotificationnewNotification({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){constsize32;constcanvascreateCanvas(size,size);constctxcanvas.getContext(2d);// 画基础图标用你的应用图标// ctx.drawImage(baseIcon, 0, 0, size, size);if(count0){// 画红色圆点constbadgeSize12;ctx.beginPath();ctx.arc(size-badgeSize/2,badgeSize/2,badgeSize/2,0,Math.PI*2);ctx.fillStyle#FF4444;ctx.fill();// 画数字ctx.fillStyle#FFFFFF;ctx.fontbold 8px Arial;ctx.textAligncenter;ctx.textBaselinemiddle;constlabelcount99?99:String(count);ctx.fillText(label,size-badgeSize/2,badgeSize/2);}constbuffercanvas.toBuffer(image/png);returnnativeImage.createFromBuffer(buffer);}// 使用functionupdateTrayBadge(count){if(tray){tray.setImage(createBadgeIcon(count));}}canvas这个npm包需要额外安装在鸿蒙PC的Electron环境里编译可能要多折腾一下原生模块的构建工具链但整体是可行的。小结做这个功能之前我以为托盘和通知是随手就能实现的边角功能没想到在鸿蒙PC上各有各的坑。我个人建议如果你的应用要上鸿蒙PC并且用到了系统级UI托盘、通知、文件选择器这类提前留出至少两倍的调试时间。鸿蒙PC适配Electron的路径目前还不算成熟很多问题只能靠翻issues和试错解决。权限问题一定要优先排查很多功能没效果的问题根源是权限没申请到而不是代码逻辑有误。版权声明本文遵循 MIT License 协议。欢迎转载转载请注明原文链接及作者信息。未经授权不得将本文用于商业用途。
