前言
当开发者为OpenHarmony系统上开发JS与C++ 交互的接口时，需要使用NAPI进行接口封装：首先需要用户定义JS接口，然后创建NAPI模块、实现NAPI初始化函数、封装JS接口、处理JS调用，最后进行构建和部署。这需要开发人员熟悉NAPI，有一定的学习成本。而Napi框架生成工具可以根据用户指定路径下的ts(typescript)接口文件一键生成NAPI框架代码、业务代码框架，这为开发者提供了一种快速、高效的开发方式，可以大大提高开发效率。使用该工具时，开发者不必关注Nodejs的语法、C++与JS之间的数据类型转换等上层应用逻辑，只需要关注底层业务逻辑；此外，Napi框架生成工具还可以自动生成GN文件，这样就可以方便地将生成的代码集成到OpenHarmony系统中。这种方式可以避免手动编写GN文件的繁琐过程，提高了代码集成的效率。
1.使用说明
NAPI框架生成工具支持三种入口，分别是可执行程序、VS Code插件、DevEco Studio上使用的IntelliJ插件，使用者可以根据自己的需要选择合适的工具。本文主要介绍可执行文件的使用方法。
1.可执行文件下载路径如下(由于网络原因，可能会导致有的下载链接失效，因此提供了以下三个下载链接):
可执行文件下载链接1
可执行文件下载链接2
可执行文件下载链接3
访问密码：kaihong
压缩包解压密码：kaihong20231121
准备
输入文件说明
1.待转换的示例.ts文件 @ohos.napitest.d.ts
declare namespace napitest {? ? function func1(v: string): string; } export default napitest;
2.业务代码serviceCode示例
业务代码头文件Service.h
#ifndef IMPL_SERVICE_H #define IMPL_SERVICE_H? #include <string>? namespace napitest {? ? std::string func1(std::string& v); } #endif // IMPL_SERVICE_H
业务代码cpp文件Service.cpp
#include "Service.h" #include "../generatorCode/napitest.h" #include "hilog/log.h" static constexpr OHOS::HiviewDFX::HiLogLabel LABEL = {LOG_CORE, 0XD002E00, "NAPITESTNAPILayer"}; #define NAPITEST_LOGI(fmt, ...) OHOS::HiviewDFX::HiLog::Info(LABEL, \? ? "%{public}s:%{public}d " fmt, __func__, __LINE__, ##__VA_ARGS__) namespace napitest { std::string func1(std::string& v) {? ? NAPITEST_LOGI("NAPITEST_LOGI func1 v = %s\r\n", v.c_str());? // 打印输入参数? ? return "testzzz"; } }
3.配置文件cfg.json示例
[? {? ? "includeName": "../serviceCode/Service.h",? ? "cppName": "../serviceCode/Service.cpp",? ? "interfaceName": "func1",? ? "serviceCode": "out = napitest::func1(v);"? } ]
可执行文件使用方法
Linux
1.将待转换的.d.ts文件（如@ohos.napitest.d.ts）、napi_generator-linux、 配置文件cfg.json、业务代码文件夹serviceCode（其中serviceCode目录下放置业务代码的.h文件和.cpp文件）放在同级目录下。此处新建generatorCode文件夹，用于存放生成框架代码。整体目录文件如下：
OpenHarmony@Ubuntu-64:~/service$ ls napi_generator-linux? @ohos.napitest.d.ts? generatorCode? cfg.json? serviceCode
2.在终端中进入到之前可执行程序napi_generator-linux所在的目录，并运行napi_generator-linux，命令如下：
OpenHarmony@Ubuntu-64:~/service$ ./napi_generator-linux -f @ohos.napitest.d.ts -o generatorCode -i false -n int -s cfg.json
其中，参数详情如下：
-f, 待转换的.d.ts文件，若同时转换多个文件，文件之间用“,”隔开；
-d, 根据指定路径转换该文件夹中所有.d.ts文件；
-i, 可选参数，默认false，待转换.d.ts文件中引用非basic.d.ts的ts文件时打开开关；
-o, 可选参数，默认为当前目录，指定生成框架代码输出路径；
-n, 可选参数，默认为uint32_t，指定生成框架代码中number类型全部为指定类型；
-s, 可选参数，默认为不配置业务代码，指定生成框架代码的业务配置文件，用于粘合工具代码和业务代码的配置。
备注1：-f与-d两个参数只选其中一个参数即可。
备注2：若.d.ts文件中声明了basic.d.ts文件，将basic.d.ts文件放置在待转换.d.ts文件同一级目录；若除此之外还声明其它.d.ts文件，将此类文件放置在待转换.d.ts文件同级目录。
其中，cfg.json内容如下：
[? {? "includeName": "../serviceCode/Service.h",? "cppName": "../serviceCode/Service.cpp",? "interfaceName": "func1",? "serviceCode": "out = napitest::func1(v);",? "description": "includeName: 引入的业务代码.h文件相对路径, cppName: 引入的业务代码.cpp文件相对路径, interfaceName: ts文件中的使用接口名,业务代码就在该接口中调用;格式为：类名::方法名(如: TestClass::funcTest1)，若无类名，则格式为：方法名(如： funcTest), serviceCode: 在接口中调用业务代码的调用语句。（该属性只做注释使用）"? } ]
cfg.json是一个数组，每一项配置对应一个方法的调用，需要对多少方法进行调用就配置多少项；其中
“includeName”: 引入的业务代码.h文件相对路径, 如： “…/serviceCode/Service.h”,
“cppName”: 引入的业务代码.cpp文件相对路径, 如：“…/serviceCode/Service.cpp”,
“interfaceName”: ts文件中的使用接口名,业务代码就在该接口中调用;格式为：类名::方法名(如: TestClass::funcTest1)，若无类名，则格式为：方法名(如： func1),
“serviceCode”: 在接口中调用业务代码的调用语句。此处调用的是实现该接口的业务代码， 如：“out = napitest::func1(v);”
“description”: 仅作为cfg.json文件中描述其它字段含义的属性，用户配置时，可以不用填写这个字段
3.运行成功后会在generatorCode目录下生成框架代码文件，如下所示：
OpenHarmony@Ubuntu-64:~/linshi/napi_generator_8/examples/ts/generatorCode$ ls binding.gyp? BUILD.gn? napi_gen.log? napitest.cpp? napitest.h? napitest_middle.h napitest_middle.cpp? test.sh? tool_utility.cpp? tool_utility.h
Windows
1.将待转换的.d.ts文件（如@ohos.napitest.d.ts）、napi_generator-win.exe、 配置文件cfg.json、业务代码文件夹serviceCode（其中serviceCode目录下放置业务代码的.h文件和.cpp文件）放在同级目录下。此处新建generatorCode文件夹，用于存放生成框架代码。整体目录文件如下：
E:\demo\napi>dir /B @ohos.napitest.d.ts napi_generator-win.exe generatorCode cfg.json serviceCode
2.在终端中进入到之前可执行程序napi_generator-win.exe所在的目录，并运行napi_generator-win.exe，命令如下：
E:\demo\napi>napi_generator-win.exe -f @ohos.napitest.d.ts -o generatorCode -i false -n double -s cfg.json
1.
其中，参数详情如下：
-f, 待转换的.d.ts文件，若同时转换多个文件，文件之间用“,”隔开；
-d, 根据指定路径转换该文件夹中所有.d.ts文件；
-i, 可选参数，默认false，待转换.d.ts文件中引用非basic.d.ts的ts文件时打开开关；
-o, 可选参数，默认为当前目录，指定生成框架代码输出路径；
-n, 可选参数，默认为uint32_t，指定生成框架代码中number类型全部为指定类型；
-s, 可选参数，默认为不配置业务代码，指定生成框架代码的业务配置文件，用于粘合工具代码和业务代码的配置。
备注1：-f与-d两个参数只选其中一个参数即可。
备注2：若.d.ts文件中声明了basic.d.ts文件，将basic.d.ts文件放置在待转换.d.ts文件同一级目录；若除此之外还声明其它.d.ts文件，将此类文件放置在待转换.d.ts文件同级目录。
其中，cfg.json内容如下：
[? {? "includeName": "../serviceCode/Service.h",? "cppName": "../serviceCode/Service.cpp",? "interfaceName": "func1",? "serviceCode": "out = napitest::func1(v);",? "description": "includeName: 引入的业务代码.h文件相对路径, cppName: 引入的业务代码.cpp文件相对路径, interfaceName: ts文件中的使用接口名,业务代码就在该接口中调用;格式为：类名::方法名(如: TestClass::funcTest1)，若无类名，则格式为：方法名(如： funcTest), serviceCode: 在接口中调用业务代码的调用语句。（该属性只做注释使用）"? } ]
cfg.json是一个数组，每一项配置对应一个方法的调用，需要对多少方法进行调用就配置多少项；其中
“includeName”: 引入的业务代码.h文件相对路径, 如： “…/serviceCode/Service.h”,
“cppName”: 引入的业务代码.cpp文件相对路径, 如：“…/serviceCode/Service.cpp”,
“interfaceName”: ts文件中的使用接口名,业务代码就在该接口中调用;格式为：类名::方法名(如: TestClass::funcTest1)，若无类名，则格式为：方法名(如： func1),
“serviceCode”: 在接口中调用业务代码的调用语句。此处调用的是实现该接口的业务代码， 如：“out = napitest::func1(v);”
“description”: 仅作为cfg.json文件中描述其它字段含义的属性，用户配置时，可以不用填写这个字段
3.运行成功后会在generatorCode目录下生成框架代码文件，如下所示：
E:\demo\napi\generatorCode>dir /B binding.gyp BUILD.gn napitest.cpp napitest.h napitest_middle.h napitest_middle.cpp napi_gen.log test.sh tool_utility.cpp tool_utility.h
Mac
方法步骤参考windows、Linux的使用方法。
不配置cfg.json文件生成框架代码
若使用配置文件配置业务代码不能满足用户使用场景需求，可手动配置业务代码，参考以下链接：
不配置cfg.json生成框架代码说明
输出文件说明
Napi工具生成文件如下所示：
binding.gyp BUILD.gn napitest.cpp napitest.h napitest_middle.h napitest_middle.cpp napi_gen.log test.sh tool_utility.cpp tool_utility.h
其中binding.gyp为工具生成框架代码后自测时的编译配置文件；BUILD.gn为集成到OpenHarmony系统上的编译配置文件；napitest.h和napitest.cpp是工具生成的业务代码文件，业务开发者在这里对业务接口进行调用或进行业务代码实现；而napitest_middle.h，napitest_middle.cpp，tool_utility.h，tool_utility.cpp为胶水代码，即NAPI框架代码，用于创建NAPI模块、实现NAPI初始化函数、参数转换、封装JS接口、处理JS调用等；napi_gen.log为工具生成的日志文件。
2.集成说明
本集成说明针对的是OpenHarmony 4.0release系统，其他系统可能存在差别，开发者可自行调试修改。
用户使用配置文件cfg.json生成框架代码后，不必再手动修改业务代码，直接将生成代码集成到OpenHarmony的方法参考以下链接：
生成代码集成到OpenHarmony
若在生成框架代码时，用户未选择配置文件cfg.json生成框架代码，那么在集成时用户就需要在生成的框架代码中自行添加业务代码，例如当前ts文件生成的napitest.cpp文件，修改相应代码后如下所示：
#include "napitest.h" #include "hilog/log.h" static constexpr OHOS::HiviewDFX::HiLogLabel LABEL = {LOG_CORE, 0XD002E00, "NAPITESTNAPILayer"}; #define NAPITEST_LOGI(fmt, ...) OHOS::HiviewDFX::HiLog::Info(LABEL, \? ? "%{public}s:%{public}d " fmt, __func__, __LINE__, ##__VA_ARGS__) namespace napitest { bool func1(std::string& v, std::string& out) {? ? NAPITEST_LOGI("NAPITEST_LOGI func1 v = %s\r\n", v.c_str());? // 打印输入参数? ? out = "testzzz";? ? return true; } }
手动配置业务代码之后集成到OpenHarmony的方法参考以下链接：
4.0版本手动配置业务代码集成方法
3.应用测试
准备
1.硬件：rk3568开发套件。
2.系统镜像: 集成到OpenHarmony并编译成功的镜像，路径如下：
OpenHarmony/out/rk3568/packages/phone/images
3.扩展SDK接口并增加新接口调用
3.1 扩展SDK接口
查看SDK目录：
添加图片注释，不超过 140 字（可选）
将@ohos.napitest.d.ts文件拷贝到sdk目录下的ets\api：
添加图片注释，不超过 140 字（可选）
编辑
3.2 编写应用测试新接口
其中修改index.ets文件内容如下：
import hilog from '@ohos.hilog'; import napitest from '@ohos.napitest'; @Entry @Component struct Index { ? @State message: string = 'Hello World' ? build() { ? ? Row() { ? ? ? Column() { ? ? ? ? Text(this.message) ? ? ? ? ? .fontSize(50) ? ? ? ? ? .fontWeight(FontWeight.Bold) ? ? ? ? // 添加按钮，以响应用户点击 ? ? ? ? Button() { ? ? ? ? ? Text('TEST') ? ? ? ? ? ? .fontSize(30) ? ? ? ? ? ? .fontWeight(FontWeight.Bold) ? ? ? ? } ? ? ? ? .type(ButtonType.Capsule) ? ? ? ? .margin({ ? ? ? ? ? top: 20 ? ? ? ? }) ? ? ? ? .backgroundColor('#0D9FFB') ? ? ? ? .width('40%') ? ? ? ? .height('5%') ? ? ? ? // 跳转按钮响应 ? ? ? ? .onClick(() => { ? ? ? ? ? let out = napitest.func1("abcf"); ? ? ? ? ? hilog.info(0x0000, 'testTag', '%{public}s', 'AAAAAAAA napi testprint' + out); ? ? ? ? }) ? ? ? } ? ? ? .width('100%') ? ? } ? ? .height('100%') ? } }
使用说明
步骤一：安装镜像环境：将out/rk3568/packages/phone目录下的images镜像文件下载并烧录到开发板上。
OpenHarmony@Ubuntu-64:~/OpenHarmony/out/rk3568/packages/phone/images$ ll? total 767452? drwxrwxrwx? 2 root root? ? ? 4096 Nov 21 05:32 ./? drwxrwxrwx 15 root root? ? ? 4096 Nov 21 05:32 ../? -rwxrwxrwx? 1 root root? 67108864 Nov 21 05:04 boot_linux.img*? -rw-r--r--? 1 root root? 52428800 Nov 21 05:32 chip_prod.img? -rwxrwxrwx? 1 root root? ? ? 8569 Nov 21 05:04 config.cfg*? -rw-r--r--? 1 root root? 12582912 Nov 21 05:32 eng_system.img? -rwxrwxrwx? 1 root root? ? 455104 Nov 21 05:04 MiniLoaderAll.bin*? -rwxrwxrwx? 1 root root? ? ? ? 756 Nov 21 05:04 parameter.txt*? -rw-rw-r--? 1 root root? ? 2507625 Nov 21 05:32 ramdisk.img? -rwxrwxrwx? 1 root root? ? 5639680 Nov 21 05:04 resource.img*? -rw-r--r--? 1 root root? 52428800 Nov 21 05:32 sys_prod.img? -rw-r--r--? 1 root root 1610608640 Nov 21 05:32 system.img? -rwxrwxrwx? 1 root root? ? 4194304 Nov 21 05:04 uboot.img*? -rw-rw-r--? 1 root root? 15806303 Nov 21 05:32 updater.img? -rw-r--r--? 1 root root 1468006400 Nov 21 05:32 userdata.img? -rw-r--r--? 1 root root? 268431360 Nov 21 05:32 vendor.img
步骤二：安装hap包。
Build Haps通过后，通过Run按钮将hap包安装到板子上。
执行完成后，设备中会出现安装的APP。
步骤三：打印日志并验证结果。
hap包安装成功后，进入hdc shell
首先执行以下命令关闭hilog隐私权限
hilog -p off
输入命输入命令实时打印日志并输出至windows中。
.\hdc.exe hilog > log.txt
然后单击设备中安装的APP，进入APP后单击测试按钮，执行完成后会在hdc安装目录下出现log.txt文件。
查看结果
log.txt中包含“AAAAAAAA napi testprint testzzz”日志表示接口调用成功。如下所示：
// 打印js层传递给C++的入参abcf I C02e00/NAPITESTNAPILayer: [Service.cpp:10] NAPITEST_LOGI func1 v = abcf // 打印接口返回到js的返回值testzzz 01-01 08:10:55.571? 2291? 2291 I A00000/testTag: AAAAAAAA napi testprint testzzz
使用问题
问题：用可执行程序生成C++代码失败，log如下所示：
E:\napi_generator_aboutTest\zzx_gjj_napi230808\napiTest>napi_generator-win.exe -f @ohos.napitest.d.ts at checkGenerate [C:\snapshot\napi_generator\src\gen\cmd_gen.js(135:21)] @ohos.napitest.d.ts (15,41): Cannot find module './basic'. Did you mean to set the 'moduleResolution' option to 'node', or to add aliases to the 'paths' option?? fail @ohos.napitest.d.ts (15,41): Cannot find module './basic'. Did you mean to set the 'moduleResolution' option to 'node', or to add aliases to the 'paths' option
问题定位：@ohos.napitest.d.ts依赖了文件basic.d.ts，但在@ohos.napitest.d.ts同级目录下未找到该依赖文件。
Cannot find module './basic'.
解决方案：将依赖文件basic.d.ts放在@ohos.napitest.d.ts同级目录下，若@ohos.napitest.d.ts中还引用了其他依赖文件，需要一一将其加入到其依赖的路径下。
更多常见问题解决方法指导如下：
FAQ
相关仓
关于Napi工具，若想了解更多，请参考以下链接：
napi_generator: NAPI框架生成工具
总结
Napi框架生成工具是一个开源项目，我们欢迎有兴趣的开发者试用该工具，并提出宝贵的改进意见，我们将继续不断优化和完善该工具软件。