【HarmonyOS NAPI 深度探索12】创建你的第一个 HarmonyOS NAPI 模块
在本篇文章中，我们将一步步走过如何创建一个简单的 HarmonyOS NAPI 模块。通过这个模块，你将能够更好地理解 NAPI 的工作原理，并在你的应用中开始使用 C++ 与 JavaScript 的交互。我们将从头开始创建，帮助你快速入门。
准备工作
首先，确保你已经完成了前面的环境搭建和 DevEco Studio 的安装。如果还没有，可以参考我们之前的教程进行安装，并确保你能够在 DevEco Studio 中正常创建项目。
创建项目
- 启动 DevEco Studio
打开 DevEco Studio，进入主界面后点击File > New > Project，选择Native C++：
-
选择开发平台
输入项目名称，例如MyFirstNapiModule，以及包名、项目位置、编译SDK版本模块名称（默认entry）以及设备类型，目前支持：- Phone
- Tablet
- 2in1
- Car
默认已勾选了前三个：
-
项目结构概览
项目创建后，在entry下你会看到一个基本的项目结构。关键部分包括：cpp/napi_init.cpp文件： C++ 代码。cpp/types文件夹：动态库声明以及接口声明。CMakeList.txt：用于构建C++的配置文件。
编写 C++ 模块代码
- 编辑 C++ 代码
在napi_init.cpp文件下，实现了一个简单的加法运算示例，通过TS传入两个数字，C++中相加后返回到TS。代码如下：
#include "napi/native_api.h"
static napi_value Add(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);
napi_valuetype valuetype0;
napi_typeof(env, args[0], &valuetype0);
napi_valuetype valuetype1;
napi_typeof(env, args[1], &valuetype1);
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;
}
EXTERN_C_START
static napi_value Init(napi_env env, napi_value exports)
{
napi_property_descriptor desc[] = {
{ "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr }
};
napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
return exports;
}
EXTERN_C_END
static napi_module demoModule = {
.nm_version = 1,
.nm_flags = 0,
.nm_filename = nullptr,
.nm_register_func = Init,
.nm_modname = "entry",
.nm_priv = ((void*)0),
.reserved = { 0 },
};
extern "C" __attribute__((constructor)) void RegisterEntryModule(void)
{
napi_module_register(&demoModule);
}
这段代码中，我们定义了一个简单的 `Add` 函数，它将最后相加结果返回给 JavaScript 层。
- 配置
CMakeLists.txt
确保你的CMakeLists.txt文件包含正确的配置，来编译和链接你的原生模块。一个基本的CMakeLists.txt配置如下：
# the minimum version of CMake.
cmake_minimum_required(VERSION 3.5.0)
project(nativedemo)
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 napi_init.cpp)
target_link_libraries(entry PUBLIC libace_napi.z.so)
这个文件告诉 CMake 如何编译 C++ 代码并链接到 Node.js 库。
编写 JavaScript 调用代码
- 在
Index.ets文件中调用C++提供的Add方法
代码如下：
import { hilog } from '@kit.PerformanceAnalysisKit';
import testNapi from 'libentry.so';
@Entry
@Component
struct Index {
@State message: string = 'Hello World';
build() {
Row() {
Column() {
Text(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
.onClick(() => {
hilog.info(0x0000, 'testTag', 'Test NAPI 2 + 3 = %{public}d', testNapi.add(2, 3));
})
}
.width('100%')
}
.height('100%')
}
}
这里我们通过 `import testNapi from 'libentry.so'` 引入 C++ 模块，并调用 `add()` 方法，输入两个参数，它会输出 C++ 中相加的结果。
构建和调试
-
构建项目
在 DevEco Studio 中，点击Build > Build Project，DevEco Studio 会使用 CMake 编译 C++ 代码并生成共享库。构建成功后，你会看到BUILD SUCCESSFUL的提示。 -
调试项目
在 DevEco Studio 中，你可以设置断点并启动调试器，查看 C++ 代码执行的详细过程。点击Run > Debug，选择目标设备进行调试。
测试模块
- 运行 JavaScript 代码
运行项目点击Hello Word文字，你应该能看到控制台输出：
Test NAPI 2 + 3 = 5
- 检查输出
如果一切正常，说明你成功创建了第一个 HarmonyOS NAPI 模块，并且能够从 JavaScript 中调用 C++ 函数。
总结
通过本篇教程，我们已经成功创建了一个简单的 HarmonyOS NAPI 模块，并从 JavaScript 调用它。通过 NAPI，你可以方便地将 C++ 的高效性能与 TS的灵活性结合起来，为你的 HarmonyOS 应用提供更强大的功能。