在鸿蒙 PC 上用 Electron 做一款「碰哪传哪」的应用:TapRipple 触涟的跨平台框架全链路实战
在鸿蒙 PC 上用 Electron 做一款「碰哪传哪」的应用:TapRipple 触涟的跨平台框架全链路实战
欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
基于 Electron 的鸿蒙化适配项目地址:https://atomgit.com/CPF-Electron/Electron
前言
鸿蒙 PC 这台机器有一个很实际的问题摆在每个开发者面前:桌面端已经有一套成熟的 Web 技术栈,而在鸿蒙 PC 上重新学一遍 ArkUI 声明式开发,成本并不低。于是「跨平台框架能不能直接跑在鸿蒙 PC 上」就成了一个必须亲手验证的问题。本文记录的就是这个验证过程的结果——一款完整的鸿蒙 PC 应用 TapRipple(触涟),用 Electron 这套跨平台框架写成,最终以 HAP 的形式安装到鸿蒙 PC 真机上,截图里那台机器的 Dock、窗口圆角、系统菜单区都是鸿蒙 PC 自己的。
TapRipple 做的事情很具体:把 HarmonyOS 7 升级后的「碰一碰」能力,做成一张可视化的工作台。左边是手机托盘,放着你准备分享的四类内容;中间是碰一碰台,摆着四扇目标窗口(图纸板、文稿台、影像墙、纪要板);右边是信号日志,每一次投递都留痕。手机轻触屏幕时系统会给出触点坐标,触涟就把这个坐标当作投递目的地——碰图纸就挂到最近的测量标注点上,碰正文就插到光标旁边,碰影像墙空白就落格追加,碰纪要板就把语音转写落到最新一行。一句话概括产品主张:碰哪传哪。(触点在应用内的产生方式与接入边界,见第六节。)
这个词在鸿蒙 PC 上的意义和手机上不太一样。手机屏幕小,碰一碰多半是「传过去就行」;鸿蒙 PC 屏幕大、窗口多、一个窗口里还有多个可落点,触点的坐标本身就携带了「传给谁、给到哪个位置」的完整意图。这也是我选择用 Electron 而不是纯 ArkTS 写它的原因:整条投递链路的核心是一套几何计算与状态机,用 JavaScript 写成纯函数,既能被渲染层调用,也能被 node:test 直接跑单元测试,改一次算法两边同时生效。

关键词:鸿蒙 PC、Electron、跨平台框架、碰一碰精准分享、触点命中、HAP 打包上屏、AtomGit
一、跨平台框架在鸿蒙 PC 上的真实运行形态
先把最容易误解的一点说清楚:在用 Electron 开发鸿蒙 PC 应用时,你 npm install electron 拿到的那份标准二进制是跑不起来的。OpenHarmony 上没有对应的官方 Electron 二进制,Chromium 与 Node 的运行时是以 libelectron.so 的形式,作为一个原生库躺在 HAP 壳工程里的。所以正确的心智模型是这样三层:
- 业务层:
app/目录里的main.js、preload.js、renderer.mjs、index.html,这部分是标准的 Electron 代码,你在 Windows 上写的写法基本都能照搬; - 壳层:官方提供的
ohos_hap预编译工程,里面有AppScope、electron模块、web_engine模块,以及libs/arm64-v8a/libelectron.so和libadapter.so; - 打包层:hvigor 把壳层和你同步进去的业务代码一起打成
electron-default-signed.hap,再用hdc install推到鸿蒙 PC 上。
这套形态带来三个直接后果,后面每一节都会碰到:
process.platform在鸿蒙 PC 上返回的不是win32/darwin/linux,实测是openharmony,也见过ohos,两个都得认;- 窗口的首屏尺寸不由
BrowserWindow的width/height决定,而是由 HAP 壳module.json5里的ohos.ability.window.*metadata 决定,你在主进程里写 1560×980,系统还是会按壳工程的声明开窗; - 鸿蒙 PC 的窗口本身自带一条系统菜单区,应用内如果再挂一条 Electron 菜单,就会叠成两层。
之所以仍然选这个跨平台框架,是因为收益很实在:整个工程 零 npm 依赖,package.json 里没有 dependencies 也没有 devDependencies,视觉、交互、动画全部用原生 DOM + CSS 完成,构建产物就是几个纯文本文件,同步进 HAP 只花几十毫秒。鸿蒙 PC 上的安装包体积主要由官方的 libelectron.so 贡献,业务代码那点体积几乎可以忽略。
二、工程骨架:把「业务」和「壳」彻底分开
触涟的目录结构是刻意设计的,目的是让业务代码永远不感知壳工程的存在:
TapRipple/
├── app/ 业务层:主进程 + 预加载 + 渲染层 + 纯函数引擎
│ ├── main.js 主进程:开窗、IPC、安全策略
│ ├── main-utils.cjs 主进程工具:URL 白名单、触点坐标夹取
│ ├── preload.js 受限桥:只暴露两个方法
│ ├── index.html 三栏工作台结构
│ ├── styles.css 深海信号波视觉
│ ├── renderer.mjs 渲染层:交互与动画
│ └── tapshare.mjs 纯函数引擎:命中、吸附、投递、涟漪
├── scripts/ 构建流水线:check / doctor / hap-init / sync / build / install / start
├── tests/ node:test 单测(引擎 + 主进程工具)
├── hap/ 官方 ohos_hap 壳(由 hap:init 生成,不入库)
├── hap.config.json 包名 / 模块名 / SDK 分支集中配置
└── dist/ 浏览器预览产物
壳工程不进仓库,靠一条命令从官方交付物复制出来,同时把包名改成本工程的:
{
"bundleName": "com.nexaport.app",
"moduleName": "electron",
"abilityName": "EntryAbility",
"productName": "default",
"sdkBranch": "v40.0.1",
"runtimeDirectory": "web_engine/src/main/resources/resfile/resources",
"hmosCltHome": "/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0"
}
runtimeDirectory 是业务代码的落点。同步脚本把 app/ 整个目录拷到 hap/web_engine/src/main/resources/resfile/resources/app/,libelectron.so 启动时就从这里读 package.json 的 main 字段,找到 main.js 开跑。官方桥接文件、Chromium 资源、两个 .so 一律不动——这是保证「壳升级时业务代码不用改」的关键。
还有个小细节值得单独说:hap:init 会顺手检查源工程的 build-profile.json5 里有没有 signingConfigs,有就拒绝初始化。因为签名材料和包名是绑定的,一旦把别人机器上的口令带进仓库,后面所有人构建都会撞签名错误。
三、主进程:鸿蒙 PC 窗口的两个硬约束
主进程在鸿蒙 PC 上的职责和在其他平台上差不多:开窗、注册 IPC、卡住导航和权限。区别在于两处鸿蒙 PC 特有的处理,我直接标在代码里了:
'use strict';
const path = require('node:path');
const { app, BrowserWindow, ipcMain, Menu, session } = require('electron');
const { clampTouchPoint, getRuntimeInfo, isTrustedUrl } = require('./main-utils.cjs');
const indexPath = path.join(__dirname, 'index.html');
let mainWindow = null;
// 鸿蒙 PC 上 platform 实测返回 'openharmony',也见过 'ohos',两个都要认
const isOhos = process.platform === 'ohos' || process.platform === 'openharmony';
app.setName('TapRipple');
function createWindow() {
mainWindow = new BrowserWindow({
title: 'TapRipple · 触涟',
width: 1560,
height: 980,
minWidth: 720,
minHeight: 560,
backgroundColor: '#06141d',
show: false,
webPreferences: {
preload: path.join(__dirname, 'preload.js'),
contextIsolation: true,
nodeIntegration: false,
sandbox: false,
webSecurity: true,
allowRunningInsecureContent: false
}
});
mainWindow.once('ready-to-show', () => mainWindow?.show());
mainWindow.on('closed', () => { mainWindow = null; });
mainWindow.loadFile(indexPath);
}
app.on('web-contents-created', (_event, contents) => {
contents.setWindowOpenHandler(() => ({ action: 'deny' }));
contents.on('will-navigate', (event, navigationUrl) => {
if (!isTrustedUrl(navigationUrl, indexPath)) {
event.preventDefault();
}
});
});
app.whenReady().then(() => {
session.defaultSession.setPermissionRequestHandler((_w, _p, callback) => callback(false));
ipcMain.handle('runtime:get', (event) => {
assertTrustedSender(event);
return getRuntimeInfo(app, process);
});
// 碰一碰触点校准:渲染层把屏幕触点送来夹取,防止越界坐标进入投递链
ipcMain.handle('touch:calibrate', (event, point) => {
assertTrustedSender(event);
const clamped = clampTouchPoint(point);
return { ok: Boolean(clamped), point: clamped };
});
// 鸿蒙 PC 窗口自带系统菜单区,应用内菜单必须置空,否则叠成两层
Menu.setApplicationMenu(null);
createWindow();
});
app.on('window-all-closed', () => app.quit());
这里有两个约束值得展开。第一是 Menu.setApplicationMenu(null)。在 Windows 或 macOS 上,你不管菜单也只是「少一条菜单栏」;在鸿蒙 PC 上,系统给每个窗口都画了一条菜单区,应用内再注册一条,视觉上就会变成两条高度不同的菜单叠在一起,非常难看。这不是审美问题,是必须处理的平台差异。
第二是平台判定。isOhos 这个布尔值把「两个可能的 platform 值」收敛到一处,将来要做平台分支就只改这一行;界面上真正显示的文案来自 runtime:get 返回的 platform 字段——是 openharmony 或 ohos,右上角胶囊写「鸿蒙 PC」,否则写「浏览器预览」。这样同一份代码既能装进 HAP 跑在鸿蒙 PC 上,也能双击 index.html 在浏览器里做 UI 调参,两种形态共享同一套渲染层。
assertTrustedSender 和 isTrustedUrl 属于安全基线,判断的是「这个 IPC 消息是不是来自我们自己的那个文件页」,前者只是后者的一个薄封装:
function assertTrustedSender(event) {
if (!isTrustedUrl(event.senderFrame?.url, indexPath)) {
throw new Error('Untrusted IPC sender');
}
main-utils.cjs 里的实现只有两件小事,但两件都在鸿蒙 PC 上真的踩过:
'use strict';
const { pathToFileURL } = require('node:url');
const TOUCH_LIMITS = { maxX: 4096, maxY: 4096 };
function isTrustedUrl(candidate, indexPath) {
if (!candidate) return false;
try {
const url = new URL(candidate);
const trusted = pathToFileURL(indexPath);
return url.protocol === 'file:' && url.origin === trusted.origin
&& url.pathname === trusted.pathname;
} catch {
return false;
}
}
// 触点坐标夹取:碰一碰上报的坐标必须落在有效屏幕区域内
function clampTouchPoint(point, limits = TOUCH_LIMITS) {
const x = Math.round(Number(point?.x));
const y = Math.round(Number(point?.y));
if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
if (x < 0 || y < 0 || x > limits.maxX || y > limits.maxY) return null;
return { x, y };
}
module.exports = { TOUCH_LIMITS, clampTouchPoint, getRuntimeInfo, isTrustedUrl };
clampTouchPoint 看起来只是防御性代码,但在鸿蒙 PC 上它解决的是真实问题:碰一碰的触点在系统层是屏幕绝对坐标,而我的画布是相对坐标,一旦窗口位置变化或者坐标上报异常,hitTest 会拿着一个几千的 x 去和几百宽的矩形比距离,结果是「最近目标」永远落在最右边那扇窗口上,用户碰到左边也会投到右边。夹取一次,越界直接判定无效,反而让落空判断变得诚实。
四、预加载:一条只开两个口的桥
跨平台框架的渲染层安全,说到底就是「不要给它 Node」。触涟的 preload.js 不到十行,暴露两个能力,一个读、一个算:
'use strict';
const { contextBridge, ipcRenderer } = require('electron');
contextBridge.exposeInMainWorld('tapripple', {
getRuntime: () => ipcRenderer.invoke('runtime:get'),
calibrateTouch: (point) => ipcRenderer.invoke('touch:calibrate')
});
关键是 calibrateTouch 只能传一个坐标对象,返回值也只能是 { ok, point }。渲染层拿不到 require、拿不到 fs、拿不到任意 IPC 通道名,所以即使某天有人往 index.html 里注入了一段脚本,它能做的极限也就是「提交一个坐标」。配合 index.html 里那条 CSP:
<meta http-equiv="Content-Security-Policy"
content="default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; object-src 'none'" />
script-src 'self' 挡住了内联脚本与远程脚本,object-src 'none' 挡掉了插件通道,connect-src 没有放开,所以这个鸿蒙 PC 应用在运行时没有任何出网能力。对于一款分享类应用来说这是加分项——碰一碰的语义本来就是「本机两台设备之间的定向投递」,不该有第三个方向的流量。
五、纯函数引擎:把「碰哪传哪」拆成四个可测的步骤
整套交互的核心在 tapshare.mjs,它不 import 任何 DOM、不 import 任何 Electron API,全是纯函数。这样做有三个好处:渲染层和单元测试共用同一份语义;算法可以离线复现;将来如果把投递逻辑搬进主进程,一行都不用改。
第一步是命中判定。四扇窗口在画布里各有自己的矩形,触点进来先算它离哪扇窗口的中心最近,同时记录「是否真的落在矩形内部」:
export function hitTest(targets, point) {
if (!Array.isArray(targets) || targets.length === 0 || !point) return null;
let best = null;
for (const target of targets) {
const rect = target.rect;
if (!rect) continue;
const within = point.x >= rect.x && point.x <= rect.x + rect.width
&& point.y >= rect.y && point.y <= rect.y + rect.height;
const cx = rect.x + rect.width / 2;
const cy = rect.y + rect.height / 2;
const distance = Math.hypot(point.x - cx, point.y - cy);
if (!best || distance < best.distance) {
best = { target, within, distance, center: { x: cx, y: cy } };
}
}
return best;
}
注意这里 hitTest 永远返回「最近的那扇窗口」,而不是「落在窗口里的那扇」。这是故意的:涟漪的落点视觉上必须有一个参照物,哪怕碰在窗口之间的缝隙里,也要能画出「你离图纸板最近」的提示。真正的成败由调用方看 within 决定,within === false 就是落空,涟漪变珊瑚色,日志记一条「未触到任何窗口」,累计流量不增加。这个分离让「落空」成为一次有明确语义的事件,而不是一次静默的失败。
第二步是锚点吸附。图纸板上预置了三个测量标注点,触点在 72px 内会吸附到最近的那个:
export function snapAnchor(anchors, point, maxDistance = 72) {
if (!Array.isArray(anchors) || anchors.length === 0 || !point) return null;
let best = null;
for (const anchor of anchors) {
const distance = Math.hypot(point.x - anchor.x, point.y - anchor.y);
if (!best || distance < best.distance) best = { anchor, distance };
}
if (!best || best.distance > maxDistance) return null;
return best;
}
maxDistance 是这套交互的手感旋钮。设太大,用户碰在图纸中间也会挂到某个角落的标注点上,「精准」就失真;设太小,用户很难真正碰到锚点。72px 是在 1560×980 的窗口、三栏布局下试出来的值——大于一根手指的容差,小于相邻两个标注点间距的一半。
第三步是投递策略矩阵。内容有四类、目标有四个,共 16 种组合,每种组合决定「用什么方式落地」以及给用户看什么文案:
export function resolveDelivery(contentKind, targetKind) {
const row = DELIVERY_MATRIX[contentKind];
if (!row || !row[targetKind]) {
return { mode: 'rejected', label: '该目标暂不接收此类内容' };
}
return row[targetKind];
}
export function deliverySpeedMB(payloadMB, mode) {
const size = Number(payloadMB);
if (!Number.isFinite(size) || size < 0) return 0;
const rates = {
'cursor-drop': 86, 'anchor-mount': 64,
'grid-append': 58, 'transcript-insert': 42, rejected: 0
};
const rate = rates[mode] ?? 50;
return Math.round(size * rate * 10) / 10;
}
四种落地方式分别对应「文字光标直达」「锚点挂载」「落格追加」「转写落行」。速率分档不是为了炫技,而是给用户一个可比较的心理预期:光标直达最快(86 MB/s 档),转写落行最慢(42 MB/s 档),因为后者在语义上要多做一次语音转文字。截图里侧栏那个「分享速率预估」进度条读的就是这个函数——选中 4.2 MB 的现场照片时显示 361.2 MB/s,选中 0.3 MB 的图表数据时显示 25.8 MB/s,数值能被手算验证,用户就不会觉得这是一个随机的装饰。
六、视觉层:涟漪、飞行卡片与「看得见的落空」
产品叫「触涟」,视觉的锚点自然是涟漪。碰一碰发生在触屏上,用户在鸿蒙 PC 上用鼠标点击是模拟这个动作,所以需要有一样东西告诉他「刚才那一下被记录到了哪个坐标」。
这里要先交代一条边界,免得读代码时误解:当前版本没有绑定系统层的碰一碰回调,触点坐标由画布上的指针事件产生,再经 touch:calibrate 送进主进程夹取。但坐标一旦拿到手,后面的命中判定、锚点吸附、投递策略、涟漪时序全部走同一条链,与真机上报坐标时完全一致——将来接系统回调,只需替换坐标来源,算法层一行都不用动。这种「把不确定的上游隔离成一个入口」的写法,是这套跨平台框架在鸿蒙 PC 上做桌面交互时最实用的一条经验。
三圈涟漪是最直观的答案:
// t 归一化 0..1,返回三圈涟漪的半径比例与透明度
export function ripplePhases(t) {
const time = Math.min(Math.max(Number(t) || 0, 0), 1);
const rings = [];
for (let i = 0; i < 3; i += 1) {
const local = Math.min(Math.max((time - i * 0.18) / 0.64, 0), 1);
rings.push({
scale: 0.16 + local * 1.84,
alpha: local > 0 ? Math.max(0, 1 - local) * (1 - i * 0.22) : 0
});
}
return rings;
}
三圈各自延迟 0.18 个时间单位起跑,用 0.64 个时间单位扩散到 2 倍尺寸,透明度线性衰减,第三圈的峰值透明度只有第一圈的 56%。这几个常数加起来的效果是:涟漪从触点向外扩散时,外侧圈永远比内侧圈更淡,视觉上像水面被石头砸了一下,而不是一个同心圆在闪烁。整个动画用一个 requestAnimationFrame 循环驱动 980ms,结束后 DOM 节点自己摘掉,不会在鸿蒙 PC 上堆积节点——这一点在长时间使用的桌面应用里很重要。
内容是沿着二次贝塞尔曲线飞到触点上的,控制点被抬高了,所以卡片走的是抛物线而不是直线:
export function driftPath(from, to, t) {
const time = Math.min(Math.max(Number(t) || 0, 0), 1);
if (!from || !to) return null;
const control = {
x: (from.x + to.x) / 2,
y: Math.min(from.y, to.y) - Math.abs(to.x - from.x) * 0.18 - 48
};
const invert = 1 - time;
return {
x: invert * invert * from.x + 2 * invert * time * control.x + time * time * to.x,
y: invert * invert * from.y + 2 * invert * time * control.y + time * time * to.y,
progress: time
};
}
控制点的 y 用 Math.min(from.y, to.y) - 弧长 * 0.18 - 48 算,意思是「按水平距离的比例抬高,最少抬 48px」。这样从左侧托盘飞到右侧影像墙时弧线平缓,从托盘飞到近处纪要板时弧线也不算塌,两种极端情况都不需要手动调参。progress 字段顺手被用来做透明度插值,卡片越接近落点越实。
最容易被忽略的设计是「落空」。一个只会报成功的交互是不可信的,用户碰歪了但界面照样弹「投递成功」,他下次就不敢信这个提示了。所以触涟把落空做成了完整的一条事件:珊瑚色涟漪、顶部提示条写「涟漪落空,未命中任何目标窗口」、右栏日志用红色条目记下触点和时间、底部统计的「次落空」加一。下面三张截图是同一个应用在同一台鸿蒙 PC 上、依次选中三种内容时的状态,最硬的一条证据是每张图右上角那枚运行时胶囊:TapRipple 0.1.0 · 鸿蒙 PC · Electron v40.0.1-release。这行字不是我写死的字符串,是主进程通过 runtime:get 读 app.getVersion()、process.platform、process.versions.electron 之后拼出来的。也就是说,这句话本身就是鸿蒙 PC 上 Electron 运行时活着的证明。



七、上屏:从静态检查到 HAP 装进鸿蒙 PC
Electron 项目在鸿蒙 PC 上的交付流程,和传统桌面端的 electron-builder 完全不是一回事,中间要过 hvigor 这一道。触涟把每一步都做成了脚本,一条命令一步:
npm run verify # 静态检查 + 单测 + 浏览器预览构建
npm run hap:init # 从官方 v40.0.1 ohos_hap 复制壳工程(改包名、修搬迁链接)
npm run hap:sign # 把本机签名材料写进 build-profile.json5
npm run hap:build # hap:sync 同步业务代码 + hvigorw assembleHap
npm run hap:install # hdc install -r,输出必须含 install bundle successfully
npm run hap:start # hdc shell aa start -a EntryAbility -b com.nexaport.app
最值得抄走的是环境准备那几行。鸿蒙 PC 上的命令行工具链不在系统 PATH 里,而是在一个 hnp 目录下,构建前必须自己拼出来:
HMOS_CLT_HOME=${HMOS_CLT_HOME:-/data/service/hnp/hmos-clt.org/hmos-clt_1.0.0}
DEVECO_SDK_HOME=${DEVECO_SDK_HOME:-$HMOS_CLT_HOME/sdk}
export HMOS_CLT_HOME DEVECO_SDK_HOME
PATH=$HMOS_CLT_HOME/node/bin:$HMOS_CLT_HOME/hvigor/bin:$HMOS_CLT_HOME/ohpm/bin:$DEVECO_SDK_HOME/default/openharmony/toolchains:$PATH
export PATH
node、hvigorw、ohpm、hdc 全部来自这条 PATH,用绝对路径调用官方工具,不给「我这台机器能跑、他那台跑不了」留空间。构建脚本还做了两件保险:一是 hap/oh_modules 不存在时先跑一次 ohpm install --all,二是构建完立刻检查 electron-default-signed.hap 是否存在且非空——因为 hvigor 有时候会「成功退出但没产物」,等你 hdc install 的时候才发现装了个旧包。
安装脚本里那句校验也值得单独提:
OUTPUT=$(hdc install -r "$HAP_PATH" 2>&1)
case "$OUTPUT" in
*"install bundle successfully"*) printf '%s\n' '安装结果已确认' ;;
*) printf '%s\n' 'hdc 输出未确认安装成功' >&2; exit 1 ;;
esac
hdc install 的返回码在部分版本上并不可靠,包名不匹配、签名冲突、versionCode 降级都可能只打一行日志然后返回 0。所以脚本不认返回码,认输出里的那句成功提示。这一个小改动把「装完打开还是旧界面」这类问题从排查半小时变成看一眼日志。
顺带说一句托管:这个鸿蒙 PC 应用的源码放在 AtomGit 上,壳工程因为是官方交付物所以不入库,仓库里只有业务层、脚本和测试,克隆下来配好 hap.config.json 就能复现同一套构建。
八、用测试把「手感」钉成数字
几何算法最怕的是「改一行参数,某条路径悄悄坏掉」。触涟的 tests/ 里有两个文件、十几个用例,跑起来是秒级:
test('snapAnchor 吸附最近标注点且受最大距离限制', () => {
const anchors = [{ x: 10, y: 10 }, { x: 60, y: 60 }];
const snapped = snapAnchor(anchors, { x: 14, y: 12 }, 72);
assert.equal(snapped.anchor.x, 10);
const far = snapAnchor(anchors, { x: 150, y: 150 }, 72);
assert.equal(far, null);
});
test('resolveDelivery 矩阵与拒绝路径', () => {
const plan = resolveDelivery(CONTENT_KINDS.ORIGINAL_PHOTO.kind, TARGET_KINDS.SLIDES.kind);
assert.equal(plan.mode, 'cursor-drop');
const rejected = resolveDelivery('hologram', TARGET_KINDS.SLIDES.kind);
assert.equal(rejected.mode, 'rejected');
});
test('ripplePhases 三圈涟漪时序', () => {
const mid = ripplePhases(0.5);
assert.ok(mid[0].scale > mid[2].scale, '同相位内圈总是更早扩散');
assert.equal(ripplePhases(0)[1].alpha, 0, '后圈起步前不可见');
});
这几个断言看着朴素,但它们守的是三件真实的事:吸附半径不能偷偷被调大;未知内容类型必须走 rejected 而不是抛异常(渲染层拿不到策略时还要能画涟漪);涟漪的圈序不能反。最后一条尤其重要,因为涟漪是纯视觉的,一旦顺序错了没人会报 bug,只会觉得「这个动画有点怪」。
除了单测,scripts/check.mjs 还做静态检查:语法检查全部 .js/.cjs/.mjs 和所有 .sh,然后校验几条不可退让的约束——index.html 必须有 script-src 'self',主进程必须有 contextIsolation: true / nodeIntegration: false / webSecurity: true,必须有 Menu.setApplicationMenu(null),必须同时识别 'openharmony' 和 'ohos',package.json 里不允许出现 devDependencies.electron。最后这条是这套跨平台框架在鸿蒙 PC 上最容易犯的错:一旦有人为了「本地能调」装上了标准 Electron,libelectron.so 和 npm 二进制就会争着当运行时,症状是应用能启动但行为诡异。
九、把速率与矩阵做成可复算的表
触涟的投递速率不是四个随手写的数字。deliverySpeedMB 把"内容类型 × 目标窗口"映射成 86 / 64 / 58 / 42 MB/s 四档,测试里钉了两个具体值:deliverySpeedMB(10, 'cursor-drop') = 860、deliverySpeedMB(10, 'transcript-insert') = 420。换算成耗时,10 MB 的原图用光标直达约 0.12 秒,走文稿追加约 0.24 秒。四类载荷的体积也写在常量里——原图 12.5 MB、现场 4.2 MB、图表 0.3 MB、语音 1.8 MB——于是每个组合的预计耗时都能在页面里算出来,而不是靠一句"很快"糊过去。
resolveDelivery 背后是一张 4×4 完备矩阵,覆盖四类内容落到四个窗口的策略;未知组合统一返回 rejected。测试第 64–71 行专门检查这个兜底,避免某天新增一种内容类型后,页面悄悄走了默认分支却没人发现。相比文章前面说的"四种策略",把它明确成矩阵加兜底,扩展时才有地方下手。
落空涟漪是另一个解耦得很干净的地方。ripplePhases 只输出 scale 和 alpha:三圈错开 0.18,后圈起步前 alpha = 0。至于涟漪是青色还是珊瑚色,由渲染层根据 hitTest 的结果决定。几何计算和反馈语义分家之后,同一套时间轴既能表达"命中了",也能表达"落空了",不需要为两种反馈各写一份动画。
坐标进入引擎前还有一道清洗。normalizePoint 对越界值做夹取,对 NaN 和 null 直接拒绝;测试第 26–31 行覆盖了这三种输入。鸿蒙 PC 上的触点坐标来自屏幕绝对系,而泊位用的是相对比例,少了这道清洗,所有落点都会被吸到最右边那扇窗口——这是真机上最容易误判成"吸附算法坏了"的问题。台账上限 40 条,和 TapBeam 的 24 条不同,长会话里不会无限增长。
十、九个踩过的坑
- 标准 Electron 二进制在鸿蒙 PC 上不可用。业务代码跑在 HAP 内的
libelectron.so里,npm install electron只会带来混淆。 process.platform有两个值。openharmony和ohos都实测出现过,只判其一会让环境自检在某些机器上退化成「浏览器预览」。- 必须
Menu.setApplicationMenu(null)。鸿蒙 PC 的窗口自带系统菜单区,不置空就是两层菜单。 - 首窗口尺寸由壳决定。
BrowserWindow的width/height在鸿蒙 PC 上会被 HAP 壳module.json5里的ohos.ability.window.*metadata 覆盖,别在业务层调窗口大小,去壳里改。 - 签名材料不能进仓库。包名与签名材料绑定,
hap:init检测到源工程带signingConfigs就直接拒绝,避免把口令带进来。 - 工程搬迁会让
oh_modules里的符号链接指向旧绝对路径,症状是 CompileArkTS 报错。hap:init里有个fixRelocatedLinks专门重写这些链接。 hdc install的返回码不可信,要认输出里的install bundle successfully。- 触点坐标必须夹取。屏幕绝对坐标混进相对坐标系,会让所有落点都被吸到最右那扇窗口。
- 不要把「装完还是旧界面」当成热更新问题。多半是装错了包(同 bundleName 的其他工程、或者旧 versionCode),先
hdc uninstall再装。
十一、小结
回到最初那个问题:跨平台框架能不能在鸿蒙 PC 上做正经应用?触涟给出的答案是能,而且不需要牺牲工程质量。业务层是标准的 Electron 三件套(主进程、preload、渲染层),几何与状态机被抽成零依赖的纯函数并用 node:test 钉住,视觉全部由 DOM + CSS 完成,整个工程零 npm 依赖;壳层由官方 ohos_hap 提供,业务代码通过一条同步脚本落进 web_engine 的资源目录,最后由 hvigor 打成 HAP 装到鸿蒙 PC 上。真机截图里那台机器上跑的,就是 Electron v40.0.1-release 这个运行时。
如果你也想在鸿蒙 PC 上试一次,建议从最小的路径开始:先让一个 BrowserWindow 加载一个 HTML 在鸿蒙 PC 上弹出来,确认 process.platform 的返回值、确认菜单区没有叠层、确认窗口尺寸听壳的话,再往里加业务。这三件事确认完,剩下的就是普通的 Web 开发了。
碰一碰这种能力天生适合鸿蒙 PC:屏幕大、可落点多、触点坐标本身就是意图。触涟只做了四扇窗口四种落地方式,真实办公场景里的落点远比这复杂——下一版我打算把投递矩阵从「内容 × 目标」扩展到「内容 × 目标 × 区域」,让落格追加也能识别格子边界。对鸿蒙 PC 上的桌面应用来说,这种「把坐标变成意图」的活儿,还远远没做完。
更多推荐




所有评论(0)