Electron 鸿蒙工程接入 ArkTS:同步异步桥接与真机验证

作者:何楠。本文介绍我开发的 Electron ArkTS Bridge Kit,包含已有工程接入、业务路由扩展、超时配置和实测结果。

项目源码:https://gitcode.com/he-nan/electron-arkts-bridge-kit

演示视频:https://www.bilibili.com/video/BV1HDs36NELz/

为什么做这个套件

本项目为已有的 Electron 鸿蒙工程提供一套可复用的 JS 调用 ArkTS 桥接工具。Electron 通过 callSync 或 callAsync 调用鸿蒙能力,ArkTS 按方法名执行对应业务,再将结果返回 Electron。

套件把原生通信、回调管理和业务实现分开。接入者安装一次桥接后,新增功能只需注册 ArkTS 路由,无需反复修改底层 addon、adapter 或 NAPI/AKI 通信代码。

解决的问题

Electron 与 ArkTS 分别运行在不同的运行环境中。手工接入某项鸿蒙能力时,通常需要同时处理原生模块导出、参数转换、回调等待、错误返回和宿主初始化。业务越多,重复桥接代码越难维护。

异步任务还涉及回调引用的保留、等待超时、重复回调和迟到结果。截图等二进制数据需要进一步处理跨层缓冲区、内存释放与图片编码。

本项目将这些公共逻辑封装到套件内部,给业务开发保留清晰的路由注册和调用入口。

实现思路

三层职责分离

  • Node addon(.node):向 Electron JS 暴露 callSync、callAsync,校验调用参数并衔接原生执行。
  • NAPI adapter(.so):连接 AKI 与 ArkTS 绑定,维护等待状态、超时及截图二进制数据处理。
  • ArkTS CommonBridge(HAR):维护同步和异步业务路由,执行鸿蒙业务并封装标准结果。

Electron 调用统一桥接入口后,套件按方法名分发到 ArkTS。同步业务直接返回字符串,异步业务在完成后通过 complete 返回成功状态和业务数据。

统一结果格式

{
  "code": 0,
  "data": "操作成功",
  "msg": "success"
}

code === 0 表示成功。data 为字符串,业务对象可序列化为 JSON 字符串。callSync 返回 JSON 字符串,callAsync 返回 Promise<string>。未知路由、业务异常及超时通过非零 code 返回,原生参数类型不正确时抛出相应参数错误。

异步等待与超时

原生层使用条件变量管理等待,避免持续忙轮询。ArkTS 回调和原生请求状态保留到相应生命周期结束,重复或迟到的完成信号不会让同一请求再次完成。

异步调用默认等待 15 秒,也支持每次独立指定 timeoutMs,范围为 1—300000 毫秒。例如为某项业务设置 5 秒:

下面的调用片段放在 async 函数中:

const bridge = require('ets_bridge_addon.node');
const result = JSON.parse(await bridge.callAsync(
  'myFeature',
  JSON.stringify({ value: 'hello' }),
  { timeoutMs: 5000 }
));

超时结束桥接等待,不自动取消业务自身的网络请求或后台任务,相关业务资源由业务层管理。

截图与大数据

宿主先完成截屏授权,ArkTS 再调用系统截图和图片编码。原生层安全复制缓冲区、完成 Base64 编码并释放相应内存,最后通过标准结果返回 Electron。

已验证全屏 JPEG、PNG、1 MiB 异步数据及重复截图。交互式区域截图保留为实验能力。

接入方式

1. 安装桥接

在已有 Electron 鸿蒙工程根目录的 DevEco 终端执行:

npx -y @henan4254/electron-arkts-bridge-kit@0.1.2 init --yes

CLI 下载匹配产物、安装依赖并配置初始化绑定。HAR 内携带 ArkTS 通用层和桥接 .so,.node 安装到宿主原生库目录。接入过程保留备份,失败时提示恢复方法与手动接入文档。

接入条件是已有 electron/web_engine 工程结构,宿主提供匹配的 Electron 运行库与 C++ 运行库。工程及上级目录使用 Hvigor 支持的英文路径,完成接入后在 DevEco 构建、签名并安装 HAP。

2. 注册同步和异步业务

同步和异步路由分别生成:

npx -y @henan4254/electron-arkts-bridge-kit@0.1.2 add myFeature --sync --yes
npx -y @henan4254/electron-arkts-bridge-kit@0.1.2 add getHarmonyUUID --async --yes

同步路由通过 registerSyncMethod 注册,Electron 使用 callSync 调用;异步路由通过 registerAsyncMethod 注册,Electron 使用 callAsync 调用。

生成后,在对应 ArkTS 文件中填写实际业务。异步处理函数的完成回调可以这样返回成功:

static handle(_params: string, complete: AsyncCompletion): void {
  complete(true, '操作成功');
}

自定义模板默认返回“尚未实现”。getHarmonyUUID 在这里仅是自定义方法名称,不会自动实现设备标识获取,需要开发者填写业务代码。修改 ArkTS 后重新构建、签名并安装宿主应用。

3. 在 Electron 主进程调用

const { app } = require('electron');

app.whenReady().then(async () => {
  const bridge = require('ets_bridge_addon.node');
  const syncResult = JSON.parse(bridge.callSync('myFeature', 'hello sync'));
  const asyncResult = JSON.parse(await bridge.callAsync(
    'getHarmonyUUID',
    'hello async',
    { timeoutMs: 5000 }
  ));
  console.log('同步结果:', syncResult);
  console.log('异步结果:', asyncResult);
}).catch(console.error);

第三个参数 { timeoutMs: 5000 } 表示本次异步调用等待 5 秒,省略则默认 15 秒。使用 await 的回调需要声明为 async。这段示例以生成的业务路由已实现为前提。

创新功能与体验优化

一套公共桥接承载多种业务

底层原生通信保持稳定,通过方法名与路由表扩展能力。同步查询、异步业务与截图可以使用统一的调用形式。

业务异步完成后返回结果

异步处理函数持有完成回调,在实际业务结束后返回,Electron 通过 Promise 获取结果。每个请求独立管理超时和完成状态,并发请求保持各自结果。

将接入步骤收敛到 CLI

自动接入工具负责产物匹配、依赖安装和初始化配置,路由生成工具负责搭建新功能的代码入口。开发者仍然使用熟悉的 DevEco 构建、签名和安装流程。

对运行问题给出统一反馈

未注册方法、业务异常、超时和参数错误都有明确反馈。接入失败时保留日志、备份及恢复说明,便于定位问题和手动接入。

分发与复现同时交付

项目提供公共 npm CLI、OHPM HAR、源码、CMake、构建脚本、初始化模板、示例及 API 文档。设备报告保留运行标识、环境信息和原始数据,便于复核功能与性能结果。

实现效果与测试

真机功能验证

已在鸿蒙电脑真机及云端真机完成测试,记录覆盖:

  • OpenHarmony 6.0.1.115:26 项功能及 4 项截图诊断通过。
  • OpenHarmony 6.1.1.135:早期真机 26 项功能通过。
  • OpenHarmony 6.1.1.130:0.1.1 的 34 项功能与超时、4 项截图诊断通过,并完成性能对照。
  • OpenHarmony 7.0.0.105:0.1.1 的 34 项功能与超时、4 项截图诊断通过,并完成性能对照。
  • OpenHarmony 7.0.0.109:0.1.1 的 34 项功能与超时通过。

套件声明支持鸿蒙OS 6.0.0及以上,最低 API20,目标架构为 arm64-v8a。以上列出的系统版本为已有实测记录。

测试内容包含原生模块加载、CLI 生成路由、同步与异步返回、Unicode、未知方法、异常、参数校验、重复回调、并发隔离、1 MiB 数据、全屏截图及自定义超时后的恢复。

性能对照

基线使用独立手写 addon/adapter 与专用 ArkTS 绑定。套件与基线在同一设备执行相同业务,保持返回格式一致。每个场景执行 5 轮,每台设备共 320000 个计时样本,使用 process.hrtime.bigint() 记录调用时延。

各场景合并样本的平均时延增长如下:

  • OpenHarmony 6.1.1.130:同步小数据 1.02%,异步小数据 3.65%,设备信息 1.14%,同步 64 KiB 数据 0.30%,异步 64 KiB 数据 -0.25%。
  • OpenHarmony 7.0.0.105:同步小数据 2.70%,异步小数据 1.82%,设备信息 0.86%,同步 64 KiB 数据 4.29%,异步 64 KiB 数据 3.71%。

以上每个场景的合并样本平均增长均低于 10%。完整报告保留逐轮结果和原始样本,汇总与原始数据的摘要及统计值已核对。

桥接编码量对照

对相同的同步 echo、异步 echo 和设备信息业务,按非空、非注释代码行统计:

  • 手写桥接为 281 行,最小 API 接入为 29 行,减少 89.68%。
  • 将 CLI 生成代码全部计入,套件侧为 59 行,减少 79.00%。
  • 复用既有通信通道新增业务的样例,手写为 19 行、套件为 2 行,减少 89.47%。

此处统计的是相同样例的桥接编码量,不包含 SDK 安装、源码下载及编译耗时。

项目图片

真机功能界面

鸿蒙电脑上的桥接演示界面

2026-10-30 真机截图,界面展示设备信息、同步调用、异步调用与全屏截图入口,并显示实际返回的设备信息。

真机功能测试记录

鸿蒙电脑上的功能测试结果

2026-10-30 真机截图,展示原生加载、路由、同步与异步、异常、并发和大数据等测试结果。后续 0.1.1 的 34 项测试与性能结果另见仓库报告。

交付内容与获取入口

0.1.2 更新了文档与打包组织,原生二进制和 ArkTS 桥接实现与 0.1.1 一致。上述功能与性能真机报告对应其原始测试版本。

Logo

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

更多推荐