Cangjie/cangjie_js_interop 类型映射全解析JSValue 与仓颉类型互转速查手册【免费下载链接】cangjie_js_interop项目地址: https://gitcode.com/Cangjie/cangjie_js_interopCangjie/cangjie_js_interop仓颉与 JavaScript 互操作库为仓颉调用 JavaScript 提供了跨语言调用的完整能力其中JSValue 类型映射与互转是所有跨语言数据流动的核心JS 侧的number、string、object……到了仓颉侧分别由谁承接、用什么方法转换、能存活多久这篇全解析给出可直接对照的速查手册 。git clone https://gitcode.com/Cangjie/cangjie_js_interop为什么类型映射是互操作的核心 仓颉调用 JavaScript 时两边类型并不长得一样JS 侧的类型需要仓颉侧的对应引用来承接跨语言传参和回调也依赖明确的对照关系。互操作库为此做了三件事为每种已支持的 JS 类型提供对应的仓颉引用类型提供统一的JSValue 类型映射体系做类型判断与转换按弱引用 / 强引用两类管理跨语言对象的生命周期。理解这三层基本就掌握了整库的使用逻辑。完整类型映射表一眼看懂对照关系下表整理自官方用户手册建议收藏对照使用js_interop_user_manual.mdJS 类型仓颉引用类型typeof类型支持情况UndefinedJSUndefinedJSType.UNDEFINED✅ 已支持NullJSNullJSType.NULL✅ 已支持BooleanJSBooleanJSType.BOOLEAN✅ 已支持NumberJSNumberJSType.NUMBER✅ 已支持StringJSStringJSType.STRING✅ 已支持ObjectJSObjectJSType.OBJECT✅ 已支持ArrayJSArrayJSType.OBJECT✅ 已支持MapJSMapJSType.OBJECT✅ 已支持FunctionJSFunctionJSType.FUNCTION✅ 已支持Symbol—JSType.SYMBOL⏳ 暂不支持ArrayBuffer / Date / Set / Promise / RegExp / Class / BigInt—对应JSType枚举⏳ 暂不支持 速记口诀9 种已支持三小强String、Object 系、Function可跨作用域其余只在作用域内有效。强引用还是弱引用决定值的寿命⏳同样是 JS 数据引用方式不同生命周期差别很大跨语言弱引用JSValue、JSUndefined、JSNull、JSBoolean、JSNumber——不阻止 JS 对象被回收只在scope作用域内有效跨语言强引用JSString、JSObject、JSArray、JSMap、JSFunction——统一继承自JSHeapObject做生命周期管理可跨scope使用在上下文存活期间有效。⚠️ 实战要点如果你要把值留给 JS 回调的仓颉函数JSLambda稍后使用请优先选择强引用类型否则可能拿到已被回收的对象。JSValue互转枢纽的三族方法 JSValue是 JavaScript 统一类型在仓颉侧的弱引用表示直接参与数据交互。它的实现位于 value.cj方法可分为三族①is族 —— 判断类型不转换isUndefined()、isNull()、isNullOrUndefined()、isBoolean()、isNumber()、isString()、isArray()、isObject()、isFunction()、isMap()、isSymbol()、isBigInt()、isPromise()、isExternal()②as族 —— 转为引用类型asUndefined()、asNull()、asBoolean()、asNumber()、asString()、asObject()、asArray()、asMap()、asFunction()③to族 —— 取出仓颉原生类型toBool()→Bool、toString()→String、toNumberFloat64()→Float64、toNumberInt32()→Int32、toNumberInt64()→Int64、toNumberUint32()→UInt32另有typeOf()返回具体的JSVM_ValueType枚举。互转方向速查表JS → 仓颉 与 仓颉 → JS ⚡JS → 仓颉拿到 JS 值后按三步走判断 → 取引用 → 取原生值场景转换路径JS 数字 → 仓颉整数value.isNumber()→asNumber()→toNumberInt64()JS 数字 → 仓颉浮点value.asNumber()→toNumberFloat64()JS 字符串 → 仓颉字符串value.asString()→toString()JS 布尔 → 仓颉布尔value.asBoolean()→toBool()JS 数组 → 逐元素处理value.asArray()→array[i]继续判断JS 函数 → 直接调用value.asFunction()→globalCall([...])仓颉 → JS统一走JSContext工厂方法详见 context.cj仓颉值创建方法得到的 JS 类型Int32 / Int64 / UInt32 / Float64context.number(…)NumberStringcontext.string(…)StringBoolcontext.boolean(…)BooleanArrayToJSValuecontext.array(…)Array键值对集合context.object(…)/context.map(…)Object / Map(JSContext, JSCallInfo) - JSValue函数context.function(…)Function特殊值context.undefined()/context.null()Undefined / Null所有实现了ToJSValue接口的仓颉类型包括JSValue本身都能调用toJSValue(context)完成封装写入JSObject/JSArray属性时会自动转换非常顺手 ✨。两个最常踩的坑 ⚠️弱引用别跨作用域传JSValue等弱引用类型出newScope后可能失效需要长期持有的数据先as成强引用类型转换前先判断as/to族在类型不符时会抛异常建议先用is族确认类型或配合typeOf()排查再执行转换。延伸阅读与源码索引 类型映射与生命周期规格js_interop_user_manual.md全部 API 参考js_interop_api_docs.md各类型映射实现源码value.cj、array.cj、map.cj、object.cj、string.cj、function.cj掌握这份 JSValue 与仓颉类型映射速查手册后跨语言互转基本可以查表即用。祝开发顺利 【免费下载链接】cangjie_js_interop项目地址: https://gitcode.com/Cangjie/cangjie_js_interop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考