NAPI 類對象導出及其生命周期管理(下)

作者：離北況歸 2023-03-16 15:29:57

系統 OpenHarmony

NDK (原生開發套件) 是一套工具，使開發者能夠在 OpenHarmony hap應用中使用 C/C++ 代碼。

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

??51CTO 開源基礎軟件社區??

??https://ost.51cto.com??

一、樣例工程源碼剖析

工程的模板是Native C++,模型是Stage。
源碼剖析主要圍繞以下幾個文件。

1、NAPI導出對象和生命周期管理具體實現

（1）定義NapiTest類及方法

Napi.h文件內容如下：

#ifndef __NAPI_TEST_H__
#define __NAPI_TEST_H__

#include "napi/native_api.h"
#include <js_native_api_types.h>

#include <iostream>

#define NAPI_CLASS_NAME "NapiTestClass"

class NapiTest {
public:
  NapiTest() : mEnv(nullptr), mRef(nullptr) {
  }
    
  NapiTest(napi_env env) : mEnv(env), mRef(nullptr){
  }
  ~NapiTest();
    
    // 創建NapiTest類的實體，并將實體返回到應用端，該方法為js創建一個類實體，因此需要將該接口對外導出
  static napi_value Create(napi_env env, napi_callback_info info);
    
    // 初始化js類并設置對應屬性并將其導出   
  static napi_value Init(napi_env env, napi_value exports);         
private:
    
    // 設置數據，此方法給到js直接調用，因此需要將該接口對外導出
  static napi_value SetMsg(napi_env env, napi_callback_info info);
    
    // 獲取數據，此方法給到js直接調用，因此需要將該接口對外導出    
    static napi_value GetMsg(napi_env env, napi_callback_info info);
    
    // 定義js結構體時實際的構建函數
    static napi_value Constructor(napi_env env, napi_callback_info info);     

    // 釋放資源的函數(類似類的析構函數)    
    static void Destructor(napi_env env, void *nativeObject, void *finalize); 

    // 生命周期變量    
    static napi_ref sConstructor_;  

    // 設置和獲取數據的變量    
    static std::string _msg;        

    // 記錄環境變量    
    napi_env mEnv = nullptr;        

    // 記錄生命周期變量    
    napi_ref mRef = nullptr;        

};

#endif  /* __NAPI_TEST_H__ */

napi_value

Node.js Node-API的值用napi_value類型表示。
OpenHarmony NAPI將ECMAScript標準中定義的Boolean、Null、Undefined、Number、BigInt、String、Symbol和Object八種數據類型，以及函數對應的Function類型，統一封裝成napi_value類型，下文中表述為JS類型，用于接收ArkUI應用傳遞過來的數據及返回數據給ArkUI應用。
這是一個不透明的指針，用于表示JavaScript值。

napi_ref

這是用來引用napi_value的抽象。這允許用戶管理JavaScript值的生命周期，包括顯式地定義它們的最小生命周期。
https://nodejs.org/docs/latest-v14.x/api/n-api.html#n_api_napi_ref

napi_env

napi_env用于表示上下文，底層的Node-API實現可以使用該上下文持久保持VM-specific的狀態。
https://nodejs.org/docs/latest-v14.x/api/n-api.html#n_api_napi_env

（2）將NapiTest類定義為js類

在定義js類之前，需要先設置js類對外導出的方法

// 在定義js類之前，需要先設置類對外導出的方法
    napi_property_descriptor desc[] = {
        { "getMsg", nullptr, NapiTest::GetMsg, nullptr, nullptr, nullptr, napi_default, nullptr },
        { "setMsg", nullptr, NapiTest::SetMsg, nullptr, nullptr, nullptr, napi_default, nullptr },
        { "create", nullptr, NapiTest::Create, nullptr, nullptr, nullptr, napi_default, nullptr }
    };

napi_property_descriptor

參考 https://nodejs.org/docs/latest-v14.x/api/n-api.html#n_api_napi_property_descriptor。

Node.js Node-API有一組API來獲取和設置JavaScript對象的屬性。在JavaScript中，屬性被表示為一個鍵和一個值的元組。基本上，Node-API中的所有屬性鍵都可以用以下形式中的任一一種表示:

Named:一個簡單的UTF-8編碼的字符串。
Integer-Indexed:索引值，由uint32_t表示。
JavaScript value:在Node-API中通過napi_value表示。它可以是一個napi_value，表示字符串、數字或符號。

typedef struct {
  // utf8name和name其中一個必須是NULL
  const char* utf8name;
  napi_value name;

  napi_callback method;
  napi_callback getter;
  napi_callback setter;
  napi_value value;

  napi_property_attributes attributes;
  void* data;
} napi_property_descriptor;

參數解析：

utf8name:在定義js類之前設置的js類對外導出的方法名字，編碼為UTF8。必須為該屬性提供utf8name或name中的一個。（utf8name和name其中一個必須是NULL）。
name:可選的napi_value，指向一個JavaScript字符串或符號，用作屬性的鍵。必須為該屬性提供utf8name或name中的一個。
method:將屬性描述符對象的value屬性設置為method表示的JavaScript函數。如果傳入這個參數，將value、getter和setter設置為NULL(因為這些成員不會被使用)。
attributes:與特定屬性相關聯的屬性。
data:調用函數時傳遞給method、getter和setter的callback data。

定義與C++類相對應的JavaScript類

napi_value constructor = nullptr;

    // 定義與C++類相對應的JavaScript類
    if (napi_define_class(env, NAPI_CLASS_NAME, NAPI_AUTO_LENGTH, Constructor, nullptr, sizeof(desc) / sizeof(desc[0]),
                          desc, &constructor) != napi_ok) {
        // "!="用來檢查兩個操作數的值是否相等，如果不相等則條件為真
        return nullptr;
    }

napi_define_class

napi_define_class函數說明:
https://nodejs.org/docs/latest-v14.x/api/n-api.html#n_api_napi_define_class

napi_status napi_define_class(napi_env env,
                          const char* utf8name,
                          size_t length,
                          napi_callback constructor,
                          void* data,
                          size_t property_count,
                          const napi_property_descriptor* properties,
                          napi_value* result);

功能：定義與C ++ 類相對應的JavaScript類。
參數說明：

[in] env: 調用api的環境。
[in] utf8name: C ++ 類的名稱。
[in] length: C ++ 類的名稱的長度，默認自動長度使用NAPI_AUTO_LENGTH。
[in] constructor: 處理C ++ 類實例構造的回調函數 (因為Constructor函數被napi_define_class調用了)。在導出C ++ 類對象時，這個函數必須是帶有napi_callback簽名（Constructor函數有napi_callback簽名是指要滿足typedef napi_value (*napi_callback)(napi_env, napi_callback_info);的形式）的靜態成員。不能使用c ++ 的類構造函數。
[in] data: 作為回調信息的數據屬性傳遞給構造函數回調的可選數據。
[in] property_count: 屬性數組中參數的個數。
[in] properties: 屬性數組，具體看代碼中napi_property_descriptor部分。
[out] result: 通過類構造函數綁定類實例的napi_value對象。
返回：如果API調用成功返回napi_ok。

JS構造函數。
如果一個js函數被使用new操作符來調用了，那么這個函數就稱之為js構造函數
C++類回調函數我們調用別人的API叫call，調用的第三方API調用我們的函數叫回調(callback)

實現js類的構造函數

當ArkTS應用在js端通過new方法獲取類對象的時候，此時會調用 napi_define_class 中設置的 constructor 回調函數，該函數實現方法如下：

napi_value NapiTest::Constructor(napi_env env, napi_callback_info info)
{
    napi_value undefineVar = nullptr, thisVar = nullptr;
    napi_get_undefined(env, &undefineVar);

    // 獲取傳入的參數對象，對象不為空，根據該參數創建實例并并綁定到該對象
    if (napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr) == napi_ok && thisVar != nullptr) {

        // 創建NapiTest 實例
        NapiTest *reference = new NapiTest(env);

        // 綁定實例到對象并獲取對象的生命周期
        if (napi_wrap(env, thisVar, reinterpret_cast<void *>(reference), NapiTest::Destructor, nullptr, &(reference->mRef)) == napi_ok) {
            return thisVar;
        }

        return thisVar;
    }
    
    return undefineVar;
}

void NapiTest::Destructor(napi_env env, void *nativeObject, void *finalize)
{
    // 釋放資源
    NapiTest *test = reinterpret_cast<NapiTest*>(nativeObject);
    test->~NapiTest();
}

NapiTest::Destructo方法是用來釋放創建的對象：

void NapiTest::Destructor(napi_env env, void *nativeObject, void *finalize)
{
    // 類析構函數，釋放資源
    NapiTest *test = reinterpret_cast<NapiTest*>(nativeObject);
    test->~NapiTest();
}

napi_wrap

napi_status napi_wrap(napi_env env,
                  napi_value js_object,
                  void* native_object,
                  napi_finalize finalize_cb,
                  void* finalize_hint,
                  napi_ref* result);

功能：將C++類實例綁定到js對象，并關聯對應的生命周期
參數說明：

[in] env: 調用api的環境。
[in] js_object: 綁定native_object的js對象。
[in] native_object: C++類實例對象。
[in] finalize_cb: 釋放實例對象的回調函數。
[in] finalize_hint: 傳遞給回調函數的數據。
[out] result: 綁定js對象的引用。

返回：調用成功返回0，失敗返回其他。

napi_get_cb_info

NAPI提供了napi_get_cb_info()方法可從napi_callback_info中獲取參數列表、this及其他數據。這個方法在constructor回調函數中使用，從給定的回調信息中檢索有關調用的詳細信息，如參數和This指針。

napi_status napi_get_cb_info(napi_env env,              
                             napi_callback_info cbinfo, 
                             size_t* argc,                          
                             napi_value* argv,     
                             napi_value* this_arg, 
                             void** data)

參數說明：

[in] env: 傳入接口調用者的環境，包含js引擎等，由框架提供，默認情況下直接傳入即可。
[in] cbinfo: napi_callback_info對象，上下文的信息。
[in-out] argc: argv數組的長度。若napi_callback_info中實際包含的參數的個數大于請求的數量argc，將只復制argc的值所指定數量的參數只argv中。若實際的參數個數小于請求的數量，將復制全部的參數，數組多余的空間用空值填充，并將參數實際長度寫入argc。
[out] argv: 用于接收參數列表。
[out] this_arg: 用于接收this對象。
[out] data: NAPI的上下文數據返回值：返回napi_ok表示轉換成功，其他值失敗。下面的返回napi_status方法一樣。

（3）導出js類

// 創建生命周期，初始引用計數設為1
    if (napi_create_reference(env, constructor, 1, &sConstructor_) != napi_ok) {
        return nullptr;
    }

    // 設置NapiTest對象相關屬性并綁定到導出變量exports
    if (napi_set_named_property(env, exports, NAPI_CLASS_NAME, constructor) != napi_ok) {
        return nullptr;
    }

在設置js類導出前，需要先創建生命周期

if (napi_create_reference(env, constructor , 1, &sConstructor_) != napi_ok) {
    return nullptr;
}

constructor 定義js類時返回的代表類的構造函數的數據。
sConstructor_ 生命周期變量。

napi_create_reference

napi_create_reference為對象創建一個reference，以延長其生命周期。調用者需要自己管理reference生命周期。

napi_create_reference函數說明：

NAPI_EXTERN napi_status napi_create_reference(napi_env env,
                                              napi_value value,
                                              uint32_t initial_refcount,
                                              napi_ref* result);

功能：通過引用對象創建新的生命周期引用對象。

[in] env: 調用 API 的環境。
[in] value: napi_value表示我們要引用的對象。
[in] initial_refcount: 生命周期變量的初始引用計數。
[out] result: 新建的生命周期引用對象。
返回 napi_ok 這個API就是成功的。

將生命周期變量作為導出對象的傳入屬性，并將js類導出到exports中

//  設置constructor對象相關屬性并綁定到導出變量exports
if (napi_set_named_property(env, exports, NAPI_CLASS_NAME, constructor) !=  napi_ok) {
    return nullptr;
}

napi_set_named_property

為給定對象的屬性設置一個名稱。

napi_status napi_set_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value value);

[in] env: 調用API的環境。
[in] object: NapiTest對象相關屬性要綁定的屬性值。
[in] utf8Name: js類的名稱。
[in] value: 要引用的對象。
返回 napi_ok 則這個API是成功的。

設置導出對象的屬性

hello.cpp中：

napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);

napi_define_properties

https://nodejs.org/docs/latest-v14.x/api/n-api.html#n_api_napi_define_properties。

napi_status napi_define_properties(napi_env env,
                                   napi_value object,
                                   size_t property_count,
                                   const napi_property_descriptor* properties);

作用：批量的向給定Object中定義屬性。

[in] env: 調用api的環境。
[in] object: js對象相關屬性的導出變量。
[in] property_count: 屬性數組中的元素數。
[in] properties: 屬性數組。

（4）創建類的實例對象

ArkTS應用除了調用new方法獲取類的實例外，我們也可以提供一些方法讓ArkTS應用獲取對應的類的實例，如在我們的NapiTest類中，定義了一個Create方法，該方法實現了NapiTest類實例的獲取。具體實現如下：

napi_value NapiTest::Create(napi_env env, napi_callback_info info) {
    napi_status status;
    napi_value constructor = nullptr, result = nullptr;
    // 獲取生命周期變量
    status = napi_get_reference_value(env, sConstructor_, &constructor);

    // 創建生命周期內的實例對象并將其返回
    status = napi_new_instance(env, constructor, 0, nullptr, &result);
    auto napiTest = new NapiTest();
    // 綁定實例類創建NapiTest到導出的對象result
    if (napi_wrap(env, result, reinterpret_cast<void *>(napiTest), Destructor,
        nullptr, &(napiTest->mRef)) == napi_ok) {
        return result;
    }
    
    return nullptr;
}

在napi接口的注冊中將該方法以接口的方式導出，應用層就可以直接調用該接口并獲取到該類的實例對。特別說明：如果單獨實現了一個類實例獲取的方法，那么js的類構造函數可以不實現(也就是定義js結構體時實際的構建函數Constructor及釋放資源的函數Destructor的代碼夠可以不寫)。

napi_get_reference_value

https://nodejs.org/docs/latest-v14.x/api/n-api.html#n_api_napi_get_reference_value。

函數說明：

NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
                                                 napi_ref ref,
                                                 napi_value* result);

作用：獲取與reference相關聯的js對象
[in] env: 調用API的環境
[in] ref: 生命周期管理的變量
[out] result: 對象引用的reference.

napi_new_instance

https://nodejs.org/docs/latest-v14.x/api/n-api.html#n_api_napi_new_instance。

napi_status napi_new_instance(napi_env env,
                              napi_value cons,
                              size_t argc,
                              napi_value* argv,
                              napi_value* result)

作用：通過給定的構造函數，構建一個對象。
[in] env: 調用API的環境。
[in] cons: napi_value表示要作為構造函數調用的 JavaScript 函數。
[in] argc: argv 數組中的元素計數。
[in] argv: JavaScript 值數組，表示構造函數的參數napi_value。
[out] result: napi_value表示返回的 JavaScript 對象。

2、 index.d.ts聲明文件編寫

使用NAPI框架代碼生成工具，可以根據.h生成.d.ts
?https://gitee.com/openharmony/napi_generator/blob/master/docs/INSTRUCTION_ZH.md。

export const create : () => NapiTest;
export class  NapiTest {
    setMsg(msg: string): void;
    getMsg(): string;
}

也可以寫成：

export class  NapiTest {
    create()；
    setMsg(msg: string): void;
    getMsg(): string;
}

3、CMakeLists.txt文件

# the minimum version of CMake.
cmake_minimum_required(VERSION 3.4.1)
project(ObjectWrapTest)

set(NATIVERENDER_ROOT_PATH ${CMAKE_CURRENT_SOURCE_DIR})

# 頭文件路徑
include_directories(${NATIVERENDER_ROOT_PATH}
                    ${NATIVERENDER_ROOT_PATH}/include)
# 動態庫源文件
add_library(entry SHARED hello.cpp NapiTest.cpp)
# 依賴libace_napi.z.so動態庫
target_link_libraries(entry PUBLIC libace_napi.z.so )

4、index.ets文件

// 讓IDE不檢查文件語法
// @ts-nocheck 
import testNapi from "libentry.so";

@Entry
@Component

struct Index {
  @State message: string = '導出對象'
  @State nativePointer:number = 0

// 創建對象tt
  tt = testNapi.create();

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            console.info("[NapiTest] Test NAPI 2 + 3 = " + testNapi.add(2, 3));
            try{
              if (this.nativePointer == 0) {
                // log打印,在程序中添加 log
                console.info("[NapiTest] Test NAPI add(2, 3) 1");
                this.nativePointer = testNapi.add(2, 3)
                console.info("[NapiTest] Test NAPI add(2, 3) 2");

                this.tt.setMsg("2+3")
                console.info("[NapiTest] Test NAPI add(2, 3) 3");

              } else {

                console.info("[NapiTest] Test NAPI add(0, 0) 1");

                this.nativePointer = testNapi.add(0, 0)
                console.info("[NapiTest] Test NAPI add(0, 0) 2");

                this.tt.setMsg("4+5")
                console.info("[NapiTest] Test NAPI add(0, 0) 3");
              }
            } catch(e) {
              console.info("[NapiTest]Test NAPI error" + JSON.stringify(e));
            }
            console.info("[NapiTest]Test NAPI " + this.tt.getMsg() + " = " + this.nativePointer);
          })
      }
      .width('100%')
    }
    .height('100%')
  }

}

知識點附送

napi接口名稱

https://gitee.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/native-lib/third_party_napi/napi.md

文章相關附件可以點擊下面的原文鏈接前往下載：

?? https://ost.51cto.com/resource/2579??