OpenHarmony系统之Napi框架生成工具介绍

作者：苟晶晶 2024-01-03 15:41:49

NAPI框架生成工具支持三种入口，分别是可执行程序、VS Code插件、DevEco Studio上使用的IntelliJ插件，使用者可以根据自己的需要选择合适的工具。本文主要介绍可执行文件的使用方法。

https://ost.51cto.com

当开发者为OpenHarmony系统上开发JS与C交互的接口时，需要使用NAPI进行接口封装：首先需要用户定义JS接口，然后创建NAPI模块、实现NAPI初始化函数、封装JS接口、处理JS调用，最后进行构建和部署。这需要开发人员熟悉NAPI，有一定的学习成本。而Napi框架生成工具可以根据用户指定路径下的ts(typescript)接口文件一键生成NAPI框架代码、业务代码框架，这为开发者提供了一种快速、高效的开发方式，可以大大提高开发效率。使用该工具时，开发者不必关注Nodejs的语法、C与JS之间的数据类型转换等上层应用逻辑，只需要关注底层业务逻辑；此外，Napi框架生成工具还可以自动生成GN文件，这样就可以方便地将生成的代码集成到OpenHarmony系统中。这种方式可以避免手动编写GN文件的繁琐过程，提高了代码集成的效率。

1、使用说明

可执行文件下载路径如下(由于网络原因，可能会导致有的下载链接失效，因此提供了以下三个下载链接):

可执行文件下载链接1

可执行文件下载链接2

可执行文件下载链接3

访问密码：kaihong

压缩包解压密码：kaihong20231121

输入文件说明

待转换的示例.ts文件 @ohos.napitest.d.ts。

declare namespace napitest {
    function func1(v: string): string;
}
export default napitest;

业务代码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";
}
}

配置文件cfg.json示例：

[
  {
    "includeName": "../serviceCode/Service.h",
    "cppName": "../serviceCode/Service.cpp",
    "interfaceName": "func1",
    "serviceCode": "out = napitest::func1(v);"
  }
]

可执行文件使用方法

Linux

将待转换的.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

在终端中进入到之前可执行程序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文件中描述其它字段含义的属性，用户配置时，可以不用填写这个字段。

运行成功后会在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

将待转换的.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

在终端中进入到之前可执行程序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

其中，参数详情如下：

-f, 待转换的.d.ts文件，若同时转换多个文件，文件之间用“,”隔开。
-d, 根据指定路径转换该文件夹中所有.d.ts文件。
-i, 可选参数，默认false，待转换.d.ts文件中引用非basic.d.ts的ts文件时打开开关。
-o, 可选参数，默认为当前目录，指定生成框架代码输出路径。
-n, 可选参数，默认为uint32_t，指定生成框架代码中number类型全部为指定类型。
-s, 可选参数，默认为不配置业务代码，指定生成框架代码的业务配置文件，用于粘合工具代码和业务代码的配置。

备注1：-f与-d两个参数只选其中一个参数即可。

其中，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”。

“serviceCode”: 在接口中调用业务代码的调用语句。此处调用的是实现该接口的业务代码，如：“out = napitest::func1(v);”。

“description”: 仅作为cfg.json文件中描述其它字段含义的属性，用户配置时，可以不用填写这个字段。

运行成功后会在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

方法步骤参考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、应用测试

硬件：rk3568开发套件。

系统镜像: 集成到OpenHarmony并编译成功的镜像，路径如下：

OpenHarmony/out/rk3568/packages/phone/images

扩展SDK接口并增加新接口调用。

（1）扩展SDK接口

查看SDK目录：

将@ohos.napitest.d.ts文件拷贝到sdk目录下的ets\api：

（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框架生成工具是一个开源项目，我们欢迎有兴趣的开发者试用该工具，并提出宝贵的改进意见，我们将继续不断优化和完善该工具软件。我们相信，该工具会成为OpenHarmony生态圈中一个有用的补充。

想了解更多关于开源的内容，请访问：

51CTO 开源基础软件社区

https://ost.51cto.com

责任编辑：jianghua 来源： 51CTO 开源基础软件社区

OpenHarmony系统之Napi框架生成工具介绍

OpenHarmony系统之Napi框架生成工具介绍

1、使用说明

输入文件说明

可执行文件使用方法

Linux

Windows

不配置cfg.json文件生成框架代码

输出文件说明

2、集成说明

3、应用测试

（1）扩展SDK接口

（2）编写应用测试新接口

Recommend

Why Aaron Rodgers Is Beefing With Jimmy Kimmel Over Jeffrey Epstein

UI 設計小錦囊 - 20 種差異鮮明色彩組合

微信小程序问一问怎么玩

On offshore wind farms, seafood production may be a breeze

大家的工作中会有 Code Review 吗？

Samsung confirms January 17 unveiling for the Galaxy S24 family, probably by mis...

2023全球高端智能手机市场，苹果依然独占鳌头，华为增长明显

hahaSIM 最终还是封神了，最新办法做到 10 港币保号一年！

怀旧风拉满成都市武侯区玉林东路打造年味十足的“跨年盛宴”

Java ZGC 调优

About Joyk