1.Node-api组成架构
为了应对日常开发经的网络通信、串口访问、多媒体解码、传感器数据收集等模块，这些模块大多数是使用c++接口实现的，arkts侧如果想使用这些能力，就需要使用node-api这样一套接口去桥接c++代码。Node-api整体的架构图如下：
Node-api接口是基于node.js的一个扩展，所以在平常开发过程也可以参照node.js官网，像接口实现的功能，入参都是类似的。
Framework模块介绍
1）ModuleManager是管理对象的模块，当arkts侧调用c++时，会加载Native侧的模块到ModuleMangger，并转化为arkts对象返回上层。
2）ScopeManager：用于管理napi_value生命周期，napi_value是Node-api独特的数据类型，类似于ArkTs中的number、String等各种参数类型的统一表示形式，在Native侧代码开发中不需要感知不同类型的数据类型，统一都是napi_value。
3）ReferenceManager：用于管理引用，开发时经常会有一些跨线程的场景，这个时候就需要创建引用(napi_ref)，否则就就会被GC回收掉。napi_ref用于指向napi_value，允许用户管理napi_value值的生命周期。
3）Native Engine的作用是统一ArkTS引擎在Node-API层的接口行为。
4）方舟运行时，也就是ArkTS引擎，整个Node-API模块都是跑在方舟运行时的。
2.Napi和native的交互流程
主要分为两步：模块初始化和函数调用
模块初始化
ArkTS在import一个so库的时候，会先找到ArkTS引擎，ArkTS引擎会加载模块信息到ModuleMananger，其实就是对应的dlopen函数（首次调用时加载，多次调用回去缓存查找）。之后ModuleManager会把模块信息返回给ArkTS引擎。ArkTS引擎拿到模块信息后，在native层触发模块注册，来初始化模块。注册完成之后通过底层框架返回给上层一个ArkTS对象，这个对象上挂在着c/c++侧的方法。我们拿到arkts对象后，就可以去调用c/c++的方法了。
函数调用
当arkts侧通过上述import返回的对象的调用方法时，ArkTS引擎会找到并调用对应的C/C++方法
3.Node-API支持的数据类型
napi_status:枚举数据类型，表示Node-API接口返回的状态信息。每当调用一个Node-API函数，都会返回该值，表示操作成功与否的相关信息。枚举信息如下：
typedef enum{
napi_ok,
napi_invalid_arg,
napi_object_expected,
napi_string_expected,
napi_name_expected,
...
napi_would_deadlock
} napi_status;
if (napi_ok != napi_get_cb_info(env, info, &argc, args, nullptr, nullptr)) {
return nullptr;
}Node-API将基本数据类型公开为各种API使用的抽象。这些API应该被视为不透明的，只能通过其他Node-API调用进行自省。
- napi_value:在Native侧代码开发中不需要感知不同类型的数据，统一都是napi_value
举例说明：napi_value napiResult; napi_create_double(env, 2.0, &napiResult); - napi_env:Native侧函数入参，表示Napi-API执行时的上下文。退出native侧的时，napi_env将失效
- napi_callback_info: Native侧函数的入参，保存了ArkTS侧的参数信息，用于传递给napi_get_cb_info()函数获取ArkTS侧入参信息。
举例说明：static napi_value MyHypot(napi_env env, napi_callback_info info) { size_t argc = 2; napi_value args[2] = {nullptr}; // 从info中获取参数信息到参数数组args[] napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); }4.Node-API接口
Node-API接口在Node.js提供的原生模块基础上，目前只支持部分接口。常用的部分接口介绍如下：
- napi_get_cb_info: 从给定的napi_callback_info中获取有关调用的详细信息，如参数和this指针
static napi_value MyHypot(napi_env env, napi_callback_info info) { size_t argc = 2; napi_value args[2] = {nullptr}; // 从info中获取参数信息到参数数组args[] napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); } -
napi_get_value_double: 获取给定ArkTS的number类型
double valueX = 0.0;
//获取args[0]存储的参数信息并赋值给valueX,args[]中存储接受ArkTs侧参数
napi_get_value_double(env, args[0], &valueX); -
napi_create_string_utf8: 通过utf8编码的c字符串数据创建ArtTS侧String类型的数据
std::string str = "temp"; napi_value sum; //用于存储转换类型后的string类型数据 napi_create_string_utf8(env, str.c_str(), str.length(). &sum);5.案例讲解说明交互流程
目录说明
CPP目录
types/index.d.ts:定义了c++侧需要暴漏在ArkTS侧的接口
oh-package.json5是描述index.d.ts文件的
napi_init.cpp文件在里面做Native模块的注册、类型的转换以及大部分业务逻辑
ets目录
page/index.ets 里面有ArkTS调用C++
src目录
build-profile.json5:主要是配置构建信息（主要是cmakelist的构建路径，构建的时候能够找到cmakelist文件）
oh-package.json5:主要配置了一些模块本身的信息和依赖的工程
6.官方代码案例
基于Node-API开发业务功能
static napi_value MyHypot(napi_env env, napi_callback_info info)
{
if ((nullptr == env) || (nullptr == info)) {
OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "MyHypot", "env or exports is null");
return nullptr;
}
// Number of parameters.
size_t argc = 2;
// Declare parameter array.
napi_value args[2] = { nullptr };
// Gets the arguments passed in and puts them in the argument array.
if (napi_ok != napi_get_cb_info(env, info, &argc, args, nullptr, nullptr)) {
OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "MyHypot", "api_get_cb_info failed");
return nullptr;
}
// Converts arguments passed in to type double.
double valueX = 0.0;
double valueY = 0.0;
if (napi_ok != napi_get_value_double(env, args[0], &valueX) ||
napi_ok != napi_get_value_double(env, args[1], &valueY)) {
OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "MyHypot", "napi_get_value_double failed");
return nullptr;
}
// The hypot method of the C standard library is called to perform the calculation.
double result = hypot(valueX, valueY);
napi_value napiResult;
if (napi_ok != napi_create_double(env, result, &napiResult)) {
OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "MyHypot", "napi_create_double failed");
return nullptr;
}
return napiResult;
}
接口映射
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports)
{
if ((nullptr == env) || (nullptr == exports)) {
OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "Init", "env or exports is null");
return exports;
}
napi_property_descriptor desc[] = {
{ "myHypot", nullptr, MyHypot, nullptr, nullptr, nullptr, napi_default, nullptr }
};
if (napi_ok != napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc)) {
OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "Init", "napi_define_properties failed");
return nullptr;
}
return exports;
}
EXTERN_C_END模块注册
static napi_module demoModule = {
.nm_version = 1,
.nm_flags = 0,
.nm_filename = nullptr,
.nm_register_func = Init,
.nm_modname = "hello",
.nm_priv = ((void *)0),
.reserved = { 0 }
};
extern "C" __attribute__((constructor)) void RegisterModule(void)
{
napi_module_register(&demoModule);
}
模块构建配置
cmakelist.txt文件：
# the minimum version of CMake.
cmake_minimum_required(VERSION 3.4.1)
project(NativeTemplateDemo)
set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})
include_directories(
${NATIVERENDER_ROOT_PATH}
${NATIVERENDER_ROOT_PATH}/include
)
find_library(
# Sets the name of the path variable.
hilog-lib
# Specifies the name of the NDK library that
# you want CMake to locate.
hilog_ndk.z
)
add_library(hello SHARED hello.cpp)
target_link_libraries(hello PUBLIC ${hilog-lib} libace_napi.z.so libc++.a)根目录下的build-profile.json5
{
"apiType": 'stageMode',
"buildOption": {
"externalNativeOptions": {
"path": "./src/main/cpp/CMakeLists.txt",
"arguments": "",
"abiFilters": [
"arm64-v8a",
"x86_64"
],
"cppFlags": "",
}
},
"targets": [
{
"name": "default",
"runtimeOS": "HarmonyOS"
}
]
}导出native接口
/entry/oh-package.json5
{
"license": "",
"devDependencies": {
"libhello.so": "file:./src/main/cpp/types/libhello"
},
"author": "",
"name": "entry",
"description": "Please describe the basic information.",
"main": "",
"version": "1.0.0",
"dependencies": {}
}7.更多接口说明参照官网
华为开发者学堂
