@henan4254/electron-arkts-bridge-kit
v0.1.2
Published
Electron to OpenHarmony ArkTS bridge kit with interactive integration CLI
Maintainers
Readme
Electron ArkTS Bridge Kit
面向 OpenHarmony 的 Electron JS 调用 ArkTS 标准化桥接套件,提供 callSync/callAsync、原生桥接模块、HAR 共享包及自动化接入工具。
一行自动接入(推荐)
工程及上级目录请使用Hvigor支持的英文路径;本次实测中文路径会被构建工具拒绝。
在已有Electron鸿蒙工程根目录的DevEco终端执行:
npx -y @henan4254/[email protected] init --yes自动下载CLI和匹配产物,安装HAR与.node、更新依赖并完成初始化和绑定,两个桥接.so随HAR打包。-y同意运行npx,末尾--yes同意CLI自动执行全部接入步骤;原文件自动备份,失败时给出恢复说明。完成后在DevEco构建、签名并安装应用。
适用于已有electron/web_engine结构及匹配运行库;旧桥迁移或自定义工程见接入场景与排错,详细步骤见快速接入。
使用条件
- 鸿蒙OS 6.0.0及以上,最低API20,arm64-v8a;已测试设备覆盖6.0.1、6.1.1和7.0.0。
- 已有electron/web_engine结构,宿主提供匹配的Electron运行库和libc++_shared.so。
- 接入后使用DevEco构建、签名并安装宿主HAP;修改ArkTS业务路由后需要重新构建。
注册自己的鸿蒙功能(按需)
桥安装好后,按业务需要生成路由,例如:
npx -y @henan4254/[email protected] add myFeature --async --yes填写生成的ArkTS业务实现后重新构建宿主HAP;默认custom模板明确返回“尚未实现”。可运行的设备信息和echo模板见示例。
API
0.1.1支持每次异步调用指定timeoutMs;0.1.0不支持该选项,见异步超时配置。
Electron 主进程:
const bridge = require('ets_bridge_addon.node');
const syncResult = JSON.parse(bridge.callSync('echo', 'hello'));
const asyncResult = JSON.parse(await bridge.callAsync('echo', 'hello'));callSync 返回 JSON 字符串,callAsync 返回 Promise<string>;结果统一为 { code: number, data: string, msg: string },code === 0 表示成功。未知路由、异常和超时返回非零 code;原生参数类型错误抛出 TypeError。业务对象可自行序列化到 data 字符串中。
ArkTS 业务路由在宿主 BridgeBootstrap.bind() 中、CommonBridge.bind() 之前注册:
import { CommonBridge } from 'electron-arkts-bridge';
CommonBridge.registerSyncMethod('echo', (params: string): string => params);
CommonBridge.registerAsyncMethod('echo', (params: string, complete: (success: boolean, data: string) => void): void => {
setTimeout(() => complete(true, params), 20);
});异步失败时调用 complete(false, '错误说明');重复完成会被忽略。默认等待上限为 15 秒;异步调用可通过第三个参数指定1—300000毫秒,超时不会取消业务自身的后台任务,因此业务应自行处理资源取消和释放。同步处理函数应及时返回,不执行阻塞 ArkTS 线程的任务。
screenCapture 为保留的异步方法,参数支持 {"mode":"full"}、{"mode":"full_png"}、{"mode":"full_0_png"} ;未传mode时默认full。交互式 {"mode":"area"} 暂列实验能力,当前设备的取消行为未可靠验证。成功的 data 为图片 Base64,二进制在原生层复制并编码;取消或失败返回错误结果。
其他接入方式(按需)
逐步确认时,执行不带CLI --yes的命令:
npx -y @henan4254/[email protected] initdoctor或init --dry-run预览文件改动;--project /path/to/ohos_hap指定工程。旧library只承载桥接时才使用--replace-legacy-library,其他迁移按手动说明合并。
本地tgz及源码运行见快速接入的其他方式,源码构建见构建与CI。
单独安装OHPM的electron-arkts-bridge提供ArkTS与.so,.node及宿主初始化仍需配套;按手动接入操作,避免与CLI的同名本地HAR重复安装。
安装备份在工程.bridge-kit/backups,日志在.bridge-kit/install.log及last-error.log,恢复方式见接入场景与排错。
维护者构建与验证
提供HAR和配套npm CLI,名称及公共仓库状态见发布记录。构建使用 Mac 上的 DevEco Studio SDK 和目标 Electron 运行时,无需服务器或 Electron 全量源码;原生N-API转发层由源码构建,不依赖旧libshim.a。
npm ci --ignore-scripts
ELECTRON_LIBRARY=/path/to/ohos_hap/electron/libs/arm64-v8a/libelectron.so npm run build
npm test默认工具目录为 /Applications/DevEco-Studio-6.1.1.app/Contents,可用 DEVECO_HOME 覆盖;OHOS_NATIVE_SDK 和 DEVECO_SDK_HOME 可分别覆盖 Native SDK 与 SDK 根目录。
产物在 dist/:HAR 包含 ArkTS 路由、截图桥接、libets_bridge_adapter.so 和 libaki_jsbind.so;.node 由接入脚本放入宿主原生库目录。宿主提供匹配的 libelectron.so 和 libc++_shared.so,接入脚本核对 Electron 哈希并保留宿主 C++ 运行时。
node scripts/prepare-validation.mjs /path/to/ohos_hap
npm run test:device
node scripts/prepare-demo.mjs
node scripts/test-demo.mjs
node scripts/archive.mjs归档脚本还需要已构建并验证的 out/demo-project,所以上述顺序先运行演示准备与验证脚本。重复执行准备/归档脚本前,先将已有同名输出移到独立备份目录;脚本会拒绝覆盖已有结果。
准备脚本将运行时模板复制到 out/validation-project,去除旧桥接源模块、缓存与二进制,再从 dist/ 接入套件。使用模板已有的本地签名配置;测试应用沿用模板的 bundleName,因此安装时会更新设备上的对应调试应用。
测试覆盖原生加载、同步/异步、Unicode、未知路由、异常、参数校验、重复回调、16 路并发、1 MiB 数据、全屏 JPEG/PNG 解码、15 秒超时和迟到回调后的恢复。原生工具测试启用 AddressSanitizer 和 UndefinedBehaviorSanitizer,检查 Base64 填充及等待状态的生命周期。
每次真机运行在 out/device-runs/ 保存结果、环境、日志、截图及签名 HAP;out/latest-device-run.txt 指向最近一次运行。archive.mjs 将成功运行的产物、脚本、源码和构建日志收集到 out/archive/,排除本地签名配置及私钥。
支持范围为鸿蒙OS 6.0.0及以上、arm64-v8a;测试设备、Electron/Node版本及运行记录见对应报告。
