在鸿蒙 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 直接跑单元测试,改一次算法两边同时生效。

TapRipple 触涟在鸿蒙 PC 上运行的完整界面

关键词:鸿蒙 PC、Electron、跨平台框架、碰一碰精准分享、触点命中、HAP 打包上屏、AtomGit

一、跨平台框架在鸿蒙 PC 上的真实运行形态

先把最容易误解的一点说清楚:在用 Electron 开发鸿蒙 PC 应用时,你 npm install electron 拿到的那份标准二进制是跑不起来的。OpenHarmony 上没有对应的官方 Electron 二进制,Chromium 与 Node 的运行时是以 libelectron.so 的形式,作为一个原生库躺在 HAP 壳工程里的。所以正确的心智模型是这样三层:

  1. 业务层:app/ 目录里的 main.js、preload.js、renderer.mjs、index.html,这部分是标准的 Electron 代码,你在 Windows 上写的写法基本都能照搬;
  2. 壳层:官方提供的 ohos_hap 预编译工程,里面有 AppScope、electron 模块、web_engine 模块,以及 libs/arm64-v8a/libelectron.so 和 libadapter.so;
  3. 打包层: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 运行时活着的证明。

选中「现场照片」时的速率预估为 361.2 MB/s

选中「图表数据」时的速率预估为 25.8 MB/s

选中「语音便签」时的速率预估为 154.8 MB/s

七、上屏:从静态检查到 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 条不同,长会话里不会无限增长。

十、九个踩过的坑

  1. 标准 Electron 二进制在鸿蒙 PC 上不可用。业务代码跑在 HAP 内的 libelectron.so 里,npm install electron 只会带来混淆。
  2. process.platform 有两个值。openharmony 和 ohos 都实测出现过,只判其一会让环境自检在某些机器上退化成「浏览器预览」。
  3. 必须 Menu.setApplicationMenu(null)。鸿蒙 PC 的窗口自带系统菜单区,不置空就是两层菜单。
  4. 首窗口尺寸由壳决定。BrowserWindow 的 width/height 在鸿蒙 PC 上会被 HAP 壳 module.json5 里的 ohos.ability.window.* metadata 覆盖,别在业务层调窗口大小,去壳里改。
  5. 签名材料不能进仓库。包名与签名材料绑定,hap:init 检测到源工程带 signingConfigs 就直接拒绝,避免把口令带进来。
  6. 工程搬迁会让 oh_modules 里的符号链接指向旧绝对路径,症状是 CompileArkTS 报错。hap:init 里有个 fixRelocatedLinks 专门重写这些链接。
  7. hdc install 的返回码不可信,要认输出里的 install bundle successfully。
  8. 触点坐标必须夹取。屏幕绝对坐标混进相对坐标系,会让所有落点都被吸到最右那扇窗口。
  9. 不要把「装完还是旧界面」当成热更新问题。多半是装错了包(同 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 上的桌面应用来说,这种「把坐标变成意图」的活儿,还远远没做完。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐