Cocos2d-x 鸿蒙：ArkTS 与 C++ 双向交互｜默然的博客

1. 适用范围与结论

本文分析的是一个将 ArkTS 和 C++ 引擎编进同一 libnativerender.so 的 Cocos2d-x 鸿蒙工程。代码中的 ContextType、NapiManager、JSFunction 和异步结果表属于该工程的封装，不代表所有 HarmonyOS NAPI 项目都必须采用同样结构。

这套交互可以拆成两个方向：ArkTS 通过 getContext(type) 获取 C++ 函数表；C++ 通过预先注册并保存的 napi_ref 回调 ArkTS。同步调用链清晰可控，异步封装则必须额外处理线程、Promise 完成时机和 napi_env 的使用边界。

2. 原理

ArkTS 和 C++ 引擎被编进同一个动态库 libnativerender.so，通过 NAPI(Node-API) 互调。交互只有两个方向，各靠一张”表”：

方向	机制	入口
TS → C++	getContext(type) 返回 C++ 函数表	plugin_manager.cpp
C++ → TS	registerFunction 把 JS 函数存入 回调引用表	JSRegisterUtils.h / NapiHelper.h

2.1 模块入口：整个库只导出一个 getContext 方法

此外，RegisterModule 没有被任何代码显式调用，它带 __attribute__((constructor))，在 libnativerender.so 被加载进进程时自动执行。

加载的触发点是 TS 侧 import ... from 'libnativerender.so'，以及 Index.ets 中 XComponent({ libraryname: 'nativerender' })。时序如下：

TS import / XComponent 引用库
        ↓ 运行时 dlopen 加载 .so
constructor RegisterModule()  →  napi_module_register(&nativerenderModule)
        ↓ NAPI 框架回调 nm_register_func
Init()  →  把 getContext 挂到 exports
        ↓
TS 得到 exports，可调用 getContext(...)

初始化入口：

// entry/src/main/cpp/napi_init.cpp
static napi_value Init(napi_env env, napi_value exports) {
    napi_property_descriptor desc[] = {
        // 唯一对 TS 暴露的入口
        DECLARE_NAPI_FUNCTION("getContext", NapiManager::GetContext),
    };
    NAPI_CALL(env, napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc));
    // 绑定 XComponent(渲染用，本文不展开)
    NapiManager::GetInstance()->Export(env, exports);
    return exports;
}

// → TS 里 import ... from 'libnativerender.so'
static napi_module nativerenderModule = {
    .nm_register_func = Init,
    .nm_modname = "nativerender",
    // ...
};

// C导出
// __attribute__((constructor)) 加载进进程时自动执行
extern "C" __attribute__((constructor)) void RegisterModule(void) {
    napi_module_register(&nativerenderModule);
}

3. ArkTS → C++（同步调用）

getContext(type) 按传入的枚举返回一组挂着 C++ 实现的函数（一张”分域函数表”），TS 拿到后直接 .xxx() 调用，同步进 C++。

举个例子：
MainAbility.ets中的：

import nativeRender from "libnativerender.so";
const rawFileUtils: nativeRender.CPPFunctions = nativeRender.getContext(ContextType.RAW_FILE_UTILS);

// 调用 nativeResourceManagerInit 方法
rawFileUtils.nativeResourceManagerInit(this.context.resourceManager);

C++ 分发实现在 plugin_manager.cpp
凡是 TS 主动调用的 C++ 普通函数，都必须在 NapiManager::GetContext 某个 case 的 desc[] 里用 DECLARE_NAPI_FUNCTION("名字", 实现) 注册，并在 index.d.ts 补一条类型声明。否则 getContext() 返回的对象上根本没有这个方法，TS 侧调不到（运行时 undefined）。

// NapiManager::GetContext(...)

switch (value) {
    case RAW_FILE_UTILS: {
        // 这里注册真实cpp调用方法：RawFileUtils::nativeResourceManagerInit
        napi_property_descriptor desc[] = {
            DECLARE_NAPI_FUNCTION("nativeResourceManagerInit", 
                RawFileUtils::nativeResourceManagerInit),
            //...
        };
        NAPI_CALL(env, napi_define_properties(env, exports, sizeof(desc)/sizeof(desc[0]), desc));
    } break;
    // ... 其它 case ...
}

TS 端的类型声明

// entry/src/main/cpp/types/libentry/index.d.ts
export interface CPPFunctions {
  nativeResourceManagerInit: (resourceManager: resmgr.ResourceManager) => void;
  // ...
}
export const getContext: (a: number) => CPPFunctions;

4. C++ → ArkTS（回调）

4.1 原理

启动时 TS 把”名字 → JS 函数”成对注册给 C++，C++ 用 napi_ref 存进一张 map；之后 C++ 随时按名字取出来调用。

4.2 注册入口

// src\main\ets\workers\CocosWorker.ets

import nativeRender from "libnativerender.so";
const napiContext: nativeRender.CPPFunctions = nativeRender.getContext(ContextType.NATIVE_API);
napiContext.nativeEngineStart();
NapiHelper.registerFunctions(napiContext.registerFunction)

4.3 ArkTS 端注册

所有供cpp调用的js方法都在这里：NapiHelper.ts

// libSysCapabilities/src/main/ets/napi/NapiHelper.ts
export class NapiHelper{
    static registerFunctions(registerFunc: Function){
        registerFunc('ApplicationManager.exit', ApplicationManager.exit);
        registerFunc('ApplicationManager.getVersionName', ApplicationManager.getVersionName);
        registerFunc('DeviceUtils.getDpi', DeviceUtils.getDpi);
        // ...
    }
}

4.4 C++ 端注册实现

// napi/helper/JSRegisterUtils.h
napi_value registerFunction(napi_env env, napi_callback_info info) {
    size_t argc = 2;
    // args[0]=名字(string), args[1]=JS 函数
    napi_value args[2];
    NAPI_CALL(env, napi_get_cb_info(env, info, &argc, args, nullptr, nullptr));

    // ... 读出 functionName ...
    napi_ref fucRef;
    // 持有 JS 函数引用
    NAPI_CALL(env, napi_create_reference(env, args[1], 1, &fucRef));

    char* name = new char[functionName.length() + 1];
    strcpy(name, functionName.c_str());
    JSFunction* jsFunction = new JSFunction(name, env, fucRef);
    // 存进 FUNCTION_MAP
    JSFunction::addFunction(name, jsFunction);
    return nullptr;
}

// napi/helper/NapiHelper.h

static std::unordered_map<std::string, JSFunction> FUNCTION_MAP;

static JSFunction getFunction(std::string functionName) {
    return FUNCTION_MAP.at(functionName);
}

// 有返回值版本
template<typename ReturnType, typename... Args>
ReturnType invoke(Args... args) {
    napi_value global;  napi_get_global(env, &global);
    
    napi_value func;
    // 取回 JS 函数
    napi_get_reference_value(env, funcRef, &func);
    // C++ 参数 → napi_value
    napi_value jsArgs[sizeof...(Args)] = {NapiValueConverter::ToNapiValue(env, args)...};
    napi_value return_val;
    // 调 JS
    napi_call_function(env, global, func, sizeof...(Args), jsArgs, &return_val);
    ReturnType value;
    // 返回值 napi_value → C++
    NapiValueConverter::ToCppValue(env, return_val, value);
    return value;
}
// void 版本同理，省略返回值转换

4.5 C++ 调用

std::string ver = JSFunction::getFunction("ApplicationManager.getVersionName").invoke<std::string>();
// invoke 内部用 NapiValueConverter::ToCppValue 把 JS 返回的 string 转回 std::string

5. C++ → ArkTS（异步）

napi_call_function 调一个返回 Promise 的 JS 函数时，拿到的是 promise 对象而不是结果，结果要等 .then 回调才有。NapiHelper.h 封装了一套：在后台子线程里把 Promise”拉平”，等到结果后落进一张异步表，供 C++ 之后按 key 取用。注意发起方 invokeAsync 起的是 detach 子线程，它立即返回、不阻塞调用线程；真正阻塞等待的是那个后台子线程。

5.1 注意点

1. 返回值类型只支持 number/string，字符串 ≤ 64 字节（replyString[64]）
2. 给 JS 只能传一个字符串入参（或无参）

5.2 invokeAsync/getAsyncInfo

invokeAsync / getAsyncInfo 这套在鸿蒙的仓库里其实没有任何业务调用点，initAsyncInfo 还是空实现。

个人此方案觉得不靠谱，invokeAsync后交给js跑异步了。getAsyncInfo需要等异步跑完来获取信息。由于没有回调，也没async/await 异步模型。至于什么时候才算异步跑完，鲁迅没说。全靠猜。

// 1) 在 AsyncInfo 枚举里加 key(保持 LAST_INDEX 在最后)
enum AsyncInfo { VERSION_NAME = 0, MY_RESULT, LAST_INDEX };

// 2) 发起(子线程异步等待,结果由 setAsyncInfo 写入 _asyncInfoMap)
JSFunction::getFunction("Xxx.getXxx").invokeAsync(AsyncInfo::MY_RESULT, "入参");

// 3) 确保 Promise 已完成后再读
std::string result = Js_Cocos2dxHelper::getAsyncInfo(AsyncInfo::MY_RESULT);

5.3 RunPromiseType

// 必须在【非 JS(env) 线程】上调用,否则死锁(见下方注意点 2)
std::string result;
// 已注册、返回 Promise 的 JS 函数
JSFunction fn = JSFunction::getFunction("Xxx.getXxx");

JSFunction::RunPromiseType(fn.env, fn.funcRef,[&result](std::string value) 
{
    // 执行完毕后回调
    result = value; 
}, "arg");  // 参数只能是字符串，无参数就传 ""
// (RunPromiseType 内部 condition.wait 一直阻塞到 successCallback 置 ready 才返回)

6. 常见问题

6.1 是否所有 native 方法都要加进 GetContext？

是。 凡是 TS 主动调用的 C++ 普通函数，都必须在 NapiManager::GetContext 某个 case 的 desc[] 里用 DECLARE_NAPI_FUNCTION("名字", 实现) 注册，并在 index.d.ts 补一条类型声明——否则 getContext() 返回的对象上不会有这个方法，TS 侧调到的是 undefined。

加到哪个 case 只是按 ContextType 分组：可挂到语义相近的已有 case，也可新增一个枚举值 + 新 case，与功能无关。

三个例外不走这里：

1. getContext 自身在 napi_init.cpp 顶层 Init 导出，不在 switch 内。
2. XComponent 渲染/触摸回调用 OH_NativeXComponent_RegisterCallback 注册，不是 DECLARE_NAPI_FUNCTION。
3. C++ → TS 的回调走 registerFunction，属于反方向。

7. 相关阅读

• Cocos2d-x Lua 与 C++ 交互
• Cocos2d-x Lua 与 Android Java 交互
• Cocos2d-x Lua 与 Objective-C 交互
• C# 与 C++ 的 P/Invoke 互操作