当前位置: 首页>后端>正文

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

前言

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


https://www.xamrdz.com/backend/3kf1944780.html

相关文章: