想了解更多關于開源的內容，請訪問：

本站開源基礎軟件社區

前言

當開發者為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

可執行文件下載鏈接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兩個參數只選其中一個參數即可。

備注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.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、應用測試

準備

硬件：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生態圈中一個有用的補充。

想了解更多關于開源的內容，請訪問：

本站開源基礎軟件社區