【HarmonyOS NAPI 深度探索12】创建你的第一个 HarmonyOS NAPI 模块

news2025/1/21 10:02:02

【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，选择目标设备进行调试。