OpenHarmony【免费下载链接】cangjie_js_interop项目地址https://gitcode.com/Cangjie/cangjie_js_interop点击查看免费下载本文以仓颉-JavaScript 互操作库cangjie_js_interop的 README 为主线系统讲解它的系统架构、类型体系与生命周期模型并结合 src 目录下 runtime、context、function、uv 等核心源码剖析跨语言函数调用、异常转换与线程协同的底层实现最后给出从工程构建到 DevEco 实战调用的完整可复制流程。读完本文你可以独立完成该互操作库的编译构建并在 OpenHarmony 应用中实现仓颉与 JavaScript 的双向调用。一、库定位与应用场景仓颉-JavaScript 互操作库用于提供仓颉调用 JavaScript 的跨语言能力即仓颉调用 JavaScript 库的互操作接口。它期望给开发者提供兼顾开发效率和运行效率的跨语言解决方案提供简洁的开发范式降低跨语言互通开销。同时本仓库还提供了公共文档包含 API 参考API 文档和用户手册用户手册。需要特别注意的是当前仓库开放的接口仅支持 OpenHarmony鸿蒙场景。在 OpenHarmony 应用开发中存在使用仓颉与 JavaScript 混合开发的诉求README 中给出了两类典型场景场景一仓颉应用调用 JavaScript 库。在使用仓颉开发时通过跨语言互操作调用 JavaScript 库复用 JavaScript 丰富的库生态。场景二JavaScript 回调仓颉代码模块。在使用 JavaScript 开发时通过跨语言互操作调用仓颉开发的代码模块发挥仓颉高性能高并发优势提升应用性能体验。目前仅支持仓颉调用 JavaScript 后回调仓颉即回调必须发生在仓颉侧主动发起 JS 调用的链路中。从 src 的源码文件划分可以看到库的能力边界runtime.cj 负责运行时context.cj 负责上下文与对象工厂function.cj 负责回调script.cj 负责脚本与代码缓存array.cj、map.cj、object.cj、string.cj、value.cj 分别实现各类互操作数据类型napi_cffi.cj 则封装了与 C 层的互操作接口。二、系统架构解析2.1 接口层面向开发者的 API架构图上半部分即接口层互操作库ark_interop / js_interop对外暴露五类核心抽象JSRuntime表示 JavaScript 运行时实例。每个 JavaScript 运行时对应一个 JSRuntime 实例提供创建 JSRuntime 的方法以及获取与该 JSRuntime 关联的执行上下文 JSContextJSContext表示与一个 JSRuntime 关联的执行上下文保存了全局对象并提供模块加载、JSValue 访问等相关方法JSCallInfo表示 JavaScript 调用仓颉方法时的调用信息主要用于获取参数数量和参数列表JSCodeCache表示一段 JavaScript 代码的缓存主要用于加速下次编译JSValue表示一个 JavaScript 对象用于封装和传递 JavaScript 数据对象。在仓颉侧需要获取 JSValue 中的值时需要使用 JSValue 提供的方法将其转换为具体类型的实例如 JSNumber、JSString、JSBoolean 等反之要把仓颉数据传递给 JavaScript 时可利用 JSContext 提供的方法将一个仓颉对象封装成 JSValue 实例。源码印证JSRuntime.create()在 src/runtime.cj#L57-L69 中实现它先执行全局初始化调用OH_JSVM_Init再创建独立的 libuv 事件循环最后通过OH_JSVM_CreateVM与OH_JSVM_OpenVMScope建立虚拟机实例与作用域。mainContext属性src/runtime.cj#L144-L160采用懒加载首次访问时通过OH_JSVM_CreateEnv创建环境并派生 JSContext且强制把 Context 创建任务投递到 JS 线程上执行。2.2 框架层六大核心能力架构图下半部分cangjie_js_interop 框架层实现了六项能力下面逐一说明并给出源码依据。1运行时管理提供创建 JavaScript 运行时的能力。从 src/runtime.cj 看JSRuntime内部持有JSVM_VM、JSVM_VMScope、UvLoop与destroyed原子布尔量。destroy()与析构函数~init()都通过compareAndSwap(false, true)保证只销毁一次避免重复释放底层资源此外还提供getHeapStat()查询 JSVM 堆统计信息。2跨语言函数调用两个方向的调用路径不同仓颉调用 JavaScript通过 C 语言互操作 JSVM 运行时接口。JSContext.evaluate()在 src/context.cj#L375-L385 中先OH_JSVM_CompileScript编译、再OH_JSVM_RunScript执行并可选传入代码缓存加速编译。JavaScript 调用仓颉通过互操作接口注册仓颉函数到 JS 运行时然后 JSVM 通过 C 语言互操作回调仓颉函数。核心在 src/function.cj#L69-L91 的C func jsFunctionCallbackStub它按 env 找回JSContext解析JSCallInfo参数列表、this 对象、lambdaId从sharedLambda_表中取出注册时的仓颉 lambda 执行并把返回的JSValue交回 JSVM。被注册函数的类型签名为(JSContext, JSCallInfo) - JSValue。3跨语言类型转换互操作库提供 JSUndefined、JSNull、JSBoolean、JSNumber、JSString、JSObject、JSArray、JSMap、JSFunction 等类型并实现 JavaScript 类型与仓颉类型的相互转换。src/napi_cffi.cj#L78-L107 定义了与 C 层一一对应的JSVM_ValueType枚举undefined、null、boolean、number、string、symbol、object、function、external、bigint互操作库即基于它完成双向类型判别。完整的类型映射与当前支持情况见下文的类型映射表。4跨语言异常处理仓颉调用 JavaScript 方向JS 代码中出现异常而未捕获时转换为仓颉异常传播到仓颉侧。实现见 src/runtime.cj#L122-L142 的checkAndHandleError当 JSVM 返回错误且存在 pending exception 时调用OH_JSVM_GetAndClearLastException取出错误对象并读取其stack属性把 JS 异常堆栈转成仓颉Exception抛出。JavaScript 调用仓颉方向仓颉代码中未捕获的异常转换为 JS 异常。src/function.cj#L54-L67 的throwExceptionToJS会把仓颉异常消息与堆栈拼接成Cangjie ...形式的错误文本通过OH_JSVM_ThrowError抛入 JS 运行时jsFunctionCallbackStub中的catch (exception: Exception)分支正是调用点随后返回undefined结束本次回调。5跨语言引用管理提供安全引用机制在仓颉侧使用仓颉对象映射 JavaScript 运行时对象保证该 JavaScript 对象在跨语言调用期间不会被垃圾回收。源码中有两层保障弱引用scope 内有效newScope底层调用OH_JSVM_OpenHandleScope/OH_JSVM_CloseHandleScope见 src/context.cj#L123-L144 的createScopesscope 内的JSValue、JSBoolean、JSNumber等弱引用在 scope 关闭后失效。强引用跨 scope 有效JSString、JSObject、JSArray、JSMap、JSFunction统一继承自JSHeapObject见 src/heap.cj#L9-L28其构造时调用OH_JSVM_CreateReference创建强引用释放时统一通过releaseRefs调用OH_JSVM_DeleteReference删除JSContext会把待删除的 ref 收集到toDeleteRefs_并投递到 JS 线程异步释放见 src/context.cj#L81-L113。6跨语言线程协同仓颉提供用户态线程运行时将仓颉线程调度到系统线程上执行因此仓颉默认不绑定特定系统线程而仓颉与 JavaScript 的互操作逻辑要求运行在 JavaScript 运行时绑定的系统线程上互操作库因此提供了切换到 JavaScript 线程执行的能力。从 src/uv.cj 源码看每个JSRuntime私有地持有一个基于 libuv 的事件循环UvLoopUvLoop.newLoop()通过uv_thread_create创建独立系统线程运行uv_run并通过uv_async机制uv_async_send向该线程投递任务。JSContext.newScopesrc/context.cj#L174-L202内部会先判断当前是否已在 JS 线程是则直接执行任务否则把任务postJSTask到 JS 线程同步等待结果并异常安全地把错误消息带回原线程重新抛出。这就是跨语言线程协同的具体实现——开发者写业务代码时无需关心线程切换库自动保证 JSVM 调用发生在正确线程上。2.3 依赖组件JSVM-API架构图底部的依赖部件为 JSVM-API它提供调用 JavaScript 虚拟机接口的能力互操作功能通过 C 语言互操作调用 JSVM 提供的接口完成。在 src/napi_cffi.cj 中可以看到OH_JSVM_CreateVM、OH_JSVM_CompileScript、OH_JSVM_CreateReference等全部 C 接口声明以及JSVM_Value、JSVM_Ref、JSVM_HandleScope、JSVM_Status25 种状态码如JSVM_OK、JSVM_PENDING_EXCEPTION、JSVM_WOULD_DEADLOCK等 CFFI 结构定义这是整个互操作库与 JSVM 之间的唯一底层通道。三、目录结构与编译构建3.1 目录结构Cangjie/cangjie_js_interop ├── src # 仓颉互操作库 ├── doc # 互操作库文档 ├── figures # 本README需要使用的图片3.2 构建准备开发者需要 Linux 平台的cangjie SDK然后执行对应 SDK 的envsetup脚本确保 SDK 被正确配置。约束目前仅支持在 Linux 平台编译和使用并且仅支持仓颉编译器的 cjnative 后端。3.3 构建步骤克隆本项目。通过根目录下的 cjpm.toml 编译仓颉-JavaScript 互操作库cjpm build --release当前支持debug、release两种编译类型开发者需要通过--release或者--debug指定。默认安装到target目录下支持开发者通过--target-dir指定安装目录。当前编译产物目录结构为target/ └── release └── js_interop ├── incremental-cache.json ├── js_interop.cjo └── libjs_interop.so结合 cjpm.toml 可以进一步理解这些构建参数的具体含义name js_interop、output-type dynamic库以动态库形式产出对应产物中的libjs_interop.sojs_interop.cjo则是仓颉侧的编译产物cjc-version 0.53.21声明了所使用的仓颉编译器版本构建前 SDK 需匹配该版本[target.aarch64-linux-ohos]中配置了compile-option通过-B、-L、--sysroot引用DEVECO_CANGJIE_HOME、DEVECO_OH_NATIVE_HOME等环境变量指向的 OHOS sysroot 与第三方库路径bin-dependencies再注入AARCH64_LIBS、AARCH64_MACRO_LIBS、AARCH64_KIT_LIBS三个库路径变量——这也是仅支持 Linux 平台、面向 OpenHarmony 场景在构建配置上的直接体现[profile]中开启增量编译incremental true对应产物里的incremental-cache.json并给出两档优化选项debug 为-g -Woff allrelease 为--fast-math -O2 -s -Woff all。四、实战在 OpenHarmony 应用中使用互操作库4.1 工程接入步骤用户手册doc/js_interop_user_manual.md给出了在 DevEco 中接入的完整流程创建仓颉工程DevEco 新建项目选择仓颉应用将互操作库代码复制到工程的顶层目录下在src-main-cangjie-cjpm.toml文件中添加依赖... [dependencies.tpc] path ../../../../TPC-HMOS-feature_js_interop version 1.0.0 ...在src-main-cangjie下新建仓颉文件例如test.cj写入互操作代码修改src-main-cangjie-index.cj在按钮事件中调用你的互操作函数... evt message test() ...编译运行后点击按钮即可看到 JS 侧计算的结果。4.2 准备互操作环境无论做哪类互操作操作都先完成三步固有工作通过JSRuntime的create函数创建JSRuntime实例通过JSRuntime实例的mainContext属性获取JSContext实例在JSContext实例的newScope函数内通过JSContext的函数接口进行一系列跨语言互操作。需要注意两点不同的JSRuntime实例中数据互相隔离在newScope内创建的跨语言弱引用不能跨 scope 使用只有跨语言强引用可以见 4.4 生命周期说明。4.3 场景一仓颉应用中调用 JavaScript完整示例如下其中第 13~15 行即为被调用的 JS 代码package ohos_app_cangjie_entry import js_interop.* func test() { // 创建JS运行时 let runtime JSRuntime.create() // 获取互操作上下文 let context runtime.mainContext context.newScope { // 加载JS代码到JS运行时 context.evaluate( function addNumber(a, b) { return a b; } ) // 获取加载至全局的JS函数 let addNumber context.global[addNumber].asFunction() // 调用JS函数 let result addNumber.globalCall([1, 2]) let retValue result.toNumberInt64() return 1 2 ${retValue} } }调用链在源码中的对应关系context.evaluate(...)走OH_JSVM_CompileScriptOH_JSVM_RunScriptsrc/context.cj#L375-L385context.global通过OH_JSVM_GetGlobal取出全局对象并包装为JSObjectsrc/context.cj#L234-L242[addNumber].asFunction()把全局属性转为JSFunctionglobalCall([1, 2])见 src/function.cj#L168toNumberInt64()见 src/value.cj#L364。evaluate的行为要点它可接受任意 JavaScript 代码解释执行并把执行返回值作为JSValue返回执行中的 JavaScript 报错和异常会被转换为仓颉异常抛出代码中若存在全局变量定义和函数声明会被放入当前JSContext的全局对象供后续使用且被依赖的数据必须先执行或创建过。4.4 场景二仓颉调用 JavaScript 后回调仓颉互操作库支持仓颉函数被 JavaScript 代码回调步骤是声明被调用的仓颉函数函数类型必须是(JSContext, JSCallInfo) - JSValue。在函数实现中通过JSCallInfo获取 this 对象和参数列表执行完仓颉语句后创建JSValue返回完成准备互操作环境三步在newScope内通过JSObject实例可以是全局对象或用户创建的对象的[]函数把仓颉函数注册到JSContext中在newScope内通过evaluate调用注册的仓颉函数或通过JSObject[]取属性 →asFunction→call/globalCall调用。完整示例第 14 行即为被调用的仓颉代码package ohos_app_cangjie_entry import js_interop.* // 定义被调用接口 func addNumber(context: JSContext, callInfo: JSCallInfo): JSValue { // 从JSCallInfo获取参数列表 let arg0: JSValue callInfo[0] let arg1: JSValue callInfo[1] // 把JSValue转换为仓颉类型 let a: Float64 arg0.toNumberFloat64() let b: Float64 arg1.toNumberFloat64() // 实际仓颉函数行为 let value a b // 把结果转换为JSValue let result: JSValue context.number(value).toJSValue() // 返回JSValue return result } func test() { // 创建JS运行时 let runtime JSRuntime.create() // 获取互操作上下文 let context runtime.mainContext context.newScope { // 注册到global即全局对象 context.global[add] context.function(addNumber) // 从仓颉侧执行JS的调用代码 let retValue context.evaluate(add(1, 2)).toNumberInt64().toString() return 1 2 ${retValue} } }当被调用的仓颉函数发生异常时该异常会被转换为 JavaScript 异常并抛到 JavaScript 运行时中然后被转换为仓颉异常抛出——这条仓颉异常 → JS 异常 → 仓颉异常的往返路径正是 2.2 节throwExceptionToJS与checkAndHandleError两处实现共同构成的。JSCallInfo的解析过程可参考 src/function.cj#L16-L39通过OH_JSVM_GetCbInfo一次性取出参数量、参数数组、this 对象和 lambdaId再包装为仓颉侧的args与thisArg。4.5 创建与操作 JavaScript 对象在newScope内可通过JSContext的工厂方法创建 JavaScript 对象并得到引用它们的仓颉对象number、array、object、map等实现见 src/context.cj#L252-L361底层对应OH_JSVM_CreateInt32、OH_JSVM_CreateArrayWithLength、OH_JSVM_CreateObject、OH_JSVM_CreateMap等 C 接口。创建之后可按对象类型进行元素级操作func test() { let runtime JSRuntime.create() let context runtime.mainContext context.newScope { // 创建Number对象 let v1 context.number(Int32(1)) let v2 context.number(2.9) let v3 context.number(UInt32(3)) // 创建Array对象 let array context.array([v1, v2, v3, s]) // 操作Array对象 array[10] 10 array.deleteAt(0) // 创建Object对象 let object context.object() // 操作Object对象 object[1] context.number(1) // 创建Map对象 let map context.map([(1, 1), (v2, 2), (object, obj)]) // 操作Map对象 map[1] array map.deleteKey(1) } }此外执行 JS 代码示例还可把仓颉函数伪装为console.log注入全局对象直观验证双向调用与异常传播func test() { let runtime JSRuntime.create() let context runtime.mainContext context.newScope { // 创建console.log函数 context.global[console] context.object([ (log, context.function { context, info let message info.args[0].toString() Hilog.info(0, console.log, message) context.undefined() }) ]) // 执行JS代码 context.evaluate(console.log(hello, world!)) context.evaluate(console.log1(hello, world!)) // JS异常传播到仓颉抛出log1不存在 } }4.6 类型映射表JavaScript 类型仓颉引用typeof 类型支持情况UndefinedJSUndefinedJSType.UNDEFINED已支持NullJSNullJSType.NULL已支持BooleanJSBooleanJSType.BOOLEAN已支持NumberJSNumberJSType.NUMBER已支持StringJSStringJSType.STRING已支持Symbol-JSType.SYMBOL暂不支持ObjectJSObjectJSType.OBJECT已支持ArrayJSArrayJSType.OBJECT已支持ArrayBuffer-JSType.OBJECT暂不支持Date-JSType.OBJECT暂不支持MapJSMapJSType.OBJECT已支持Set-JSType.OBJECT暂不支持Promise-JSType.OBJECT暂不支持RegExp-JSType.OBJECT暂不支持FunctionJSFunctionJSType.FUNCTION已支持Class-JSType.FUNCTION暂不支持--JSType.EXTERNAL暂不支持BigInt-JSType.BIGINT暂不支持4.7 互操作类型的生命周期对于 JavaScript 已支持的互操作类型都有仓颉类型与之对应这些仓颉类型的对象本质上是对 JavaScript 对象的引用。按引用方式不同生命周期分为两类跨语言弱引用持有 JavaScript 对象的弱引用不会阻止 JavaScript 对象被回收只在 scope 作用域内有效。对应类型JSValue、JSUndefined、JSNull、JSBoolean、JSNumber。跨语言强引用持有 JavaScript 对象的强引用保证 JavaScript 对象不会被回收可以跨 scope 作用域使用在上下文存活期间有效。对应类型JSString、JSObject、JSArray、JSMap、JSFunction。这些强引用类型统一继承自JSHeapObjectsrc/heap.cj进行生命周期管理。4.8 代码缓存加速编译evaluate函数可选传入一段代码缓存来加速编译调用evaluate时可选择性传入代码缓存缓存可通过createCodeCache创建当传入代码和代码缓存校验一致时使用缓存加速编译否则直接编译代码。从 src/script.cj 源码看JSScript.createCodeCache()调用OH_JSVM_CreateCodeCache产出JSCodeCache一段原始字节缓冲 长度JSScriptBuilder还提供更细粒度的编译控制包括setCompileMode、setCompileCache/setNoneCache、setEnableSourceMap、setOrigin设置脚本源与行列偏移等对应 JSVM 的JSVM_CompileOptions机制。五、开源协议与相关资源开源协议本项目基于 Apache-2.0 with Runtime Library Exception 和 Attribution 4.0 International。相关仓arkcompiler_jsvmOpenHarmony 的 JavaScript 虚拟机互操作库通过其 JSVM-API 完成底层调用。文档入口互操作 API 参考见 doc/js_interop_api_docs.md包含FromJSValue、ToJSValue、JSKeyable等接口以及 JSContext、JSValue、JSFunction、JSCallInfo 等全部 API 的参数与返回值说明使用指导见 doc/js_interop_user_manual.md。贡献方式欢迎贡献代码、文档具体流程参见仓颉社区的参与贡献文档。六、总结cangjie_js_interop 以JSRuntime / JSContext / JSCallInfo / JSCodeCache / JSValue五个接口层抽象配合框架层的运行时管理、双向函数调用、类型转换、异常转换、引用管理和线程协同六大能力把仓颉与 JavaScript 的互操作封装成创建运行时 → 获取上下文 → 进入 newScope → 自由读写的简洁范式。开发者在当前版本中需要牢记三条约束仅支持 Linux 平台编译使用、仅支持 cjnative 后端、且开放接口仅面向 OpenHarmony 场景其中 JavaScript 侧回调仓颉目前仅限仓颉调用 JS 后回调这一链路。在掌握类型映射与弱/强引用生命周期规则后即可按本文第四节的可复制示例在 OpenHarmony 应用中落地仓颉 JavaScript 的混合开发。赞分享OpenHarmony【免费下载链接】cangjie_js_interop项目地址https://gitcode.com/Cangjie/cangjie_js_interop点击查看免费下载相关推荐鸿蒙跨语言开发实战仓颉与ArkTS互操作全指南鸿蒙跨语言开发实战仓颉与ArkTS互操作全指南 你还在为鸿蒙应用开发中跨语言调用难题困扰本文将通过19 CangjiexArkTS示例项目系统讲解仓颉C示例工程cangjie_python_interop 仓颉-Python 互操作库跨语言桥接能力与源码级实战指南cangjie_python_interop 仓颉 Python 互操作库跨语言桥接能力与源码级实战指南 本文围绕 cangjie_python_intero开发工具cangjie_python_interop仓颉-Python 互操作库的架构、构建与使用指南cangjie_python_interop仓颉 Python 互操作库的架构、构建与使用指南 cangjie_python_interop仓颉 Pytho开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考