03 NAPI 入门

第一部分：NAPI基本概念介绍

OpenHarmony 中的 NAPI（由Node.js N-API 框架扩展而来），是UI框架下ArkUI子系统的一部分， 用于通过 JS/ETS 语言编写的代码与 native 代码（C/C++ ）交互。NAPI适合封装IO、CPU密集型、OS底层等能力并对外暴露JS接口，通过NAPI可以实现JS（JavaScript）与C/C++代码互相访问。

1 JavaScript 、 TypeScript 和 ArkTS

TypeScript 是 JavaScript 的类型的超集，支持ES6语法，支持面向对象编程的概念，如类、接口、继承、泛型等，是一种静态类型检查的语言，提供了类型注解，在代码编译阶段就可以检查出数据类型的错误同时扩展了JavaScript 的语法，所以任何现有的JavaScript 程序可以不加改变的在 TypeScript 下工作为了保证兼容性，TypeScript 在编译阶段需要编译器编译成纯 JavaScript 来运行。TypeScript 文件的后缀名 .ts （.ts，.tsx，.d.ts），JavaScript 文件是 .js。

ArkTS 则是在TypeScript 基础上扩展一些功能，增加一些类似语法糖和"注解"作用的。

2 .ts 和.d.ts文件

.ts 文件包含实际的代码逻辑，用于编写 TypeScript 程序的实现，文件包含了变量、函数、类等 TypeScript 代码的定义和实现。在编译时.ts 文件将被转换为 JavaScript 文件，从而可以在浏览器或其他 JavaScript 运行环境中执行；而 .d.ts 文件是类型声明文件里面只有类型代码，没有具体的代码实现。它的文件名一般为[模块名].d.ts的形式，其中的d表示 declaration（声明），用于描述 JavaScript 代码在 TypeScript 中的类型信息。 从简而言之，.ts 文件是我们编写实际业务逻辑的地方，而 .d.ts 文件是用于提供类型声明的地方。

3 基础数据类型

NAPI框架，所有参数，无论是ECMAScript标准中定义的Boolean、Null、Undefined、Number、BigInt、String、Symbol和Object八种数据类型，还是Function类型，都已统一封装为napi_value类型，故可如获取数据类型的参数一样获取Function类型参数。

基本数据类型：

• napi_env 对应 NativeEngine 在 oh 中指 ArkComplier 中 JSNAPI 的相关上下文环境，任何 napi 数据类型和 js 数据类型的转换都需要用到它。
• napi_value 对应 NativeValue 在 oh 中指所有 ArkComplier 可识别的 js 数据类型，它有子类 ArkNativeNumber、ArkNativeString、ArkNativeFunction 等，对应 js 中的 number、string、function 等数据类型。
• napi_callback_info 对应 NativeCallbackInfo ，指注册 callback handle 时用来存放 js 传入参数信息的数据类型。它是一个 struct。
• napi_property_descriptor 是用来存放单个 property 的数据类型。
• napi_callback 对应 NativeCallback，即前面的 callback handle，native 代码将其注册为对应 js 接口的回调函数。

4 NAPI 对象生命周期

NAPI 对象的生命周期代表着从对象创建到释放的整个过程，如下图所示：

在 ArkTS 应用启动时会加载 NAPI 模块，而在 NAPI 模块加载过程中会创建一个对象 A 提供给应用使用，在应用退出或者主动释放 A 对象前，A 对象必须一直保持"活跃"状态。从 A 对象创建到释放的整个过程也代表着 A 对象的生命周期。

当调用 Node-API 时，底层虚拟机在堆中对象的句柄可能以 napi_values 的形式返回。这些句柄必须保持对象"活动"，直到本地代码不再需要它们。

5 同步接口和异步接口

同步接口在主线程中执行，可能会导致界面卡顿；异步接口在工作线程中执行，避免了主线程的阻塞。

概念	同步接口	异步接口
执行线程	主线程	工作线程
阻塞情况	会阻塞主线程	不会阻塞主线程
使用场景	简单任务	复杂任务、CPU密集型任务
实现复杂度	简单	复杂

异步接口使用napi_create_async_work函数创建异步工作项，并使用napi_queue_async_work函数将其加入调度队列。在Complete函数中处理异步结果，调用回调函数或更新Promise状态。

第二部分：NAPI常见函数

学习了NAPI的基础理论部分后，本小节再介绍几个在开发者使用频繁的几个函数。

1 napi_get_cb_info

功能说明：

napi_get_cb_info 是 Node.js N-API 中的一个核心函数，主要用于在原生插件（通常用 C/C++ 编写）中获取调用 JavaScript 函数时传递的参数信息、this 对象以及其他上下文数据。简单来说，它是原生代码与 JavaScript 交互的核心。

函数原型：

napi_status napi_get_cb_info(napi_env env,
                             napi_callback_info cbinfo,
                             size_t* argc,
                             napi_value* argv,
                             napi_value* this_arg,
                             void** data)

参数说明：

参数	类型 (C/C++)	方向（对函数而言）	描述
env	napi_env	输入	N-API 的环境句柄，提供了函数执行的上下文。
cbinfo	napi_callback_info	输入	回调信息句柄，通常由 Node.js 在调用原生函数时传入。
argc	size_t *	输入/输出	输入时表示期望获取的参数数量，输出时表示实际接收到的参数数量。
argv	napi_value *	输出	用于存储参数的数组。如果传入 nullptr，则不会复制参数，仅获取数量。
this_arg	napi_value *	输出	用于接收 JavaScript 中的 this 对象。
data	void **	输出	用于接收在创建函数时可能绑定的额外数据指针。

使用示例：

#include <node_api.h>

// 准备变量来获取参数和信息
size_t argc = 2; // 我们期望获取2个参数
napi_value argv[2]; // 准备一个数组来存放这两个参数
napi_value this_arg;
void* data;

// 调用 napi_get_cb_info 获取信息
status = napi_get_cb_info(env, info, &argc, argv, &this_arg, &data);
if (status != napi_ok) {
  // 处理错误...
}

2 napi_get_value_string_utf8

功能说明： 从 JavaScript 字符串值中提取 UTF-8 编码的 C 字符串。它将 JavaScript 字符串转换为 UTF-8 格式的字符数组，便于 C/C++ 代码处理。

函数原型：

napi_status napi_get_value_string_utf8(napi_env env,
                                       napi_value value,
                                       char* buf,
                                       size_t bufsize,
                                       size_t* result);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄，提供函数执行的上下文
value	napi_value	输入	要转换的 JavaScript 字符串值
buf	char*	输出	指向存储结果的缓冲区的指针（可为 NULL）
bufsize	size_t	输入	缓冲区的大小（以字节为单位）
result	size_t*	输出	可选参数，接收实际字符串长度（不包括空终止符）

使用示例：

napi_value js_string;
// ... 获取 JavaScript 字符串到 js_string ...

// 首先获取所需缓冲区大小
size_t length;
napi_get_value_string_utf8(env, js_string, NULL, 0, &length);

// 分配缓冲区（+1 用于空终止符）
char* buffer = (char*)malloc(length + 1);

// 实际获取字符串内容
napi_get_value_string_utf8(env, js_string, buffer, length + 1, NULL);

// 使用 buffer...
free(buffer);

3 napi_create_function

功能说明： 创建一个新的 JavaScript 函数对象，该函数在调用时会执行指定的 C/C++ 回调函数。

函数原型：

napi_status napi_create_function(napi_env env,
                                 const char* utf8name,
                                 size_t length,
                                 napi_callback cb,
                                 void* data,
                                 napi_value* result);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄
utf8name	const char*	输入	函数名称（UTF-8 编码）
length	size_t	输入	函数名称长度（使用 NAPI_AUTO_LENGTH 自动计算）
cb	napi_callback	输入	当 JavaScript 函数被调用时执行的原生回调函数
data	void*	输入	传递给回调函数的用户数据
result	napi_value*	输出	新创建的 JavaScript 函数对象

使用示例：

napi_value my_function;
napi_create_function(env, "myFunction", NAPI_AUTO_LENGTH, MyNativeFunction, NULL, &my_function);

4 napi_create_object

功能说明： 创建一个新的空 JavaScript 对象。

函数原型：

napi_status napi_create_object(napi_env env, napi_value* result);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄
result	napi_value*	输出	新创建的 JavaScript 对象

使用示例：

napi_value obj;
napi_create_object(env, &obj);

5 napi_create_string_utf8

功能说明： 从 UTF-8 编码的 C 字符串创建 JavaScript 字符串。

函数原型：

napi_status napi_create_string_utf8(napi_env env,
                                    const char* str,
                                    size_t length,
                                    napi_value* result);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄
str	const char*	输入	UTF-8 编码的 C 字符串
length	size_t	输入	字符串长度（使用 NAPI_AUTO_LENGTH 自动计算）
result	napi_value*	输出	新创建的 JavaScript 字符串

使用示例：

napi_value js_string;
napi_create_string_utf8(env, "Hello World", NAPI_AUTO_LENGTH, &js_string);

6 napi_set_named_property

功能说明： 给 JavaScript 对象设置一个命名属性。

函数原型：

napi_status napi_set_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8name,
                                    napi_value value);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄
object	napi_value	输入	要设置属性的 JavaScript 对象
utf8name	const char*	输入	属性名称（UTF-8 编码）
value	napi_value	输入	要设置的属性值

使用示例：

napi_value obj, value;
napi_create_object(env, &obj);
napi_create_string_utf8(env, "test", NAPI_AUTO_LENGTH, &value);
napi_set_named_property(env, obj, "propertyName", value);

7 napi_get_value_double

功能说明： 从 JavaScript 数字值中提取 C 双精度浮点数值。

函数原型：

napi_status napi_get_value_double(napi_env env, napi_value value, double* result);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄
value	napi_value	输入	JavaScript 数字值
result	double*	输出	提取的双精度浮点数值

使用示例：

double number;
napi_get_value_double(env, js_number_value, &number);

8 napi_typeof

功能说明： 确定 JavaScript 值的类型。

函数原型：

napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄
value	napi_value	输入	要检查的 JavaScript 值
result	napi_valuetype*	输出	值的类型（如 napi_number, napi_string 等）

使用示例：

napi_valuetype type;
napi_typeof(env, js_value, &type);
if (type == napi_number) {
    // 处理数字类型
}

9 napi_open_handle_scope / napi_close_handle_scope

功能说明： 管理 napi_value 句柄的生命周期，防止内存泄漏。

函数原型：

napi_status napi_open_handle_scope(napi_env env, napi_handle_scope* result);
napi_status napi_close_handle_scope(napi_env env, napi_handle_scope scope);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄
result	napi_handle_scope*	输出	新创建的作用域句柄
scope	napi_handle_scope	输入	要关闭的作用域句柄

使用示例：

napi_handle_scope scope;
napi_open_handle_scope(env, &scope);
// 在此作用域内创建 napi_value
napi_close_handle_scope(env, scope);

10 napi_throw_error

功能说明： 抛出 JavaScript 错误。

函数原型：

napi_status napi_throw_error(napi_env env, const char* code, const char* msg);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄
code	const char*	输入	错误代码（可为 NULL）
msg	const char*	输入	错误消息

使用示例：

napi_throw_error(env, NULL, "Something went wrong");

11 napi_create_int32

功能说明： 从 C int32_t 值创建 JavaScript 数字。

函数原型：

napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄
value	int32_t	输入	C 整数值
result	napi_value*	输出	新创建的 JavaScript 数字

使用示例：

napi_value js_number;
napi_create_int32(env, 42, &js_number);

12 napi_call_function

功能说明： 调用JavaScript函数。

函数原型：

napi_status napi_call_function(napi_env env,
                               napi_value recv,
                               napi_value func,
                               size_t argc,
                               const napi_value* argv,
                               napi_value* result);

参数说明：

参数	类型	方向	描述
env	napi_env	输入	N-API 环境句柄
recv	napi_value	输入	函数调用时的 this 对象
func	napi_value	输入	要调用的 JavaScript 函数
argc	size_t	输入	参数数量
argv	const napi_value*	输入	参数数组
result	napi_value*	输出	函数调用的返回值（可为 NULL）

使用示例：

napi_value global, func, args[1], result;
napi_get_global(env, &global);
// 假设 func 是一个 JavaScript 函数
napi_call_function(env, global, func, 1, args, &result);

第三部分：NAPI开发步骤

1. 引入头文件并实现C/C++函数体

首先是在C/C++文件中引入 #include "napi/native_api.h"，然后就是按照普通逻辑实现C/C++的函数体。

#include "napi/native_api.h"

2. 定义要开放的NAPI接口函数与Native函数的映射关系

将C/C++中的Native函数或者属性开放给JavaScript使用，通常是在框架自带的函数 static napi_value Init(napi_env env, napi_value exports) 中完成映射的。

EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
    napi_property_descriptor desc[] = {
        {"Init", nullptr, ObjectDectionInit, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"Process", nullptr, ObjectDectionProcess, nullptr, nullptr, nullptr, napi_default, nullptr},
        {"DeInit", nullptr, ObjectDectionDeInit, nullptr, nullptr, nullptr, napi_default, nullptr}};
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

或者使用宏定义：

EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports) {
    napi_property_descriptor desc[] = {
        DECLARE_NAPI_FUNCTION("Init", ObjectDectionInit),
        DECLARE_NAPI_FUNCTION("Process", ObjectDectionProcess),
        DECLARE_NAPI_FUNCTION("DeInit", ObjectDectionDeInit)
         };
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

这样子就建立完成了相关的映射关系。

3. 建立接口与Module的映射关系

3.1 定义一个napi_module对象

定义一个napi_module对象，把对应的so绑定到nm_modname属性中，并且绑定了注册Module的入口函数。

/*
 * Napi Module define
 */

static napi_module msLiteModule = {
    .nm_version = 1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "mslite_napi",
    .nm_priv = ((void *)0),
    .reserved = {0},
};

绑定后就可以在ETS侧通过 import mslite_napi from 'libmslite_napi.so'

import mslite_napi from 'libmslite_napi.so'

let resourceManager = context.resourceManager
mslite_napi.Init(resourceManager)
mslite_napi
  .Process(this.modelId, picDesc, buffer)
  .then((value: InferResult) => {
    callback(value.objects)
  })
  .catch((err: BusinessError) => {})
mslite_napi.DeInit()

3.2 napi_module对象绑定到系统函数RegisterModule中

再把napi_module对象传入到系统函数RegisterModule中：

/*
 * module register
 */
extern "C" __attribute__((constructor)) void RegisterModule(void) {
  MS_LOG(INFO) << "RegisterModule() is called";
  napi_module_register(&g_module);
}

3.3 执行napi_module的入口函数nm_register_func

一般来说在OH系统中内置的NAPI的注册入口函数是由Framework自动去执行，所以呢我们自己开发NAPI的话需要自己去调用触发才行。

4. 定义ETS接口描述文件.d.ts

export const Init: (path: Object) => number
export const Process: (
  modeid: number,
  picDesc: Object,
  buffer: ArrayBuffer,
) => number
export const DeInit: () => number

5. 在Native侧实现接收和处理ETS的传参及反馈结果

因为在ETS侧你可以认为数据类型是弱类型的，具体的类型是什么，需要由Native侧自己去解析。

Native侧接收ETS侧传递过来的函数的形参列表及返回值都是固定类型的。

5.1 开发同步接口

C开发者做好数据的转换工作就可以了。

JavaScript调用传递的参数对象、函数对象都是以napi_value这样一个抽象的类型提供给C的，开发者需要将它们转换为C数据类型进行计算，再将计算结果转为napi_value类型返回就可以了。NAPI框架提供了各种api接口为用户完成这些转换，这些转换工作背后是依赖JS引擎去实现的。

static napi_value GetVisitCountSync(napi_env env, napi_callback_info info) {
  /* 根据环境变量获取参数 */
  size_t argc = 2; //参数个数
  napi_value argv[2] = { 0 }; //参数定义

  /* 入参变量获取 */
  napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
  // 获取入参的类型
  napi_valuetype valueType = napi_undefined;
  napi_typeof(env, argv[0], &valueType);

  // 入参值转换为C/C++可以操作的数据类型
  char value[VALUE_BUFFER_SIZE] = { 0 };
  size_t valueLen = 0;
  napi_get_value_string_utf8(env, argv[0], value, VALUE_BUFFER_SIZE, &valueLen);

  // ...... 省略若干业务流程计算步骤

  /* C/C++数据类型转换为JS数据类型并返回 */
  napi_value result = nullptr; // JS字符串对象
  std::string resultStr = "Visit Count = 65535";
  napi_create_string_utf8(env, resultStr.c_str(), resultStr.length(), &result);

  return result; //返回JS对象
}

5.1.1 函数声明

每一个映射后的函数，必须是参数napi_env env, napi_callback_info cbinfo，返回值为napi_value。为了实现js或ets调用，NAPI框架需要解决以下问题，数据传递与转换，js/ets传入的入参、得到的返回结果，需要转换成C/C++代码可以操作的数据类型，因此NAPI框架引入了一个中间的数据类型，来分别对应上层js/ets与C/C++的类型，以及数据类型的操作方法。

5.1.2 获取入参

函数napi_get_cb_info从cbinfo参数中获取JavaScript传入参数

5.1.3 把NAPI类型转换为C/C++可识别的类型

napi_value NapiDemo(napi_env env, napi_callback_info cbinfo)
{
        ...
    char* type = nullptr;
    size_t typeLen = 0;
    napi_get_value_string_utf8(env, argv[0], nullptr, 0, &typeLen);
    NAPI_ASSERT(env, typeLen > 0, "typeLen == 0");
    type = new char[typeLen + 1];
    napi_get_value_string_utf8(env, argv[0], type, typeLen + 1, &typeLen);
        ...
}

5.1.4 返回值

当C++没有返回值时NapiDemo将nullptr返回，NAPI框架没有nullptr，通过napi_get_undefined将nullptr转换成nullptr napi_undefined。

napi_value NapiDemo(napi_env env, napi_callback_info cbinfo)
{
...
    napi_value result = nullptr;
    napi_get_undefined(env, &result);
    return result;
}