• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用Node-API实现跨语言交互开发流程
2
3
4使用Node-API实现跨语言交互，首先需要按照Node-API的机制实现模块的注册和加载等相关动作。
5
6
7- **ArkTS/JS侧**：实现C++方法的调用。代码比较简单，import一个对应的so库后，即可调用C++方法。
8
9- **Native侧**：.cpp文件，实现模块的注册。需要提供注册lib库的名称，并在注册回调方法中定义接口的映射关系，即Native方法及对应的JS/ArkTS接口名称等。
10
11
12此处以在ArkTS/JS侧实现add()接口、在Native侧实现Add()接口，从而实现跨语言交互为例，呈现使用Node-API进行跨语言交互的流程。
13
14
15## 创建Native C++工程
16
17- 在DevEco Studio中**New > Create Project**，选择**Native C++**模板，点击**Next**，选择API版本，设置好工程名称，点击**Finish**，创建得到新工程。
18
19- 创建工程后工程结构可以分两部分，cpp部分和ets部分，工程结构具体介绍可见<!--RP1-->[C++工程目录结构](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-project-structure-V5)<!--RP1End-->。
20
21
22## Native侧方法的实现
23
24- 设置模块注册信息
25
26  ArkTS侧import native模块时，会加载其对应的so。加载so时，首先会调用napi_module_register方法，将模块注册到系统中，并调用模块初始化函数。
27
28  napi_module有两个关键属性：一个是.nm_register_func，定义模块初始化函数；另一个是.nm_modname，定义模块的名称，也就是ArkTS侧引入的so库的名称，模块系统会根据此名称来区分不同的so。
29
30  ```
31  // entry/src/main/cpp/hello.cpp
32
33  // 准备模块加载相关信息，将上述Init函数与本模块名等信息记录下来。
34  static napi_module demoModule = {
35      .nm_version = 1,
36      .nm_flags = 0,
37      .nm_filename = nullptr,
38      .nm_register_func = Init,
39      .nm_modname = "entry",
40      .nm_priv = nullptr,
41      .reserved = {0},
42  };
43
44  // 加载so时，该函数会自动被调用，将上述demoModule模块注册到系统中。
45  extern "C" __attribute__((constructor)) void RegisterDemoModule() {
46      napi_module_register(&demoModule);
47   }
48  ```
49
50- 模块初始化
51
52  实现ArkTS接口与C++接口的绑定和映射。
53
54  ```
55  // entry/src/main/cpp/hello.cpp
56  EXTERN_C_START
57  // 模块初始化
58  static napi_value Init(napi_env env, napi_value exports) {
59      // ArkTS接口与C++接口的绑定和映射
60      napi_property_descriptor desc[] = {
61          {"callNative", nullptr, CallNative, nullptr, nullptr, nullptr, napi_default, nullptr},
62          {"nativeCallArkTS", nullptr, NativeCallArkTS, nullptr, nullptr, nullptr, napi_default, nullptr},
63      };
64      // 在exports对象上挂载CallNative/NativeCallArkTS两个Native方法
65      napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
66      return exports;
67  }
68  EXTERN_C_END
69
70  // 模块基本信息
71  static napi_module demoModule = {
72      .nm_version = 1,
73      .nm_flags = 0,
74      .nm_filename = nullptr,
75      .nm_register_func = Init,
76      .nm_modname = "entry",
77      .nm_priv = nullptr,
78      .reserved = {0},
79  };
80  ```
81
82- 在index.d.ts文件中，提供JS侧的接口方法。
83
84  ```
85  // entry/src/main/cpp/types/libentry/index.d.ts
86  export const callNative: (a: number, b: number) => number;
87  export const nativeCallArkTS: (cb: (a: number) => number) => number;
88  ```
89
90- 在oh-package.json5文件中将index.d.ts与cpp文件关联起来。
91
92  ```
93  {
94    "name": "libentry.so",
95    "types": "./index.d.ts",
96    "version": "",
97    "description": "Please describe the basic information."
98  }
99  ```
100
101- 在CMakeLists.txt文件中配置CMake打包参数。
102
103  ```
104  # entry/src/main/cpp/CMakeLists.txt
105  cmake_minimum_required(VERSION 3.4.1)
106  project(MyApplication2)
107
108  set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})
109
110  include_directories(${NATIVERENDER_ROOT_PATH}
111                      ${NATIVERENDER_ROOT_PATH}/include)
112
113  # 添加名为entry的库
114  add_library(entry SHARED hello.cpp)
115  # 构建此可执行文件需要链接的库
116  target_link_libraries(entry PUBLIC libace_napi.z.so)
117  ```
118
119- 实现Native侧的CallNative以及NativeCallArkTS接口。具体代码如下：
120
121  ```
122  // entry/src/main/cpp/hello.cpp
123  static napi_value CallNative(napi_env env, napi_callback_info info)
124  {
125      size_t argc = 2;
126      // 声明参数数组
127      napi_value args[2] = {nullptr};
128
129      // 获取传入的参数并依次放入参数数组中
130      napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
131
132      // 依次获取参数
133      double value0;
134      napi_get_value_double(env, args[0], &value0);
135      double value1;
136      napi_get_value_double(env, args[1], &value1);
137
138      // 返回两数相加的结果
139      napi_value sum;
140      napi_create_double(env, value0 + value1, &sum);
141      return sum;
142  }
143
144  static napi_value NativeCallArkTS(napi_env env, napi_callback_info info)
145  {
146      size_t argc = 1;
147      // 声明参数数组
148      napi_value args[1] = {nullptr};
149
150      // 获取传入的参数并依次放入参数数组中
151      napi_get_cb_info(env, info, &argc, args , nullptr, nullptr);
152
153      // 创建一个int，作为ArkTS的入参
154      napi_value argv = nullptr;
155      napi_create_int32(env, 2, &argv );
156
157      // 调用传入的callback，并将其结果返回
158      napi_value result = nullptr;
159      napi_call_function(env, nullptr, args[0], 1, &argv, &result);
160      return result;
161  }
162  ```
163
164
165## ArkTS侧调用C/C++方法实现
166
167ArkTS侧通过import引入Native侧包含处理逻辑的so来使用C/C++的方法。
168
169```
170// entry/src/main/ets/pages/Index.ets
171// 通过import的方式，引入Native能力。
172import nativeModule from 'libentry.so'
173
174@Entry
175@Component
176struct Index {
177  @State message: string = 'Test Node-API callNative result: ';
178  @State message2: string = 'Test Node-API nativeCallArkTS result: ';
179  build() {
180    Row() {
181      Column() {
182        // 第一个按钮，调用add方法，对应到Native侧的CallNative方法，进行两数相加。
183        Text(this.message)
184          .fontSize(50)
185          .fontWeight(FontWeight.Bold)
186          .onClick(() => {
187            this.message += nativeModule.callNative(2, 3);
188            })
189        // 第二个按钮，调用nativeCallArkTS方法，对应到Native的NativeCallArkTS，在Native调用ArkTS function。
190        Text(this.message2)
191          .fontSize(50)
192          .fontWeight(FontWeight.Bold)
193          .onClick(() => {
194            this.message2 += nativeModule.nativeCallArkTS((a: number)=> {
195                return a * 2;
196            });
197          })
198      }
199      .width('100%')
200    }
201    .height('100%')
202  }
203}
204```
205
206
207## Node-API的约束限制
208
209
210### SO命名规则
211
212导入使用的模块名和注册时的模块名大小写保持一致，如模块名为entry，则so的名字为libentry.so，napi_module中nm_modname字段应为entry，ArkTS侧使用时写作：import xxx from 'libentry.so'。
213
214
215### 注册建议
216
217- nm_register_func对应的函数（如上述Init函数）需要加上static，防止与其他so里的符号冲突；
218
219- 模块注册的入口，即使用__attribute__((constructor))修饰的函数的函数名（如上述RegisterDemoModule函数）需要确保不与其它模块重复。
220
221
222### 多线程限制
223
224每个引擎实例对应一个JS线程，实例上的对象不能跨线程操作，否则会引起应用crash。使用时需要遵循如下原则：
225
226- Node-API接口只能在JS线程使用。
227
228- Native接口入参env与特定JS线程绑定只能在创建时的线程使用。
229