Node-API提供了相关接口对object进行基本操作,例如创建对象、获取原型、冻结和密封对象,检查对象的类型等。
在Node-API接口开发中,经常需要定义和操作对象。例如,创建一个API接口,该接口接受一个对象作为输入参数,对该对象执行某些操作,并返回一个结果对象。在这个过程中,需要确保接口的定义清晰、规范,并且与对象的属性和方法相兼容。
以下Node-API接口主要用于操作和管理ArkTS对象,使用场景介绍:
| 接口 | 描述 |
|---|---|
| napi_get_prototype | 当需要获取一个ArkTS对象的原型时,可以使用这个接口。通过这个接口可以在C/C++中获取到这个原型对象。 |
| napi_create_object | 在Node-API模块中创建一个默认的ArkTS对象。 |
| napi_object_freeze | 当需要确保一个对象不会被修改时(immutable),可以使用这个接口来冻结该对象,使其属性不可更改。 |
| napi_object_seal | 类似于napi_object_freeze,napi_object_seal用于密封给定的对象,使其属性不可添加或删除,但可以修改属性的值。 |
| napi_typeof | 在处理传入的ArkTS值时,可以使用这个接口来获取其类型,以便进行相应的处理。 |
| napi_instanceof | 当需要在Node-API模块中确定一个对象是否为特定构造函数的实例时,可以使用这个接口。 |
| napi_type_tag_object | 可以将指针的特定值与ArkTS对象关联起来,这对于一些自定义的内部对象标记非常有用。 |
| napi_check_object_type_tag | 使用此接口可以检查给定的对象上是否关联了特定类型的标记。 |
| napi_create_symbol | 创建一个ArkTS Symbol对象。 |
| napi_create_external | 用于创建一个ArkTS外部对象,该对象可以用于将C/C++中的自定义数据结构或对象传递到ArkTS中,并且可以在ArkTS中访问其属性和方法。 |
| napi_get_value_external | 用于获得napi_create_external创建的绑定了外部数据的ArkTS值,此函数可以在ArkTS和C/C++之间传递数据。 |
这些接口为开发人员提供了在Node-API模块中处理ArkTS对象的灵活性和功能性,可以实现从创建对象、管理对象属性和类型检查等多种操作。
Node-API接口开发流程参考使用Node-API实现跨语言交互开发流程,本文仅对接口对应C++及ArkTS相关代码进行展示。
可以获得给定ArkTS对象的prototype。
cpp部分代码
- // napi_get_prototype
- static napi_value GetPrototype(napi_env env, napi_callback_info info)
- {
- // 获取并解析传参
- size_t argc = 1;
- napi_value args[1] = {nullptr};
- napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
- napi_value result = nullptr;
- // 获取此对象的原型对象,将结果返回到napi_value类型的变量result中
- napi_get_prototype(env, args[0], &result);
- return result;
- }
接口声明
- export const getPrototype: (object: Object) => Object; // napi_get_prototype
ArkTS侧示例代码
- class Person {
- // 属性
- name: string;
- age: number;
- // 构造函数
- constructor(name: string, age: number) {
- this.name = name;
- this.age = age;
- }
- }
- // 创建类的实例
- const person = new Person('Alice', 30);
- // 传入实例对象,获取该对象的原型
- let personPrototype = testNapi.getPrototype(person);
- // 判断通过testNapi.getPrototype()函数获取到的原型是不是person的原型
- // 在DevEco Studio 4.1及以后的版本中,由于ArkTS没有原型的概念,
- // 因此尝试进行原型赋值或相关操作时,
- // 将会触发错误提示'Prototype assignment is not supported (arkts-no-prototype-assignment)',
- // 以下代码需在ts文件中执行
- if (personPrototype === Person.prototype) {
- hilog.info(0x0000, 'Node-API', 'get_prototype_success');
- } else {
- hilog.error(0x0000, 'Node-API', 'get_prototype_fail');
- }
用于在Node-API模块中创建一个空的ArkTS对象。
cpp部分代码
- // napi_create_object
- napi_value NewObject(napi_env env, napi_callback_info info)
- {
- napi_value object = nullptr;
- // 创建一个空对象
- napi_create_object(env, &object);
- // 设置对象的属性
- napi_value name = nullptr;
- // 设置属性名为"name"
- napi_create_string_utf8(env, "name", NAPI_AUTO_LENGTH, &name);
- napi_value value = nullptr;
- // 设置属性值为"Hello from Node-API!"
- napi_create_string_utf8(env, "Hello from Node-API!", NAPI_AUTO_LENGTH, &value);
- // 将属性设置到对象上
- napi_set_property(env, object, name, value);
- return object;
- }
接口声明
- export const createObject: () => { name: string }; // napi_create_object
ArkTS侧示例代码
- // napi_create_object
- try {
- const myObject = testNapi.createObject();
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_object: %{public}s', myObject.name);
- // ...
- } catch (error) {
- hilog.error(0x0000, 'testTag',
- 'Test Node-API napi_create_object errorCode: %{public}s, errorMessage: %{public}s', error.code,
- error.message);
- // ...
- }
用于冻结给定的ArkTS对象。冻结对象后,无法再向对象添加新的属性或方法,也无法修改已有属性或方法的值。
cpp部分代码
- // napi_object_freeze
- static napi_value ObjectFreeze(napi_env env, napi_callback_info info)
- {
- // 接受一个ArkTS侧传入的object
- size_t argc = 1;
- napi_value argv[1] = {nullptr};
- napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
-
- // 调用接口napi_object_freeze将传入的object冻结
- napi_value objFreeze = argv[0];
- napi_status status = napi_object_freeze(env, objFreeze);
- if (status == napi_ok) {
- OH_LOG_INFO(LOG_APP, "Node-API napi_object_freeze success");
- }
- // 将冻结后的object传回ArkTS侧
- return objFreeze;
- }
接口声明
- export interface Obj {
- data: number
- message: string
- }
-
- export const objectFreeze: (objFreeze: Object) => Obj; // napi_object_freeze
ArkTS侧示例代码
- // napi_object_freeze
- try {
- class Obj {
- public data: number = 0
- public message: string = ''
- }
-
- let obj: Obj = { data: 0, message: 'hello world' };
- let objFreeze = testNapi.objectFreeze(obj);
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_object_freeze: %{public}s', (objFreeze.data = 1));
- // ...
- } catch (error) {
- hilog.error(0x0000, 'testTag', 'Test Node-API napi_object_freeze error: %{public}s', error.message);
- // ...
- }
封闭一个对象后,无法向其添加新的属性,也无法删除或修改现有属性的可配置性。但是,可以继续修改已有属性的值。
cpp部分代码
- // napi_object_seal
- static napi_value ObjectSeal(napi_env env, napi_callback_info info)
- {
- // 接受一个ArkTS侧传入的object
- size_t argc = 1;
- napi_value argv[1] = {nullptr};
- napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr);
- // 调用接口napi_object_seal将传入的object封闭,使其无法添加新的属性
- napi_value objSeal = argv[0];
- napi_status status = napi_object_seal(env, objSeal);
- if (status == napi_ok) {
- OH_LOG_INFO(LOG_APP, "Node-API napi_object_seal success");
- } else {
- napi_throw_error(env, nullptr, "Node-API napi_object_seal failed");
- return nullptr;
- }
- // 将封闭后的object传回ArkTS侧
- return objSeal;
- }
接口声明
- export interface Obj1 {
- data: number
- message: string
- id: number
- }
-
- export const objectSeal: (objSeal: Object) => Obj1; // napi_object_seal
ArkTS侧示例代码
- // napi_object_seal
- try {
- class Obj {
- public data: number = 0
- public message: string = ''
- // 可选属性
- public address?: number = 0
- }
-
- let obj: Obj = { data: 0, message: 'hello world' };
- let objSeal = testNapi.objectSeal(obj);
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_object_seal: %{public}s', objSeal.message);
- objSeal.data = 1;
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_object_seal: %{public}d', objSeal.data);
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_object_seal: %{public}d', (objSeal.id = 1));
- // ...
- } catch (error) {
- hilog.error(0x0000, 'testTag', 'Test Node-API napi_object_seal error: %{public}s', error.message);
- // ...
- }
这个接口用于获取给定ArkTS value的ArkTS Type。
**注:**napi_typeof可以判断的类型包含:
| 类型 |
|---|
| undefined |
| null |
| boolean |
| number |
| string |
| object |
| function |
| bigint |
cpp部分代码
- // napi_typeof
- static napi_value NapiTypeOf(napi_env env, napi_callback_info info)
- {
- // 接受一个入参
- size_t argc = 1;
- napi_value args[1] = {nullptr};
- napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
-
- // 调用napi_typeof判断传入ArkTS参数类型
- napi_valuetype valueType;
- napi_status status = napi_typeof(env, args[0], &valueType);
- if (status != napi_ok) {
- napi_throw_error(env, nullptr, "Node-API napi_typeof fail");
- return nullptr;
- }
- // 将结果转成napi_value类型返回。
- napi_value returnValue = nullptr;
- switch (valueType) {
- case napi_undefined:
- napi_create_string_utf8(env, "Input type is napi_undefined", NAPI_AUTO_LENGTH, &returnValue);
- break;
- case napi_null:
- napi_create_string_utf8(env, "Input type is napi_null", NAPI_AUTO_LENGTH, &returnValue);
- break;
- case napi_boolean:
- napi_create_string_utf8(env, "Input type is napi_boolean", NAPI_AUTO_LENGTH, &returnValue);
- break;
- case napi_number:
- napi_create_string_utf8(env, "Input type is napi_number", NAPI_AUTO_LENGTH, &returnValue);
- break;
- case napi_string:
- napi_create_string_utf8(env, "Input type is napi_string", NAPI_AUTO_LENGTH, &returnValue);
- break;
- case napi_object:
- napi_create_string_utf8(env, "Input type is napi_object", NAPI_AUTO_LENGTH, &returnValue);
- break;
- case napi_function:
- napi_create_string_utf8(env, "Input type is napi_function", NAPI_AUTO_LENGTH, &returnValue);
- break;
- case napi_bigint:
- napi_create_string_utf8(env, "Input type is napi_bigint", NAPI_AUTO_LENGTH, &returnValue);
- break;
- default:
- napi_create_string_utf8(env, "unknown", NAPI_AUTO_LENGTH, &returnValue);
- }
- return returnValue;
- }
接口声明
- export const napiTypeOf: <T>(value: T) => string | undefined; // napi_typeof
ArkTS侧示例代码
- // napi_typeof
- try {
- let varUndefined: undefined;
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_typeof: %{public}s',
- testNapi.napiTypeOf(varUndefined));
- let varNull: null = null;
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_typeof: %{public}s',
- testNapi.napiTypeOf(varNull));
- let varTrue = true;
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_typeof: %{public}s',
- testNapi.napiTypeOf(varTrue));
- let varNum = 1;
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_typeof: %{public}s',
- testNapi.napiTypeOf(varNum));
- let varString = 'str';
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_typeof: %{public}s',
- testNapi.napiTypeOf(varString));
-
- class Obj {
- public id: number = 0
- public name: string = ''
- }
-
- let varObject: Obj = { id: 1, name: 'LiLei' };
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_typeof: %{public}s',
- testNapi.napiTypeOf(varObject));
- const addNum = (a: number, b: number): number => a * b;
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_typeof: %{public}s',
- testNapi.napiTypeOf(addNum));
- let varBigint = BigInt('1234567890123456789012345678901234567890');
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_typeof: %{public}s',
- testNapi.napiTypeOf(varBigint));
- // ...
- } catch (error) {
- hilog.error(0x0000, 'testTag', 'Test Node-API napi_typeof error: %{public}s', error.message);
- // ...
- }
用于检查一个对象是否是指定构造函数的实例。
cpp部分代码
- // napi_instanceof
- static napi_value NapiInstanceOf(napi_env env, napi_callback_info info)
- {
- // 接受两个入参
- size_t argc = 2;
- napi_value args[2] = {nullptr};
- napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
- // 调用napi_instanceof接口判断给定object是否为给定constructor的实例
- bool result = true;
- napi_status status = napi_instanceof(env, args[0], args[1], &result);
- if (status != napi_ok) {
- napi_throw_error(env, nullptr, "Node-API napi_instanceof fail");
- return nullptr;
- }
- // 将结果转成napi_value类型返回
- napi_value returnValue = nullptr;
- napi_get_boolean(env, result, &returnValue);
-
- return returnValue;
- }
接口声明
- export const napiInstanceOf: (date: Object, construct: Object) => boolean | undefined; // napi_instanceof
ArkTS侧示例代码
- // napi_instanceof
- try {
- class Person {
- public name: string;
- public age: number;
-
- constructor(name: string, age: number) {
- this.name = name;
- this.age = age;
- }
- }
-
- const person = new Person('Alice', 30);
-
- class Obj {
- public data: number = 0
- public message: string = ''
- }
-
- let obj: Obj = { data: 0, message: 'hello world' };
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_instanceof: %{public}s',
- testNapi.napiInstanceOf(person, Person));
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_instanceof: %{public}s',
- testNapi.napiInstanceOf(obj, Person));
- // ...
- } catch (error) {
- hilog.error(0x0000, 'testTag', 'Test Node-API napi_instanceof error: %{public}s', error.message);
- // ...
- }
使用类型标签type_tag来标记ArkTS对象,后续可以更精确地识别ArkTS对象。
ArkTS版本中,napi_type_tag_object接口没有使用private symbol,导致type_tag有被改写的风险,开发者应避免在关键安全场景中使用该接口。
验证一个ArkTS对象是否带有特定类型标签。
类型标签提供了一种在Node-API模块和ArkTS对象之间建立强类型关联的机制,使得原生代码能够更准确地识别和处理特定的ArkTS对象。
cpp部分代码
- #define NUMBERINT_FOUR 4
- // 定义一个静态常量napi_type_tag数组存储类型标签
- static const napi_type_tag TagsData[NUMBERINT_FOUR] = {
- {0x9e4b2449547061b3, 0x33999f8a6516c499},
- {0x1d55a794c53a726d, 0x43633f509f9c944e},
- // 用于表示无标签或默认标签
- {0, 0},
- {0x6a971439f5b2e5d7, 0x531dc28a7e5317c0},
- };
- // napi_type_tag_object
- static napi_value SetTypeTagToObject(napi_env env, napi_callback_info info)
- {
- // 获取函数调用信息和参数
- size_t argc = 2;
- napi_value args[2] = {nullptr};
- napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
- // 获取索引数字转换为napi_value
- int32_t index = 0;
- napi_get_value_int32(env, args[1], &index);
- // 给参数(对象)设置类型标签
- napi_status status = napi_type_tag_object(env, args[0], &TagsData[index]);
- if (status != napi_ok) {
- napi_throw_error(env, "Reconnect error", "napi_type_tag_object failed");
- return nullptr;
- }
- // 将bool结果转换为napi_value并返回
- napi_value result = nullptr;
- napi_get_boolean(env, true, &result);
- return result;
- }
- // napi_check_object_type_tag
- static napi_value CheckObjectTypeTag(napi_env env, napi_callback_info info)
- {
- // 获取函数调用信息和参数
- size_t argc = 2;
- napi_value args[2] = {nullptr};
- napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
- // 获取索引数字转换为napi_value
- int32_t index = 0;
- napi_get_value_int32(env, args[1], &index);
- // 检查对象的类型标签
- bool checkResult = true;
- napi_check_object_type_tag(env, args[0], &TagsData[index], &checkResult);
- // 将bool结果转换为napi_value并返回
- napi_value checked = nullptr;
- napi_get_boolean(env, checkResult, &checked);
-
- return checked;
- }
接口声明
- export const setTypeTagToObject: (obj: Object, index: number) => boolean | undefined; // napi_type_tag_object
-
- export const checkObjectTypeTag: (obj: Object, index: number) => boolean; // napi_check_object_type_tag
- // napi_type_tag_object and napi_check_object_type_tag
- class Obj {
- public data: number = 0
- public message: string = ''
- }
-
- let objA: Obj = { data: 0, message: 'hello world' };
- let objB: Obj = { data: 10, message: 'typeTag' };
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_type_tag_object objA -> 0: %{public}s',
- testNapi.setTypeTagToObject(objA, 0));
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_type_tag_object objB -> 0: %{public}s',
- testNapi.setTypeTagToObject(objB, 0));
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_check_object_type_tag objA -> 0: %{public}s',
- testNapi.checkObjectTypeTag(objA, 0));
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_check_object_type_tag objB -> 1: %{public}s',
- testNapi.checkObjectTypeTag(objB, 1));
创建自定义的C/C++对象并将其公开给ArkTS代码。这种情况下,我们可以使用napi_create_external来创建一个包含指向自定义对象的指针的Node-API值,以便让ArkTS代码能够访问和操作该对象。
cpp部分代码
- // 用于释放外部数据的回调函数
- void finalizeCallback(napi_env env, void *data, void *hint)
- {
- // 释放外部数据
- free(data);
- }
- // napi_create_external
- static napi_value GetExternalType(napi_env env, napi_callback_info info)
- {
- size_t argc = 1;
- napi_value args[1] = {nullptr};
- napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
- // 获取参数的数据类型
- napi_valuetype valueType;
- napi_typeof(env, args[0], &valueType);
- napi_value returnValue = nullptr;
- if (valueType == napi_external) {
- // 如果数据类型是napi_external,则返回true
- napi_get_boolean(env, true, &returnValue);
- } else {
- napi_get_boolean(env, false, &returnValue);
- }
- return returnValue;
- }
-
- static napi_value CreateExternal(napi_env env, napi_callback_info info)
- {
- // 设置外部数据大小为10
- const size_t dataSize = 10;
- // 分配外部数据
- void *data = malloc(dataSize);
- if (data == nullptr) {
- OH_LOG_ERROR(LOG_APP, "malloc failed");
- return nullptr;
- }
- // 初始化外部数据
- memset(data, 0, dataSize);
- napi_value result = nullptr;
- // 返回带有外部数据的对象
- napi_status status = napi_create_external(env, data, finalizeCallback, nullptr, &result);
- if (status != napi_ok) {
- OH_LOG_ERROR(LOG_APP, "Node-API Failed to create external data");
- free(data);
- return nullptr;
- }
- return result;
- }
接口声明
- export const createExternal: () => Object; // napi_create_external
-
- export const getExternalType: (externalData: Object) => boolean; // napi_create_external
ArkTS侧示例代码
- // napi_create_external
- const externalData = testNapi.createExternal();
- hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_external:%{public}s',
- testNapi.getExternalType(externalData));
napi_create_external可以创建包装自定义的C/C++对象并将其公开给ArkTS代码,而napi_get_value_external就是用来获得napi_create_external所创建的外部对象的。
cpp部分代码
- // napi_get_value_external
- static int g_external = 5;
- static napi_value GetValueExternal(napi_env env, napi_callback_info info)
- {
- // 创建外部数据
- int *data = &g_external;
- napi_value setExternal = nullptr;
- napi_create_external(env, data, nullptr, nullptr, &setExternal);
- // 获得外部数据的值
- void *getExternal;
- napi_get_value_external(env, setExternal, &getExternal);
- // 返回获得到的外部数据
- napi_value result = nullptr;
- napi_create_int32(env, *(int *)getExternal, &result);
- return result;
- }
接口声明
- export const getValueExternal: () => number; // napi_get_value_external
ArkTS侧示例代码
- // napi_get_value_external
- hilog.info(0x0000, 'Node-API', 'get_value_external:%{public}d', testNapi.getValueExternal());
用于创建一个新的Symbol。Symbol是一种特殊的数据类型,用于表示唯一的标识符。与字符串或数字不同,符号的值是唯一的,即使两个符号具有相同的描述,它们也是不相等的。符号通常用作对象属性的键,以确保属性的唯一性。
cpp部分代码
- // napi_create_symbol
- static napi_value CreateSymbol(napi_env env, napi_callback_info info)
- {
- napi_value result = nullptr;
- const char *des = "only";
- // 使用napi_create_string_utf8创建描述字符串
- napi_status status = napi_create_string_utf8(env, des, NAPI_AUTO_LENGTH, &result);
- if (status != napi_ok) {
- OH_LOG_ERROR(LOG_APP, "Node-API napi_create_string_utf8 failed");
- return nullptr;
- }
- napi_value returnSymbol = nullptr;
- // 创建一个symbol类型,并返回
- status = napi_create_symbol(env, result, &returnSymbol);
- if (status != napi_ok) {
- OH_LOG_ERROR(LOG_APP, "Node-API napi_create_symbol failed");
- return nullptr;
- }
- return returnSymbol;
- }
- export const createSymbol: () => symbol; // napi_create_symbol
ArkTS侧示例代码
- // napi_create_symbol
- let varSymbol = testNapi.createSymbol();
- hilog.info(0x0000, 'Node-API', 'createSymbol:%{public}s', typeof varSymbol);
以上代码如果要在native cpp中打印日志,需在CMakeLists.txt文件中添加以下配置信息(并添加头文件:#include "hilog/log.h"):
- // CMakeLists.txt
- add_definitions( "-DLOG_DOMAIN=0xd0d0" )
- add_definitions( "-DLOG_TAG=\"testTag\"" )
- target_link_libraries(entry PUBLIC libace_napi.z.so libhilog_ndk.z.so)