Electron 鸿蒙工程接入 ArkTS:同步异步桥接与真机验证
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 项测试与性能结果另见仓库报告。
交付内容与获取入口
- 演示讲解视频
- 项目源码及主文档
- npm CLI:0.1.2 已公开,并完成匿名下载安装验证。
- OHPM HAR:0.1.1 已公开,完成公共安装与消费工程构建验证。
- 快速接入
- API 与业务开发
- 源码构建与 CI
- 跨版本全项验证与性能结果
- 代码量对照
0.1.2 更新了文档与打包组织,原生二进制和 ArkTS 桥接实现与 0.1.1 一致。上述功能与性能真机报告对应其原始测试版本。
更多推荐

所有评论(0)