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插件，使用者可以根據自己的需要選擇合適的工具。本文主要介紹可執行文件的使用方法。
可執行文件下載路徑如下(由于網絡原因，可能會導致有的下載鏈接失效，因此提供了以下三個下載鏈接):
訪問密碼：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.hWindows
將待轉換的.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兩個參數只選其中一個參數即可。
備注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目錄下生成框架代碼文件，如下所示：
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.hMac
方法步驟參考windows、Linux的使用方法。
不配置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的方法參考以下鏈接：
若在生成框架代碼時，用戶未選擇配置文件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的方法參考以下鏈接：
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中還引用了其他依賴文件，需要一一將其加入到其依賴的路徑下。
更多常見問題解決方法指導如下：
相關倉
關于Napi工具，若想了解更多，請參考以下鏈接：
總結
Napi框架生成工具是一個開源項目，我們歡迎有興趣的開發者試用該工具，并提出寶貴的改進意見，我們將繼續不斷優化和完善該工具軟件。我們相信，該工具會成為OpenHarmony生態圈中一個有用的補充。
