N-API在Android平臺應用的使用指導

N-API接口可以實現(xiàn)ArkTS/TS/JS與C/C++(Native)之間的交互，ArkUI-X中支持的N-API接口情況和使用場景請見[FFI能力(N-API)]。本文檔以[ArkUI-X/Samples]中的Native樣例工程為例，介紹如何在Android平臺上使用N-API能力完成跨語言調用。

開發(fā)流程

使用N-API完成跨語言調用的整體開發(fā)流程分為以下五步，即

1. 環(huán)境準備：獲取Native工程。
2. 提供Native能力：使用N-API接口提供Native能力，同時，Native接口中還可調用ArkTS/TS/JS傳入的方法。
3. 定義接口聲明：添加Native側暴露給ArkTS側接口的聲明。
4. 調用Native能力：ArkTS/TS/JS側使用Native能力。
5. 編譯與運行應用：編出應用，并在android平臺上運行，觀察效果。
6. 開發(fā)前請熟悉鴻蒙開發(fā)指導文檔 ：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]點擊或者復制轉到。

這里通過修改樣例工程，提供兩個例子來介紹N-API的典型使用場景：

1. 提供一個名為Add的Native方法，ArkTS側調用該方法并傳入兩個number，Native方法將這兩個number相加并返回到ArkTS側。以此介紹：ArkTS側如何調用到Native側方法。
2. 提供一個名為NativeCallArkTS的Native方法，ArkTS側調用該方法并傳入一個ArkTS function，Native方法中調用這個ArkTS function，并將其結果返回ArkTS側。以此介紹：Native側如何調用到ArkTS側方法。

1. 環(huán)境準備

從[ArkUI-X/Samples]中獲取Native樣例工程，并使用DevEco Studio(V4.0 Beta2及以上版本)打開該工程，打開后將自動進行工程初始化。

2. 提供Native能力

利用N-API接口，進行Native能力開發(fā)。同時，本樣例中的NativeCallArkTS也完成了Native側調ArkTS側的演示。

// entrysrcmaincpphello.cpp，包含Native側邏輯。
// 引入N-API相關頭文件。
#include "napi/native_api.h"

// 開發(fā)者提供的Native方法，入?yún)⒂星覂H有如下兩個，開發(fā)者不需進行變更。
// napi_env 為當前運行的上下文。
// napi_callback_info 記錄了一些信息，包括從ArkTS側傳遞過來參數(shù)等。
static napi_value Add(napi_env env, napi_callback_info info)
{
    // 期望從ArkTS側獲取的參數(shù)的數(shù)量，napi_value可理解為ArkTS value在Native方法中的表現(xiàn)形式。
    size_t argc = 2;
    napi_value args[2] = {nullptr};
    
    // 從info中，拿到從ArkTS側傳遞過來的參數(shù)，此處獲取了兩個ArkTS參數(shù)，即arg[0]和arg[1]。
    napi_get_cb_info(env, info, &argc, args , nullptr, nullptr);

    // 獲取arg[0]的類型
    napi_valuetype valuetype0 = napi_undefined;
    napi_typeof(env, args[0], &valuetype0);

    // 獲取arg[1]的類型
    napi_valuetype valuetype1 = napi_undefined;
    napi_typeof(env, args[1], &valuetype1);

    // 校驗入?yún)㈩愋停舨皇莕umber，則返回undefined
    if ((valuetype0 != napi_number) || (valuetype1 != napi_number)) {
        napi_value undefined = nullptr;
        napi_get_undefined(env, &undefined);
        return undefined;
    }

    // 將獲取的ArkTS參數(shù)轉換為Native信息，此處ArkTS側傳入了兩個number，這里將其轉換為Native側可以操作的double類型。
    double value0;
    napi_get_value_double(env, args[0], &value0);

    double value1;
    napi_get_value_double(env, args[1], &value1);
    
    // Native側的業(yè)務邏輯，這里簡單以兩數(shù)相加為例。
    double nativeSum = value0 + value1;
    
    // 此處將Native側業(yè)務邏輯處理結果轉換為ArkTS值，并返回給ArkTS。
    napi_value sum = nullptr;
    napi_create_double(env, nativeSum , &sum);
    return sum;
}

static napi_value NativeCallArkTS(napi_env env, napi_callback_info info)
{
    // 期望從ArkTS側獲取的參數(shù)的數(shù)量，napi_value可理解為ArkTS value在Native方法中的表現(xiàn)形式。
    size_t argc = 1;
    napi_value args[1] = {nullptr};
    
    // 從info中，拿到從ArkTS側傳遞過來的參數(shù)，此處獲取了一個ArkTS參數(shù)，即arg[0]。
    napi_get_cb_info(env, info, &argc, args , nullptr, nullptr);

    // 獲取arg[0]的類型
    napi_valuetype valuetype = napi_undefined;
    napi_typeof(env, args[0], &valuetype);

    // 校驗入?yún)㈩愋?/span>
    if (valuetype != napi_function) {
        napi_value undefined = nullptr;
        napi_get_undefined(env, &undefined);
        return undefined;
    }
    
    // 創(chuàng)建一個ArkTS string作為ArkTS function的入?yún)ⅰ?/span>
    napi_value argv = nullptr;
    // 創(chuàng)建一個js string
    napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &argv);
    
    napi_value result = nullptr;
    // Native方法中調用ArkTS function，其返回值保存到result中并返到ArkTS側。
    napi_call_function(env, nullptr, args[0], 1, &argv, &result);
    
    return result;
}

EXTERN_C_START
// Init將在exports上掛上Add/NativeCallArkTS這些Native方法，此處的exports就是開發(fā)者import之后獲取到的ArkTS對象。
static napi_value Init(napi_env env, napi_value exports)
{
    // 函數(shù)描述結構體，以Add為例，第三個參數(shù)"Add"為上述的Native方法，
    // 第一個參數(shù)"add"為ArkTS側對應方法的名稱。
    napi_property_descriptor desc[] = {
        { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr },
        { "nativeCallArkTS", nullptr, NativeCallArkTS, nullptr, nullptr, nullptr, napi_default, nullptr },
    };
    // 在exports這個ArkTS對象上，掛載Native方法。
    napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc);
    return exports;
}
EXTERN_C_END

// 準備模塊加載相關信息，將上述Init函數(shù)與本模塊名等信息記錄下來。
static napi_module demoModule = {
    .nm_version =1,
    .nm_flags = 0,
    .nm_filename = nullptr,
    .nm_register_func = Init,
    .nm_modname = "entry",
    .nm_priv = ((void*)0),
    .reserved = { 0 },
};

// 打開so時，該函數(shù)將自動被調用，使用上述demoModule模塊信息，進行模塊注冊相關動作。
extern "C" __attribute__((constructor)) void RegisterHelloModule(void)
{
    napi_module_register(&demoModule);
}

3. 定義接口聲明

在d.ts文件中添加暴露接口聲明

// entrysrcmaincpptypeslibentryindex.d.ts，包含Native側暴露給ArkTS側接口的聲明。
// Native側暴露給ArkTS側接口的聲明。
export const add: (a: number, b: number) = > number;
export const nativeCallArkTS: (a: object) = > string;

4. 調用Native能力

在ArkTS/TS/JS側使用Native能力。

1. entry.add接口完成了ArkTS -> Native的調用。
2. entry.nativeCallArkTS接口完成了ArkTS -> Native -> ArkTS的調用。

// entrysrcmainetspagesIndex.ets，包含ArkTS側邏輯。
// 通過import的方式，引入Native能力。
import entry from 'libentry.so'

function TestFunction(str) {
  let ret = str + ' world!'
  return ret;
}

@Entry
@Component
struct Index {
  @State message: string = 'Test native api: 2 + 3 = ?'
  @State message2: string = 'Click me'

  build() {
    Row() {
      Column() {
        // 第一個按鈕，調用add方法，對應到Native側的Add方法，進行兩數(shù)相加。
        Text(this.message)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() = > {
            this.message = "Test native api: 2 + 3 = " + entry.add(2, 3);
            console.log("Test NAPI 2 + 3 = " + entry.add(2, 3));
          })
        // 第二個按鈕，調用nativeCallArkTS方法，對應到Native的NativeCallArkTS，在Native中執(zhí)行ArkTS function。
        Text(this.message2)
          .fontSize(50)
          .fontWeight(FontWeight.Bold)
          .onClick(() = > {
            this.message2 = entry.nativeCallArkTS(TestFunction);
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

5. 編譯與運行應用

點擊DevEco Studio(V4.0 Beta2及以上版本)中的"Build > Build Hap(s)/APP(s) > Build APP(s)"進行編譯，并利用Android Studio打開Native工程的".arkui-xandroid"文件夾，點擊"Run app"按鈕后運行應用。應用運行后，點擊頁面上的兩個文本，文本做出相應變換。

開發(fā)建議

注冊建議

• nm_register_func對應的函數(shù)（如上述Init函數(shù)）需要加上static，防止與其他so里的符號沖突。
• 模塊注冊的入口，即使用__attribute__((constructor))修飾的函數(shù)的函數(shù)名（如上述RegisterHelloModule函數(shù)）需要確保不與其他模塊重復。

so命名規(guī)則

so命名必須符合以下規(guī)則：

• 每個模塊對應一個so。
• 如模塊名為entry，則so的名字為libentry.so，napi_module中nm_modname字段應為entry，大小寫與模塊名保持一致，應用使用時寫作：import entry from 'libentry.so'。

JS對象線程限制

ArkCompiler會對JS對象線程進行保護，使用不當會引起應用crash，因此需要遵循如下原則：

• N-API接口只能在JS線程使用。
• Native接口入?yún)⒌膃nv與線程綁定，不能跨線程使用。Native側JS對象只能在創(chuàng)建時的線程使用，即與線程所持有的env綁定。

頭文件引入限制

在引入頭文件時，需引入"napi/native_api.h"，否則會出現(xiàn)N-API接口無法找到的編譯報錯。

HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿

N-API在iOS平臺應用的使用指導

N-API接口可以實現(xiàn)ArkTS/TS/JS與C/C++(Native)之間的交互，ArkUI-X中支持的N-API接口情況和使用場景請見[FFI能力(N-API)]。N-API在iOS平臺上的使用方式中，除去"編譯與運行應用"環(huán)節(jié)與Android平臺略有差異外，其余部分均與Android平臺相同。本文檔將主要介紹N-API在iOS平臺上的"編譯與運行應用"環(huán)節(jié)，其他環(huán)節(jié)可參考[N-API在Android平臺應用的使用指導]。

編譯與運行應用

相較于Android平臺，iOS平臺上編譯/運行Native工程時需要進行簽名操作，完整步驟如下：

1. 點擊DevEco Studio(V4.0 Beta2及以上版本)中的"Build > Build Hap(s)/APP(s) > Build APP(s)"進行編譯。
2. 使用Xcode工具打開".arkui-xios"文件，在Xcode中完成簽名操作。
3. 點擊Xcode中的運行按鈕以完成二次打包，運行應用。