使用Node-API实现跨语言交互开发流程

作者：鸿蒙一哥
团队：坚果派
公众号：“大前端之旅”

团队介绍：坚果派由坚果创建，团队拥有12个华为HDE，以及若干其他领域的三十余位万粉博主运营。专注于分享的技术包括HarmonyOS/OpenHarmony，ArkUI-X，元服务，服务卡片，华为自研语言、BlueOS。团队成员聚集在北京，上海，南京，深圳，广州，宁夏等地，欢迎合作。

使用Node-API实现跨语言交互，首先需要按照Node-API的机制实现模块的注册和加载等相关动作。

• ArkTS/JS侧：实现C++方法的调用。代码比较简单，import一个对应的so库后，即可调用C++方法。
• Native侧：.cpp文件，实现模块的注册。需要提供注册lib库的名称，并在注册回调方法中定义接口的映射关系，即Native方法及对应的JS/ArkTS接口名称等。

此处以在ArkTS/JS侧实现add()接口、在Native侧实现Add()接口，从而实现跨语言交互为例，呈现使用Node-API进行跨语言交互的流程。

创建Native C++工程

• 在DevEco Studio中New > Create Project，选择Native C++**模板，点击**Next**，选择API版本，设置好工程名称，点击Finish**，创建得到新工程。
• 创建工程后工程结构可以分两部分，cpp部分和ets部分。

• entry > src > main > cpp > types：用于存放C++的API接口描述文件。
• entry > src > main > cpp > types > libentry > index.d.ts：描述C++ API接口行为，如接口名、入参、返回参数等。
• entry > src > main > cpp > types > libentry > oh-package.json5：配置.so三方包声明文件的入口及包名。
• entry > src > main > cpp > CMakeLists.txt：C++源码编译配置文件，提供CMake构建脚本。
• entry > src > main > cpp > hello.cpp：定义C++ API接口的文件。
• entry > src > main > ets：用于存放ArkTS源码。

Native侧方法的实现

• 设置模块注册信息

  ArkTS侧import native模块时，会加载其对应的so。加载so时，首先会调用napi_module_register方法，将模块注册到系统中，并调用模块初始化函数。

  napi_module有两个关键属性：一个是.nm_register_func，定义模块初始化函数；另一个是.nm_modname，定义模块的名称，也就是ArkTS侧引入的so库的名称，模块系统会根据此名称来区分不同的so。

  // 准备模块加载相关信息，将上述Init函数与本模块名等信息记录下来。
  static napi_module demoModule = {
      .nm_version = 1,
      .nm_flags = 0,
      .nm_filename = nullptr,
      .nm_register_func = Init,
      .nm_modname = "entry",
      .nm_priv = nullptr,
      .reserved = {0},
  };
  
  // 加载so时，该函数会自动被调用，将上述demoModule模块注册到系统中。
  extern "C" __attribute__((constructor)) void RegisterDemoModule() { napi_module_register(&demoModule); }
  

• 模块初始化

  实现ArkTS接口与C++接口的绑定和映射。

  EXTERN_C_START
  // 模块初始化
  static napi_value Init(napi_env env, napi_value exports) {
      // ArkTS接口与C++接口的绑定和映射
      napi_property_descriptor desc[] = {
          { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr },
      {"callNative", nullptr, CallNative, nullptr, nullptr, nullptr, napi_default, nullptr},
          {"nativeCallArkTS", nullptr, NativeCallArkTS, nullptr, nullptr, nullptr, napi_default, nullptr}
      };
      // 在exports对象上挂载CallNative/NativeCallArkTS两个Native方法
      napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
      return exports;
  }
  EXTERN_C_END
  

• 在index.d.ts文件中，提供JS侧的接口方法。

  
  // entry/src/main/cpp/types/libentry/index.d.ts
  export const callNative: (a: number, b: number) => number;
  export const nativeCallArkTS: (cb: (a: number) => number) => number;
  

• 在oh-package.json5文件中将index.d.ts与cpp文件关联起来。

  {
    "name": "entry",
    "version": "1.0.0",
    "description": "Please describe the basic information.",
    "main": "",
    "author": "",
    "license": "",
    "dependencies": {
      "libentry.so": "file:./src/main/cpp/types/libentry"
    }
  }
  

• 在CMakeLists.txt文件中配置CMake打包参数。

  # the minimum version of CMake.
  cmake_minimum_required(VERSION 3.4.1)
  project(nextnativ)
  
  set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})
  
  if(DEFINED PACKAGE_FIND_FILE)
      include(${PACKAGE_FIND_FILE})
  endif()
  
  include_directories(${NATIVERENDER_ROOT_PATH}
                      ${NATIVERENDER_ROOT_PATH}/include)
  
  add_library(entry SHARED hello.cpp)
  
  # 添加名为entry的库
  
  target_link_libraries(entry PUBLIC libace_napi.z.so)
  

• 实现Native侧的CallNative以及NativeCallArkTS接口。具体代码如下：

  static napi_value CallNative(napi_env env, napi_callback_info info) {
      size_t argc = 2;
      // 声明参数数组
      napi_value args[2] = {nullptr};
  
      // 获取传入的参数并依次放入参数数组中
      napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  
      // 依次获取参数
      double value0;
      napi_get_value_double(env, args[0], &value0);
      double value1;
      napi_get_value_double(env, args[1], &value1);
  
      // 返回两数相加的结果
      napi_value sum;
      napi_create_double(env, value0 + value1, &sum);
      return sum;
  }
  
  static napi_value NativeCallArkTS(napi_env env, napi_callback_info info) {
      size_t argc = 1;
      // 声明参数数组
      napi_value args[1] = {nullptr};
  
      // 获取传入的参数并依次放入参数数组中
      napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
  
      // 创建一个int，作为ArkTS的入参
      napi_value argv = nullptr;
      napi_create_int32(env, 2, &argv);
  
      // 调用传入的callback，并将其结果返回
      napi_value result = nullptr;
      napi_call_function(env, nullptr, args[0], 1, &argv, &result);
      return result;
  }
  

ArkTS侧调用C/C++方法实现

ArkTS侧通过import引入Native侧包含处理逻辑的so来使用C/C++的方法。

import { hilog } from '@kit.PerformanceAnalysisKit';

import nativeModule from 'libentry.so'

@Entry
@Component
struct Index {
  @State message: string = 'Test Node-API';
  @State message1: string = 'callNative result: ';
  @State message2: string = 'nativeCallArkTS result: ';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            // this.message=testNapi.add(2, 3).toString()
            hilog.info(0x0000, 'testTag', 'Test NAPI 2 + 3 = %{public}d', nativeModule.add(2, 3));
          })
        // 第一个按钮，调用add方法，对应到Native侧的CallNative方法，进行两数相加。
        Text(this.message1)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            this.message1 = nativeModule.callNative(2, 3).toString();
          })
        // 第二个按钮，调用nativeCallArkTS方法，对应到Native的NativeCallArkTS，在Native调用ArkTS function。
        Text(this.message2)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            this.message2 = nativeModule.nativeCallArkTS((a: number) => {
              return (a * 2);
            }).toString();
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

Node-API的约束限制

SO命名规则

导入使用的模块名和注册时的模块名大小写保持一致，如模块名为entry，则so的名字为libentry.so，napi_module中nm_modname字段应为entry，ArkTS侧使用时写作：import xxx from 'libentry.so'。

注册建议

• nm_register_func对应的函数（如上述Init函数）需要加上static，防止与其他so里的符号冲突；
• 模块注册的入口，即使用__attribute__((constructor))修饰的函数的函数名（如上述RegisterDemoModule函数）需要确保不与其它模块重复。

多线程限制

每个引擎实例对应一个JS线程，实例上的对象不能跨线程操作，否则会引起应用crash。使用时需要遵循如下原则：

• Node-API接口只能在JS线程使用。
• Native接口入参env与特定JS线程绑定只能在创建时的线程使用。

Node-API典型使用场景

• 使用Node-API接口进行异步任务开发
• 使用Node-API接口进行线程安全开发
• Native与ArkTS对象绑定
• 在非ArkTS线程中回调ArkTS接口
• 使用Node-API接口创建ArkTs运行时环境
• 使用Node-API接口在主线程中进行模块加载
• 使用Node-API接口进行模块加载

更多文章，见知识星球《跟着坚果派学鸿蒙》