在鸿蒙PC上用 Electron 跨平台框架开发碰一碰精准分享应用:TapPort 碰泊塔台实战

欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/

欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

基于 Electron 的鸿蒙化适配项目地址:https://atomgit.com/CPF-Electron/Electron

前言

把手机与电脑之间的分享做得更直接,关键不只是“把文件传过去”,还要让内容落在用户真正想要的位置。TapPort(碰泊塔台)是一个围绕 HarmonyOS 7 碰一碰能力设计的桌面交互演示应用:屏幕上布置演示稿、图纸、白板和相册四个目标区域,界面模拟手机触碰 PC 屏幕后,按触点命中区域生成对应投递计划,并在塔台日志中显示时间、坐标、载荷与目标。本文聚焦的不是泛泛介绍,而是在鸿蒙PC电脑上使用 Electron 跨平台框架开发鸿蒙PC应用的工程实践:业务界面采用 HTML、CSS 与 JavaScript,Electron 主进程负责窗口和受控 IPC,项目再通过适配工程打包为 HAP,在鸿蒙PC上运行。

关键词:鸿蒙PC,Electron跨平台框架,HarmonyOS 7,TapPort,碰一碰,精准分享,HAP,AtomGit

TapPort 在鸿蒙PC上的完整应用界面

图:TapPort 项目截图。应用以深空蓝塔台为视觉主题,展示碰触画布、多个投递泊位和操作日志。截图来自项目提供的运行画面;具体设备环境请以实际截图采集记录为准。这里讨论的是 Electron 应用在鸿蒙PC上的开发与交付,不把它误称为纯 ArkTS 原生应用。

一、Electron 在鸿蒙PC项目中的位置

Electron 的开发模型是由 Chromium 渲染网页界面、由 Node.js 驱动主进程逻辑,再通过 preload 将有限能力暴露给渲染层。TapPort 延续这套模型:app/index.html、styles.css、renderer.mjs 组成塔台界面,tapcore.mjs 保存可独立测试的碰触计算逻辑,main.js 管理 Electron 窗口和 IPC,preload.js 是两进程之间的窄桥。

需要区分“使用 Electron 写业务”和“底层平台适配”。项目 README 指出,鸿蒙目标不能直接拿桌面 Windows 的 Electron 可执行文件运行;它采用 OpenHarmony 对应的 Electron/HAP 构建流程,产物为 HAP,并受对应运行时及 ABI(项目文档中特别提到 musl_64)约束。换言之,HTML、CSS、JavaScript 的业务组织方式可以延续 Electron 跨平台框架的开发习惯,但打包、签名、安装和系统能力接入仍需遵循鸿蒙PC适配链路。标准 npm Electron 包并不等于可直接安装的鸿蒙PC应用。

该项目将 HAP 壳参数集中在 hap.config.json,包名为 com.memora.heapstudio,并将 Electron 业务入口放在 app/main.js。开发者可以从 npm run hap:init 开始准备壳工程,再按项目脚本完成同步、签名、构建和安装。界面也可以直接打开 app/index.html 进行浏览器预览,但浏览器预览只验证前端交互,并不能代替鸿蒙PC设备上的 Electron/HAP 运行验收。

二、把“碰哪传哪”变成可计算的模型

触点坐标是精准分享的核心。TapPort 把屏幕区域抽象为泊位,每个泊位拥有 id、kind、矩形位置和尺寸。kind 决定落点语义:演示稿把内容放到光标附近,图纸将照片以图钉语义挂载,白板以触点为便签左上角,相册则将整批照片入册并记录坐标。原型中载荷类型为原图、便签、语音和文档。

核心算法不依赖 Electron API,因此可以在 Node 测试中独立验证。先做边界命中,再把触点夹取到泊位安全区,避免交互卡片贴边溢出;最后按泊位类型生成投递计划。下面是简化但可运行的核心实现,体现项目 tapcore.mjs 的处理思路:

const zoneMeta = {
  slide: { dx: -28, dy: -20, verb: '原图插入光标处' },
  drawing: { dx: -12, dy: 8, verb: '现场照片挂载钉固' },
  board: { dx: 0, dy: 0, verb: '便签贴附触点' },
  album: { dx: 0, dy: 0, verb: '整批照片入册' }
};

function planDelivery(tap, zone, payloadKind) {
  if (!Number.isFinite(tap?.x) || !Number.isFinite(tap?.y)) return null;
  if (!zone || !zoneMeta[zone.kind] || !zone.size) return null;
  if (!['photo', 'note', 'audio', 'file'].includes(payloadKind)) return null;

  const padding = Math.max(0, Math.min(24,
    zone.size.width / 2, zone.size.height / 2));
  const anchor = {
    x: Math.round(Math.min(Math.max(tap.x, zone.x + padding),
      zone.x + zone.size.width - padding)),
    y: Math.round(Math.min(Math.max(tap.y, zone.y + padding),
      zone.y + zone.size.height - padding))
  };
  const { dx, dy, verb } = zoneMeta[zone.kind];
  return {
    zoneId: zone.id,
    payloadKind,
    tap: { x: Math.round(tap.x), y: Math.round(tap.y) },
    anchor,
    drop: { x: anchor.x + dx, y: anchor.y + dy },
    verb
  };
}

代码里的 tap 是画布坐标,不是手机触摸硬件的原始传感器数据。实际产品接入系统级碰一碰能力时,需要由鸿蒙侧能力回调提供载荷与触点,再把屏幕坐标转换到应用内容区域坐标系。这个原型把“触碰”做成可点击的交互模拟,重点验证落点寻址、泊位语义和反馈闭环;不能据此声称它已经完成手机与 PC 的真实近场传输。

TapPort 泊位与坐标交互画面

三、坐标命中与尺寸变化

在窗口可缩放的桌面应用里,写死像素矩形很容易失效。TapPort 的工程经验是优先用相对比例描述泊位布局,再根据渲染后元素的 getBoundingClientRect() 计算像素区域。命中判定和绘制都使用同一套画布坐标,避免视觉区域与算法区域错位。

命中判定要包含边界:触点恰好落在矩形右侧或下侧时仍可认为命中。输入校验也不能省略。项目把点校验与尺寸校验分开,避免把 {width, height} 当成 {x, y} 复用验证函数,造成所有区域静默不命中。未命中泊位时,应用并不只显示失败,而是寻找中心距离最近的泊位并给出提示;这让用户知道应该把触点移向哪里。

投递锚点使用安全边距夹取。若泊位尺寸小于两倍 padding,则边距收敛到泊位的一半,锚点落在中心而不是产生反向区间。不同泊位再叠加各自偏移:演示稿偏向光标行,图纸略向下放置图钉,白板保持触点原点。设计上,命中、锚点和语义偏移是三个独立步骤,方便单测覆盖边缘条件,也便于后续替换真实布局。

四、Electron 主进程、preload 与安全边界

桌面应用不能把 Node 全量能力直接交给网页渲染层。TapPort 的 BrowserWindow 配置启用 contextIsolation、关闭 nodeIntegration,并通过 preload 中的 contextBridge 暴露少量方法。主进程还拒绝新窗口、拦截离开本地入口页面的导航,并验证 IPC 发送方是否为可信页面。

项目中桥接接口很小:getRuntime() 获取运行时信息,deliver(plan) 提交投递计划。渲染页面不直接访问 Node 文件系统或 Electron 的完整 IPC 对象。这种边界在鸿蒙PC上同样重要:跨平台框架让 UI 复用更方便,但并不意味着可以忽略页面来源、权限和消息校验。

// preload.js:只暴露明确的业务方法
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('tapport', {
  getRuntime: () => ipcRenderer.invoke('runtime:get'),
  deliver: (plan) => ipcRenderer.invoke('tap:deliver', plan)
});

主进程收到 tap:deliver 后,再检查发送方和计划结构;项目示例会校验 zoneId,生成时间戳与平台回执。正式业务接入时,还应对载荷大小、泊位标识白名单和重复请求做更严格校验,并将系统能力调用放在适配层中,而不是让渲染进程直接调用任意原生接口。项目针对 ohos 和 openharmony 两种 process.platform 值均做识别,避免平台标识差异导致判断分支失效。

TapPort 操作反馈与日志区域

五、测试策略:纯逻辑先测,设备链路再验

TapPort 将几何算法放在 tapcore.mjs,通过 Node 内置 node:test 编写测试,不需要先启动窗口或连接设备。现有测试覆盖边界命中、畸形输入、最近泊位、夹取、各泊位的落点语义、重复投递去重、队列容量、坐标格式化和雷达波纹序列。main-utils 相关测试则覆盖可信 URL、窗口尺寸边界和运行时信息。

运行项目验证命令:

npm run verify

它依次执行静态检查、Node 测试和业务包构建。这个验证说明算法与项目构建脚本符合当前工程检查,不等于已经证明 HAP 在任意鸿蒙PC版本上都可运行。设备端仍需按目标 SDK 与工具链完成壳工程初始化、签名、HAP 构建、hdc install -r 安装和应用启动,并观察窗口尺寸、输入坐标、窗口焦点、系统权限与日志表现。项目脚本提供 hap:init、hap:sign、hap:build 等入口,实际使用时应先阅读工程 docs/EXPERIENCE.md 与目标环境要求。

六、界面反馈与异常场景

塔台界面把操作过程可视化:触点触发雷达波纹,十字标记保留坐标,投递卡片按计划落地,日志记录时间和泊位。空白区域触碰采用不同颜色提示,并指出最近泊位;自动巡航演示则串联四个区域,适合快速观察布局和状态变化。队列对同泊位、同载荷在短时间内的重复请求去重,并限制容量,避免演示中连续点击导致记录无限增长。

这些反馈不是装饰,而是便于排查坐标映射问题的观测面板。当卡片落点看起来不正确时,可以分别检查:实际命中的区域、原始触点、夹取后的锚点、泊位偏移,以及渲染区域是否发生缩放。把中间结果暴露出来,比只保留最终动画更利于定位问题。鸿蒙PC的窗口大小和显示缩放可能不同于开发者浏览器,因此设备上应重新验证区域测量,不能仅依赖固定分辨率下的预览效果。

TapPort 自动巡航与落点展示

七、开发者复现路线

如果要基于 Electron 跨平台框架复刻这类鸿蒙PC应用,可以按下面顺序推进:

  1. 先拆业务模型。 把泊位、载荷和落点规则定义成纯数据与纯函数,先不依赖 Electron。
  2. 搭建渲染层。 用 HTML/CSS 实现可缩放画布和状态反馈,确保浏览器预览可完成交互。
  3. 建立主进程边界。 用 preload 暴露窄接口,校验 IPC 来源、参数和导航,不将 Node 权限交给页面。
  4. 跑通鸿蒙适配壳。 使用项目提供的 HAP 流程和匹配的 Electron 运行时,确认架构、SDK、签名配置一致。
  5. 在鸿蒙PC设备闭环验收。 安装 HAP 后核对运行时平台信息、窗口行为、触点坐标和系统级能力接入结果,并保留完整桌面截图与构建记录。

代码托管与协作建议统一使用 AtomGit,提交 README、版本依赖、构建脚本和设备验证步骤;不要把签名私钥、证书口令或设备个人数据提交到仓库。文章中的截图来自项目提供的图片目录,展示的是应用界面;如需作为“鸿蒙PC真机运行证明”发布,应确保图中完整保留 HarmonyOS 桌面特征,并由实际设备采集原图佐证,不应用浏览器预览图替代。

八、防手抖队列与坐标的寿命

TapPort 把屏幕画成停机坪,四个目标窗是四个泊位。听起来只是视觉隐喻,但真正让原型在真机上不"抽风"的,是一段不起眼的去重逻辑。pushDelivery 对同一泊位、同一载荷在 600 ms 内的重复触点做合并,队列容量固定 12 条,满了就丢最旧的。测试里塞了 20 条压力数据,最后剩下的是 stress-8 到 stress-19——也就是最新的 12 条。没有这道闸门时,手指在触摸屏上轻轻一抖就会生成好几条投递记录,台账瞬间变成噪声。

坐标的寿命则靠"相对描述 + 命中前重算"两件事保证。泊位在模型里用比例坐标定义,命中前按 getBoundingClientRect() 换算成当前像素坐标。窗口一缩放,换算结果自然跟着变,不需要在每一个 resize 回调里手工迁移旧数据。这一点在鸿蒙 PC 上尤其重要:同一份业务代码在浏览器预览里是 1280 宽,真机上可能是 1440 甚至更宽,绝对坐标一旦写死,预览通过也没意义。

anchorPointInZone 负责把触点夹到泊位内部。测试给了一个完整例子:触点 (100, 80) 落在 slide 泊位、padding 取 24,输出是 (124, 104);如果泊位只有 20×20,padding 已经超过半宽,函数退而求其次返回中心点 (10, 10)。这条退化路径很容易被漏掉——小窗口下所有触点都会挤到边界,如果没有兜底,用户会看到落点贴着泊位外沿。把"夹取失败就取中点"写进纯函数,渲染层就不用再做二次判断。

台账的可读性也有契约。formatCoord({x:834, y:12}) 输出 X 0834 · Y 0012,四位定宽便于逐列对齐;非法输入输出 X ---- · Y ----,一眼就能看出是坏数据而不是排版问题。formatLogLine 同时兼容 payloadLabel 和 payloadKind 两级字段推导,老日志不会因为字段改名而变成空白。

最后记两个静默失败陷阱。isFinitePoint(zone.size) 在尺寸对象上永远返回 false,必须单独写 isFiniteSize;少了它,所有命中和夹取都会悄悄返回 null,界面看起来只是"没反应"。另外 .mjs 文件不认 module.exports,整套工程统一 ES Module 写法。坑不复杂,但都不会让构建失败,只会在真机上变成"查半天不知道哪里错了"的时间黑洞。

结语

TapPort 展示了一条可理解、可复用的路线:用 Electron 跨平台框架构建鸿蒙PC应用的 Web 业务界面,将坐标命中和投递规则拆成可测试的纯逻辑,通过 preload/IPC 把渲染层与主进程隔离,再用 OpenHarmony 对应的 HAP 适配流程完成交付。它的“碰一碰”流程是交互原型,重点验证坐标寻址和界面反馈;真实系统级分享仍需接入并验证鸿蒙侧对应能力。明确区分原型模拟、Electron 运行时和系统能力接入,才能让鸿蒙PC跨平台开发既容易复现,也保持技术表述准确。

Logo

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

更多推荐