1# 使用Node-API扩展能力接口 2 3## 简介 4 5[扩展能力](napi-data-types-interfaces.md#扩展能力)接口进一步扩展了Node-API的功能，提供了一些额外的接口，用于在Node-API模块中与ArkTS进行更灵活的交互和定制，这些接口可以用于创建自定义ArkTS对象等场景。 6 7Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 8 9## 模块加载 10 11### 接口描述 12 13| 接口 | 描述 | 14| -------- | -------- | 15| napi_load_module | 用于在Node-API模块中将abc文件作为模块加载，返回模块的命名空间，适用于需要在运行时动态加载模块或资源的应用程序，从而实现灵活的扩展和定制。 | 16| napi_load_module_with_info | 用于在Node-API中进行模块的加载，当模块加载出来之后，可以使用函数napi_get_property获取模块导出的变量，也可以使用napi_get_named_property获取模块导出的函数，该函数可以在[新创建的ArkTs基础运行时环境](use-napi-ark-runtime.md)中使用。 | 17| napi_module_register | 有些功能可能需要通过Node-API模块来实现以获得更好的性能，通过将这些功能实现为自定义模块并注册到ArkTS环境中，可以在一定程度上提高整体的性能。 | 18 19### 使用示例 20 21#### napi_load_module 22 23[使用Node-API接口在主线程中进行模块加载](use-napi-load-module.md) 24 25#### napi_load_module_with_info 26 27[使用Node-API接口进行模块加载](use-napi-load-module-with-info.md) 28 29#### napi_module_register 30 31在ArkTS代码环境中使用Node-API模块编写的代码来实现特定的功能，可以将这部分功能封装成自定义模块，然后通过napi_module_register将其注册到ArkTS代码环境中，以实现功能的扩展和复用。 32 33cpp部分代码 34 35```cpp 36#include "napi/native_api.h" 37 38// 此模块是一个Node-API的回调函数 39static napi_value Add(napi_env env, napi_callback_info info) 40{ 41 // 接受传入两个参数 42 size_t requireArgc = 2; 43 size_t argc = 2; 44 napi_value args[2] = {nullptr}; 45 napi_get_cb_info(env, info, &argc, args , nullptr, nullptr); 46 47 // 将传入的napi_value类型的参数转化为double类型 48 double valueLift; 49 double valueRight; 50 napi_get_value_double(env, args[0], &valueLift); 51 napi_get_value_double(env, args[1], &valueRight); 52 53 // 将转化后的double值相加并转成napi_value返回给ArkTS代码使用 54 napi_value sum; 55 napi_create_double(env, valueLift + valueRight, &sum); 56 57 return sum; 58} 59 60// C++函数Init用于初始化插件，用于将ArkTS层的函数或属性与C++层的函数进行关联 61EXTERN_C_START 62static napi_value Init(napi_env env, napi_value exports) 63{ 64 // 通过napi_property_descriptor结构体，可以定义需要导出的属性，并在Node-API模块中使用。napi_define_properties将属性与实际的C++函数进行关联，使其可以被ArkTS层访问和调用 65 napi_property_descriptor desc[] = { 66 { "add", nullptr, Add, nullptr, nullptr, nullptr, napi_default, nullptr } 67 }; 68 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 69 return exports; 70} 71EXTERN_C_END 72 73// 插件的初始化被定义在一个名为demoModule的结构体中，其中包含了模块的基本信息，比如模块的版本号、注册函数等 74static napi_module demoModule = { 75 .nm_version =1, 76 .nm_flags = 0, 77 .nm_filename = nullptr, 78 .nm_register_func = Init, 79 .nm_modname = "entry", 80 .nm_priv = ((void*)0), 81 .reserved = { 0 }, 82}; 83 84// 在RegisterEntryModule函数中，使用napi_module_register函数注册并导出了这个插件 85extern "C" __attribute__((constructor)) void RegisterEntryModule(void) 86{ 87 napi_module_register(&demoModule); 88} 89``` 90 91接口声明 92 93```ts 94// index.d.ts 95export const add: (a: number, b: number) => number; 96``` 97 98ArkTS侧示例代码 99 100```ts 101import hilog from '@ohos.hilog' 102import testNapi from 'libentry.so' 103 104hilog.info(0x0000, 'testTag', 'Test Node-API 2 + 3 = %{public}d', testNapi.add(2, 3)); 105``` 106 107## ArkTS Object相关 108 109### 接口描述 110 111| 接口 | 描述 | 112| -------- | -------- | 113| napi_create_object_with_properties | 用于在Node-API模块中使用给定的napi_property_descriptor创建ArkTS Object。descriptor的键名必须为string，且不可转为number。 | 114| napi_create_object_with_named_properties | 用于在Node-API模块中使用给定的napi_value和键名创建ArkTS Object。键名必须为string，且不可转为number。 | 115 116### 使用示例 117 118#### napi_create_object_with_properties 119 120用给定的napi_property_descriptor作为属性去创建一个ArkTS对象，并且descriptor的键名必须为string，且不可转为number。 121 122cpp部分代码 123 124```cpp 125#include "napi/native_api.h" 126 127static napi_value CreateObjectWithProperties(napi_env env, napi_callback_info info) 128{ 129 size_t argc = 1; 130 napi_value argv[1] = nullptr; 131 // 获取解析传递的参数 132 napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); 133 // 声明了一个napi_property_descriptor数组desc，其中包含了一个名为"name"的属性，其值为传入的第一个参数argv[0]。 134 napi_property_descriptor desc[] = { 135 {"name", nullptr, nullptr, nullptr, nullptr, argv[0], napi_default_jsproperty, nullptr}}; 136 napi_value object = nullptr; 137 // 调用napi_create_object_with_properties来创建一个新的ArkTS对象，并将属性值添加到该对象中。 138 napi_create_object_with_properties(env, &object, sizeof(desc) / sizeof(desc[0]), desc); 139 napi_valuetype valueType; 140 napi_typeof(env, object, &valueType); 141 if (valueType == napi_object) { 142 return object; 143 } 144} 145``` 146 147接口声明 148 149```ts 150// index.d.ts 151export const createObjectWithProperties: (data: string) => Object; 152``` 153 154ArkTS侧示例代码 155 156```ts 157import hilog from '@ohos.hilog' 158import testNapi from 'libentry.so' 159 160let value = testNapi.createObjectWithProperties('createObject'); 161hilog.info(0x0000, 'testTag', 'Node-API napi_create_object_with_properties:%{public}s', JSON.stringify(value)); 162``` 163 164#### napi_create_object_with_named_properties 165 166用于使用给定的napi_value和键名创建一个ArkTS对象，并且给定的键名必须为string，且不可转为number。 167 168cpp部分代码 169 170```cpp 171#include "napi/native_api.h" 172 173static napi_value CreateObjectWithNameProperties(napi_env env, napi_callback_info info) 174{ 175 size_t argc = 1; 176 napi_value argv[1] = nullptr; 177 // 获取解析传递的参数 178 napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); 179 napi_value obj = nullptr; 180 const char *key[] = { 181 "name", 182 }; 183 const napi_value values[] = { 184 argv[0], 185 }; 186 napi_property_descriptor desc[] = {{"name", nullptr, nullptr, 187 nullptr, nullptr, nullptr, napi_default, nullptr}}; 188 napi_status status; 189 status = napi_create_object_with_named_properties(env, &obj, sizeof(desc) / sizeof(desc[0]), key, values); 190 if (status != napi_ok) { 191 return argv[0]; 192 } 193 return obj; 194} 195``` 196 197接口声明 198 199```ts 200// index.d.ts 201export const createObjectWithNameProperties: (data: string) => string | { name: string }; 202``` 203 204ArkTS侧示例代码 205 206```ts 207import hilog from '@ohos.hilog' 208import testNapi from 'libentry.so' 209 210let value = testNapi.createObjectWithNameProperties('ls'); 211hilog.info(0x0000, 'testTag', 'Node-API napi_create_object_with_named_properties:%{public}s', JSON.stringify(value)); 212``` 213 214## 运行指定abc文件 215 216### 接口描述 217 218| 接口 | 描述 | 219| -------- | -------- | 220| napi_run_script_path | 用于在Node-API模块中运行指定abc文件。 | 221 222### 使用示例 223 224#### napi_run_script_path 225 226在Node-API模块中运行abc文件。 227 228cpp部分代码 229 230```cpp 231#include "napi/native_api.h" 232 233static napi_value RunScriptPath(napi_env env, napi_callback_info info) 234{ 235 napi_value value = nullptr; 236 // 注意：记得在应用rawfile目录下放置.abc文件 237 const char *scriptPath = "/entry/resources/rawfile/test.abc"; 238 // 使用napi_run_script_path函数执行指定路径中的文件 239 napi_status status = napi_run_script_path(env, scriptPath, &value); 240 // 检查是否执行成功，如果失败，返回false 241 napi_value returnValue = nullptr; 242 if (value == nullptr || status != napi_ok) { 243 napi_get_boolean(env, false, &returnValue); 244 } else { 245 napi_get_boolean(env, true, &returnValue); 246 } 247 return returnValue; 248} 249``` 250 251接口声明 252 253```ts 254// index.d.ts 255export const runScriptPath: () => boolean; 256``` 257 258ArkTS侧示例代码 259 260```ts 261import hilog from '@ohos.hilog' 262import testNapi from 'libentry.so' 263 264try { 265 // 在此处执行错误返回false，成功就返回true 266 hilog.info(0x0000, 'testTag', 'Test Node-API napi_run_script_path: %{public}s', testNapi.runScriptPath()); 267} catch (error) { 268 hilog.error(0x0000, 'testTag', 'Test Node-API napi_run_script_path errorMessage: %{public}s', error.message); 269} 270``` 271 272test.js代码，将js代码编成.abc文件，步骤如下: 273 2741. 在SDK的ets/build-tools/ets-loader/bin/ark/build-win/bin目录下放置test.js文件 2752. 执行命令如es2abc.exe test.js --output test.abc后便可生成test.abc文件 276 277放入指定路径中：/entry/resources/rawfile 278 279```js 280function add(a, b) { 281 return a+b; 282} 283add(1, 2); 284``` 285 286## 异步工作对象加入队列并指定优先级 287 288### 接口描述 289 290| 接口 | 描述 | 291| -------- | -------- | 292| napi_queue_async_work_with_qos | 用于将异步工作对象加入队列，让开发者能够根据QoS优先级来管理和调度异步工作的执行，从而更好地满足程序的性能和响应需求。 | 293 294### 使用示例 295 296#### napi_queue_async_work_with_qos 297 298将异步工作对象加到队列，由底层根据传入的qos优先级去调度执行。 299 300<!--Del--> 301[指定异步任务调度优先级](../performance/develop-Native-modules-using-NAPI-safely-and-efficiently.md#指定异步任务调度优先级) 302<!--DelEnd--> 303 304## 给ArkTS对象绑定回调和回调所需的参数 305 306### 接口描述 307 308| 接口 | 描述 | 309| -------- | -------- | 310| napi_coerce_to_native_binding_object | 用于给ArkTS对象绑定回调和回调所需的参数，其作用是为了给ArkTS对象携带Native信息。 | 311 312### 使用示例 313 314#### napi_coerce_to_native_binding_object 315 316用于给ArkTS Object绑定回调和回调所需的参数，给ArkTS Object携带Native信息。 317 318cpp部分代码 319 320```cpp 321#include <bits/alltypes.h> 322#include <mutex> 323#include <unordered_set> 324#include <uv.h> 325#include "napi/native_api.h" 326 327class Object { 328public: 329 Object() = default; 330 ~Object() = default; 331 332 static Object* GetInstance() 333 { 334 Object* instance = new Object(); 335 return instance; 336 } 337 338 static napi_value GetAddress(napi_env env, napi_callback_info info) 339 { 340 napi_value thisVar = nullptr; 341 napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr); 342 if (thisVar == nullptr) { 343 return nullptr; 344 } 345 void* object = nullptr; 346 napi_unwrap(env, thisVar, &object); 347 if (object == nullptr) { 348 return nullptr; 349 } 350 uint64_t addressVal = reinterpret_cast<uint64_t>(object); 351 napi_value address = nullptr; 352 napi_create_bigint_uint64(env, addressVal, &address); 353 return address; 354 } 355 356 // 获取数组大小 357 static napi_value GetSetSize(napi_env env, napi_callback_info info) 358 { 359 napi_value thisVar = nullptr; 360 napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr); 361 if (thisVar == nullptr) { 362 return nullptr; 363 } 364 void* object = nullptr; 365 napi_unwrap(env, thisVar, &object); 366 if (object == nullptr) { 367 return nullptr; 368 } 369 std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_); 370 uint32_t setSize = reinterpret_cast<Object*>(object)->numberSet_.size(); 371 napi_value napiSize = nullptr; 372 napi_create_uint32(env, setSize, &napiSize); 373 return napiSize; 374 } 375 376 // 往数组里插入元素 377 static napi_value Store(napi_env env, napi_callback_info info) 378 { 379 size_t argc = 1; 380 napi_value args[1] = {nullptr}; 381 napi_value thisVar = nullptr; 382 napi_get_cb_info(env, info, &argc, args, &thisVar, nullptr); 383 if (argc != 1) { 384 napi_throw_error(env, nullptr, "Store args number must be one."); 385 return nullptr; 386 } 387 napi_valuetype type = napi_undefined; 388 napi_typeof(env, args[0], &type); 389 if (type != napi_number) { 390 napi_throw_error(env, nullptr, "Store args is not number."); 391 return nullptr; 392 } 393 if (thisVar == nullptr) { 394 return nullptr; 395 } 396 uint32_t value = 0; 397 napi_get_value_uint32(env, args[0], &value); 398 void* object = nullptr; 399 napi_unwrap(env, thisVar, &object); 400 if (object == nullptr) { 401 return nullptr; 402 } 403 std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_); 404 reinterpret_cast<Object *>(object)-> numberSet_.insert(value); 405 return nullptr; 406 } 407 408 // 删除数组元素 409 static napi_value Erase(napi_env env, napi_callback_info info) 410 { 411 size_t argc = 1; 412 napi_value args[1] = {nullptr}; 413 napi_value thisVar = nullptr; 414 napi_get_cb_info(env, info, &argc, args, &thisVar, nullptr); 415 if (argc != 1) { 416 napi_throw_error(env, nullptr, "Erase args number must be one."); 417 return nullptr; 418 } 419 napi_valuetype type = napi_undefined; 420 napi_typeof(env, args[0], &type); 421 if (type != napi_number) { 422 napi_throw_error(env, nullptr, "Erase args is not number."); 423 return nullptr; 424 } 425 if (thisVar == nullptr) { 426 return nullptr; 427 } 428 uint32_t value = 0; 429 napi_get_value_uint32(env, args[0], &value); 430 void* object = nullptr; 431 napi_unwrap(env, thisVar, &object); 432 if (object == nullptr) { 433 return nullptr; 434 } 435 std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_); 436 reinterpret_cast<Object *>(object)->numberSet_.erase(value); 437 return nullptr; 438 } 439 440 // 清空数组 441 static napi_value Clear(napi_env env, napi_callback_info info) 442 { 443 napi_value thisVar = nullptr; 444 napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr); 445 if (thisVar == nullptr) { 446 return nullptr; 447 } 448 void* object = nullptr; 449 napi_unwrap(env, thisVar, &object); 450 if (object == nullptr) { 451 return nullptr; 452 } 453 std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_); 454 reinterpret_cast<Object *>(object)->numberSet_.clear(); 455 return nullptr; 456 } 457 458private: 459 Object(const Object &) = delete; 460 Object &operator=(const Object &) = delete; 461 462 std::unordered_set<uint32_t> numberSet_{}; 463 std::mutex numberSetMutex_{}; 464}; 465 466void FinializeCallback(napi_env env, void *data, void *hint) 467{ 468 return; 469} 470 471// 解绑回调，在序列化时调用，可在对象解绑时执行一些清理操作 472void* DetachCallback(napi_env env, void *value, void *hint) 473{ 474 return value; 475} 476 477// 绑定回调，在反序列化时调用 478napi_value AttachCallback(napi_env env, void* value, void* hint) 479{ 480 napi_value object = nullptr; 481 napi_create_object(env, &object); 482 napi_property_descriptor desc[] = { 483 {"getAddress", nullptr, Object::GetAddress, nullptr, nullptr, nullptr, napi_default, nullptr}, 484 {"getSetSize", nullptr, Object::GetSetSize, nullptr, nullptr, nullptr, napi_default, nullptr}, 485 {"store", nullptr, Object::Store, nullptr, nullptr, nullptr, napi_default, nullptr}, 486 {"erase", nullptr, Object::Erase, nullptr, nullptr, nullptr, napi_default, nullptr}, 487 {"clear", nullptr, Object::Clear, nullptr, nullptr, nullptr, napi_default, nullptr}}; 488 napi_define_properties(env, object, sizeof(desc) / sizeof(desc[0]), desc); 489 // 将JS对象object和native对象value生命周期进行绑定 490 napi_wrap(env, object, value, FinializeCallback, nullptr, nullptr); 491 // JS对象携带native信息 492 napi_coerce_to_native_binding_object(env, object, DetachCallback, AttachCallback, value, hint); 493 return object; 494} 495 496EXTERN_C_START 497static napi_value Init(napi_env env, napi_value exports) 498{ 499 napi_property_descriptor desc[] = { 500 {"getAddress", nullptr, Object::GetAddress, nullptr, nullptr, nullptr, napi_default, nullptr}, 501 {"getSetSize", nullptr, Object::GetSetSize, nullptr, nullptr, nullptr, napi_default, nullptr}, 502 {"store", nullptr, Object::Store, nullptr, nullptr, nullptr, napi_default, nullptr}, 503 {"erase", nullptr, Object::Erase, nullptr, nullptr, nullptr, napi_default, nullptr}, 504 {"clear", nullptr, Object::Clear, nullptr, nullptr, nullptr, napi_default, nullptr}}; 505 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 506 auto object = Object::GetInstance(); 507 napi_wrap(env, exports, reinterpret_cast<void*>(object), FinializeCallback, nullptr, nullptr); 508 napi_coerce_to_native_binding_object(env, exports, DetachCallback, AttachCallback, reinterpret_cast<void*>(object), 509 nullptr); 510 return exports; 511} 512EXTERN_C_END 513 514static napi_module demoModule = { 515 .nm_version = 1, 516 .nm_flags = 0, 517 .nm_filename = nullptr, 518 .nm_register_func = Init, 519 .nm_modname = "entry", 520 .nm_priv = ((void*)0), 521 .reserved = { 0 }, 522}; 523 524extern "C" __attribute__((constructor)) void RegisterEntryModule(void) 525{ 526 napi_module_register(&demoModule); 527} 528``` 529 530接口声明 531 532```ts 533// index.d.ts 534export const getAddress: () => number; 535export const getSetSize: () => number; 536export const store: (a: number) => void; 537export const erase: (a: number) => void; 538export const clear: () => void; 539``` 540 541ArkTS侧示例代码 542 543```ts 544// index.ets 545import testNapi from 'libentry.so'; 546import taskpool from '@ohos.taskpool'; 547 548@Concurrent 549function getAddress() { 550 let address: number = testNapi.getAddress(); 551 console.info("taskpool:: address is " + address); 552} 553 554@Concurrent 555function store(a:number, b:number, c:number) { 556 let size:number = testNapi.getSetSize(); 557 console.info("set size is " + size + " before store"); 558 testNapi.store(a); 559 testNapi.store(b); 560 testNapi.store(c); 561 size = testNapi.getSetSize(); 562 console.info("set size is " + size + " after store"); 563} 564 565@Concurrent 566function erase(a:number) { 567 let size:number = testNapi.getSetSize(); 568 console.info("set size is " + size + " before erase"); 569 testNapi.erase(a); 570 size = testNapi.getSetSize(); 571 console.info("set size is " + size + " after erase"); 572} 573 574@Concurrent 575function clear() { 576 let size:number = testNapi.getSetSize(); 577 console.info("set size is " + size + " before clear"); 578 testNapi.clear(); 579 size = testNapi.getSetSize(); 580 console.info("set size is " + size + " after clear"); 581} 582 583let address:number = testNapi.getAddress(); 584console.info("host thread address is " + address); 585 586let task1 = new taskpool.Task(getAddress); 587await taskpool.execute(task1); 588 589let task2 = new taskpool.Task(store, 1, 2, 3); 590await taskpool.execute(task2); 591 592let task3 = new taskpool.Task(store, 4, 5, 6); 593await taskpool.execute(task3); 594 595let task4 = new taskpool.Task(erase, 3); 596await taskpool.execute(task4); 597 598let task5 = new taskpool.Task(erase, 5); 599await taskpool.execute(task5); 600 601let task6 = new taskpool.Task(clear); 602await taskpool.execute(task6); 603``` 604 605**注意事项** 606 607对ArkTs对象A调用`napi_coerce_to_native_binding_object`将开发者实现的detach/attach回调和native对象信息加到A上，再将A跨线程传递。跨线程传递需要对A进行序列化和反序列化，在当前线程thread1序列化A得到数据data，序列化阶段执行detach回调。然后将data传给目标线程thread2，在thread2中反序列化data，执行attach回调，最终得到ArkTS对象A。 608 609 610## 事件循环 611 612### 接口描述 613 614| 接口 | 描述 | 615| -------- | -------- | 616| napi_run_event_loop | 触发底层的事件循环。 | 617| napi_stop_event_loop | 停止底层的事件循环。 | 618 619### 使用示例 620 621#### napi_run_event_loop、napi_stop_event_loop 622 623[使用扩展的Node-API接口在异步线程中运行和停止事件循环](use-napi-event-loop.md) 624 625## ArkTS基础运行时环境 626 627### 接口描述 628 629| 接口 | 描述 | 630| -------- | -------- | 631| napi_create_ark_runtime | 创建基础运行时环境。 | 632| napi_destroy_ark_runtime | 销毁基础运行时环境。 | 633 634### 使用示例 635 636#### napi_create_ark_runtime、napi_destroy_ark_runtime 637 638[使用Node-API接口创建ArkTS运行时环境](use-napi-ark-runtime.md) 639 640## 序列化和反序列化 641 642### 接口描述 643 644| 接口 | 描述 | 645| -------- | -------- | 646| napi_serialize | 将ArkTS对象转换为native数据。第一个参数env是接口执行的ArkTS环境；第二个参数object是待序列化的ArkTS对象；第三个参数transfer_list是存放需要以transfer传递的arrayBuffer的array，如不涉及可传undefined；第四个参数clone_list是存放需要克隆传递的Sendable对象的array，如不涉及可传undefined；第五个参数result是序列化结果。 | 647| napi_deserialize | 将native数据转为ArkTS对象。第一个参数env是接口执行的ArkTS环境；第二个参数buffer是序列化数据；第三个参数object是反序列化得到的结果。 | 648| napi_delete_serialization_data | 删除序列化数据。 | 649 650### 使用示例 651 652#### napi_serialize、napi_deserialize、napi_delete_serialization_data 653 654用于将ArkTS对象转换为native数据、将native数据转为ArkTS对象、删除序列化数据等操作。 655 656cpp部分代码 657 658```cpp 659#include "napi/native_api.h" 660 661static napi_value AboutSerialize(napi_env env, napi_callback_info info) 662{ 663 // 获取传入的ts的一个对象作为参数 664 size_t argc = 1; 665 napi_value args[1] = {nullptr}; 666 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 667 napi_value undefined = nullptr; 668 // 构造napi_serialize方法所需参数 669 napi_get_undefined(env, &undefined); 670 void *data = nullptr; 671 // 调用napi_serialize方法将ts对象转化为native数据 672 napi_status status = napi_serialize(env, args[0], undefined, undefined, &data); 673 if (status != napi_ok ||data == nullptr) { 674 napi_throw_error(env, nullptr, "Node-API napi_serialize fail"); 675 return nullptr; 676 } 677 // 构造napi_value类型的数据，用于接收将native数据转化为ts对象后的数据 678 napi_value result = nullptr; 679 napi_deserialize(env, data, &result); 680 napi_value number = nullptr; 681 // 获取native数据转化为ts对象后的数据中的numKey属性的值 682 napi_get_named_property(env, result, "numKey", &number); 683 // 判断获取到的属性值是否为number类型 684 napi_valuetype valuetype; 685 napi_typeof(env, number, &valuetype); 686 if (valuetype != napi_number) { 687 napi_throw_error(env, nullptr, "Node-API Wrong type of argment. Expects a number."); 688 return nullptr; 689 } 690 // 调用napi_delete_serialization_data方法删除序列化数据 691 napi_delete_serialization_data(env, data); 692 // 返回获取到的属性值 693 return number; 694} 695``` 696 697接口声明 698 699```ts 700// index.d.ts 701export const aboutSerialize: (obj: Object) => number; 702``` 703 704ArkTS侧示例代码 705 706```ts 707import hilog from '@ohos.hilog' 708import testNapi from 'libentry.so' 709class Obj { 710 numKey:number = 0; 711} 712let obj: Obj = { numKey: 500 }; 713hilog.info(0x0000, 'testTag', ' Node-API aboutSerialize: %{public}d', testNapi.aboutSerialize(obj)); 714``` 715 716## 根据任务指定的优先级和入队方式进行处理异步线程向ArkTS线程投递的任务 717 718### 接口描述 719 720| 接口 | 描述 | 721| -------- | -------- | 722| napi_call_threadsafe_function_with_priority | 将指定优先级和入队方式的任务投递到ArkTS主线程。 | 723 724### 使用示例 725 726#### napi_call_threadsafe_function_with_priority 727 728[使用Node-API接口从异步线程向ArkTS线程投递指定优先级和入队方式的的任务](use-call-threadsafe-function-with-priority.md) 729 730## Sendable相关 731 732### 接口描述 733 734| 接口 | 描述 | 735| -------------------------- | ---------------------------------- | 736| napi_is_sendable | 判断给定ArkTS value是否是Sendable的。 | 737| napi_define_sendable_class | 创建一个sendable类。 | 738| napi_create_sendable_object_with_properties | 使用给定的napi_property_descriptor创建一个sendable对象。| 739| napi_create_sendable_array | 创建一个sendable数组。| 740| napi_create_sendable_array_with_length | 创建一个指定长度的sendable数组。| 741| napi_create_sendable_arraybuffer | 创建一个sendable ArrayBuffer。| 742| napi_create_sendable_typedarray | 创建一个sendable TypedArray。| 743| napi_wrap_sendable | 包裹一个native实例到ArkTS对象中。| 744| napi_wrap_sendable_with_size | 包裹一个native实例到ArkTS对象中并指定大小。| 745| napi_unwrap_sendable | 获取ArkTS对象包裹的native实例。| 746| napi_remove_wrap_sendable | 移除并获取ArkTS对象包裹的native实例。| 747 748### 使用示例 749 750#### napi_is_sendable 751 752判断给定ArkTS value是否是Sendable的。 753 754cpp部分代码 755 756```cpp 757#include "napi/native_api.h" 758 759static napi_value IsSendable(napi_env env, napi_callback_info info) { 760 size_t argc = 1; 761 napi_value args[1] = {nullptr}; 762 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 763 bool isSendable = false; 764 napi_is_sendable(env, args[0], &isSendable); 765 napi_value result; 766 napi_get_boolean(env, isSendable, &result); 767 return result; 768} 769``` 770 771接口声明 772 773```ts 774// index.d.ts 775export const isSendable: <T>(a: T) => boolean; 776``` 777 778ArkTS侧示例代码 779 780```ts 781import hilog from '@ohos.hilog' 782import testNapi from 'libentry.so' 783 784let value = testNapi.isSendable('createObject'); 785hilog.info(0x0000, 'testTag', 'Node-API napi_is_sendable: %{public}s', JSON.stringify(value)); 786``` 787 788#### napi_define_sendable_class 789 790创建一个sendable类。 791 792cpp部分代码 793 794```cpp 795#include "napi/native_api.h" 796 797static napi_value func(napi_env env, napi_callback_info info) { 798 napi_value val; 799 napi_create_string_utf8(env, "func result", NAPI_AUTO_LENGTH, &val); 800 return val; 801} 802 803static napi_value DefineSendableClass(napi_env env) { 804 napi_value str; 805 napi_create_string_utf8(env, "str", NAPI_AUTO_LENGTH, &str); 806 807 napi_property_descriptor props[] = { 808 {"staticStr", nullptr, nullptr, nullptr, nullptr, str, 809 static_cast<napi_property_attributes>(napi_static | napi_writable), nullptr}, 810 {"staticFunc", nullptr, func, nullptr, nullptr, nullptr, napi_static, nullptr}, 811 {"str", nullptr, nullptr, nullptr, nullptr, str, static_cast<napi_property_attributes>(1 << 9 | napi_writable), 812 nullptr}, 813 {"func", nullptr, nullptr, nullptr, nullptr, nullptr, 814 static_cast<napi_property_attributes>(1 << 11 | napi_writable), nullptr}, 815 }; 816 817 napi_value sendableClass = nullptr; 818 napi_define_sendable_class( 819 env, "SendableClass", NAPI_AUTO_LENGTH, 820 [](napi_env env, napi_callback_info info) -> napi_value { 821 napi_value thisVar = nullptr; 822 napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr); 823 napi_value str; 824 napi_create_string_utf8(env, "instance str", NAPI_AUTO_LENGTH, &str); 825 napi_property_descriptor props[] = { 826 {"str", nullptr, nullptr, nullptr, nullptr, str, napi_default, nullptr}, 827 {"func", nullptr, func, nullptr, nullptr, nullptr, napi_default, nullptr}, 828 }; 829 napi_define_properties(env, thisVar, sizeof(props) / sizeof(props[0]), props); 830 return thisVar; 831 }, 832 nullptr, sizeof(props) / sizeof(props[0]), props, nullptr, &sendableClass); 833 834 return sendableClass; 835} 836``` 837 838接口声明 839 840```ts 841// index.d.ts 842@Sendable 843export class SendableClass { 844 static staticStr: string; 845 static staticFunc(): string; 846 str: string; 847 func(): string; 848} 849``` 850 851ArkTS侧示例代码 852 853```ts 854import hilog from '@ohos.hilog' 855import testNapi from 'libentry.so' 856 857let value = new testNapi.SendableClass(); 858hilog.info(0x0000, 'testTag', 'Node-API napi_define_sendable_class: %{public}s', value.str); 859``` 860 861#### napi_create_sendable_object_with_properties 862 863使用给定的napi_property_descriptor创建一个sendable对象。 864 865cpp部分代码 866 867```cpp 868#include "napi/native_api.h" 869 870static napi_value GetSendableObject(napi_env env, napi_callback_info info) { 871 napi_value val_true; 872 napi_get_boolean(env, true, &val_true); 873 napi_property_descriptor desc1[] = { 874 {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr}, 875 }; 876 napi_value obj; 877 napi_create_sendable_object_with_properties(env, 1, desc1, &obj); 878 return obj; 879} 880``` 881 882接口声明 883 884```ts 885// index.d.ts 886export const getSendableObject: () => { x: true }; 887``` 888 889ArkTS侧示例代码 890 891```ts 892import hilog from '@ohos.hilog' 893import testNapi from 'libentry.so' 894 895let value = testNapi.getSendableObject(); 896hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_object_with_properties: %{public}s', JSON.stringify(value)); 897``` 898 899#### napi_create_sendable_array 900 901创建一个sendable数组。 902 903cpp部分代码 904 905```cpp 906#include "napi/native_api.h" 907 908static napi_value GetSendableArray(napi_env env, napi_callback_info info) { 909 napi_value result = nullptr; 910 napi_create_sendable_array(env, &result); 911 return result; 912} 913``` 914 915接口声明 916 917```ts 918// index.d.ts 919export const getSendableArray: () => []; 920``` 921 922ArkTS侧示例代码 923 924```ts 925import hilog from '@ohos.hilog' 926import testNapi from 'libentry.so' 927 928let value = testNapi.getSendableArray(); 929hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_array: %{public}s', JSON.stringify(value)); 930``` 931 932#### napi_create_sendable_array_with_length 933 934创建一个指定长度的sendable数组。 935 936cpp部分代码 937 938```cpp 939static napi_value GetSendableArrayWithLength(napi_env env, napi_callback_info info) { 940 napi_value result = nullptr; 941 napi_create_sendable_array_with_length(env, 1, &result); 942 return result; 943} 944``` 945 946接口声明 947 948```ts 949// index.d.ts 950export const getSendableArrayWithLength: () => []; 951``` 952 953ArkTS侧示例代码 954 955```ts 956import hilog from '@ohos.hilog' 957import testNapi from 'libentry.so' 958 959let value = testNapi.getSendableArrayWithLength(); 960hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_array_with_length: %{public}s', JSON.stringify(value.length)); 961``` 962 963#### napi_create_sendable_arraybuffer 964 965创建一个sendable ArrayBuffer。 966 967cpp部分代码 968 969```cpp 970#include "napi/native_api.h" 971#include "hilog/log.h" 972 973static napi_value GetSendableArrayBuffer(napi_env env, napi_callback_info info) { 974 static size_t LENGTH = 1024; 975 void *data; 976 napi_value result = nullptr; 977 napi_create_sendable_arraybuffer(env, LENGTH, &data, &result); 978 bool isArrayBuffer = false; 979 napi_is_arraybuffer(env, result, &isArrayBuffer); 980 OH_LOG_INFO(LOG_APP, "isArrayBuffer: %{public}d", isArrayBuffer); 981 return result; 982} 983``` 984 985接口声明 986 987```ts 988// index.d.ts 989export const getSendableArrayBuffer: () => void; 990``` 991 992ArkTS侧示例代码 993 994```ts 995import hilog from '@ohos.hilog' 996import testNapi from 'libentry.so' 997 998testNapi.getSendableArrayBuffer(); 999``` 1000 1001#### napi_create_sendable_typedarray 1002 1003创建一个sendable TypedArray。 1004 1005cpp部分代码 1006 1007```cpp 1008#include "napi/native_api.h" 1009#include "hilog/log.h" 1010 1011static napi_value GetSendableTypedArray(napi_env env, napi_callback_info info) { 1012 static size_t LENGTH = 1024; 1013 static size_t OFFSET = 0; 1014 void *data; 1015 napi_value arraybuffer = nullptr; 1016 napi_create_sendable_arraybuffer(env, LENGTH, &data, &arraybuffer); 1017 1018 napi_value result = nullptr; 1019 napi_create_sendable_typedarray(env, napi_uint8_array, LENGTH, arraybuffer, OFFSET, &result); 1020 bool isTypedArray = false; 1021 napi_is_typedarray(env, result, &isTypedArray); 1022 OH_LOG_INFO(LOG_APP, "isTypedArray: %{public}d", isTypedArray); 1023 return result; 1024} 1025``` 1026 1027接口声明 1028 1029```ts 1030// index.d.ts 1031export const getSendableTypedArray: () => void; 1032``` 1033 1034ArkTS侧示例代码 1035 1036```ts 1037import hilog from '@ohos.hilog' 1038import testNapi from 'libentry.so' 1039 1040testNapi.getSendableTypedArray(); 1041``` 1042 1043#### napi_wrap_sendable 1044 1045包裹一个native实例到ArkTS对象中。 1046 1047cpp部分代码 1048 1049```cpp 1050#include "napi/native_api.h" 1051 1052static napi_value WrapSendable(napi_env env, napi_callback_info info) { 1053 napi_value val_true; 1054 napi_get_boolean(env, true, &val_true); 1055 napi_property_descriptor desc1[] = { 1056 {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr}, 1057 }; 1058 napi_value obj; 1059 napi_create_sendable_object_with_properties(env, 1, desc1, &obj); 1060 1061 const char* testStr = "test"; 1062 napi_wrap_sendable(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr); 1063 1064 return nullptr; 1065} 1066``` 1067 1068接口声明 1069 1070```ts 1071// index.d.ts 1072export const wrapSendable: () => void; 1073``` 1074 1075ArkTS侧示例代码 1076 1077```ts 1078import hilog from '@ohos.hilog' 1079import testNapi from 'libentry.so' 1080 1081testNapi.wrapSendable(); 1082``` 1083 1084#### napi_wrap_sendable_with_size 1085 1086包裹一个native实例到ArkTS对象中并指定大小。 1087 1088cpp部分代码 1089 1090```cpp 1091#include "napi/native_api.h" 1092 1093static napi_value WrapSendableWithSize(napi_env env, napi_callback_info info) { 1094 napi_value val_true; 1095 napi_get_boolean(env, true, &val_true); 1096 napi_property_descriptor desc1[] = { 1097 {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr}, 1098 }; 1099 napi_value obj; 1100 napi_create_sendable_object_with_properties(env, 1, desc1, &obj); 1101 1102 const char* testStr = "test"; 1103 napi_wrap_sendable_with_size(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr, 100); 1104 1105 return nullptr; 1106} 1107``` 1108 1109接口声明 1110 1111```ts 1112// index.d.ts 1113export const wrapSendableWithSize: () => void; 1114``` 1115 1116ArkTS侧示例代码 1117 1118```ts 1119import hilog from '@ohos.hilog' 1120import testNapi from 'libentry.so' 1121 1122testNapi.wrapSendableWithSize(); 1123``` 1124 1125#### napi_unwrap_sendable 1126 1127获取ArkTS对象包裹的native实例。 1128 1129cpp部分代码 1130 1131```cpp 1132#include "napi/native_api.h" 1133 1134static napi_value UnwrapSendable(napi_env env, napi_callback_info info) { 1135 napi_value val_true; 1136 napi_get_boolean(env, true, &val_true); 1137 napi_property_descriptor desc1[] = { 1138 {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr}, 1139 }; 1140 napi_value obj; 1141 napi_create_sendable_object_with_properties(env, 1, desc1, &obj); 1142 1143 const char* testStr = "test"; 1144 napi_wrap_sendable(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr); 1145 1146 char* tmpTestStr = nullptr; 1147 napi_unwrap_sendable(env, obj, (void**)&tmpTestStr); 1148 OH_LOG_INFO(LOG_APP, "native value is %{public}s", tmpTestStr); 1149 1150 return nullptr; 1151} 1152``` 1153 1154接口声明 1155 1156```ts 1157// index.d.ts 1158export const unwrapSendable: () => void; 1159``` 1160 1161ArkTS侧示例代码 1162 1163```ts 1164import hilog from '@ohos.hilog' 1165import testNapi from 'libentry.so' 1166 1167testNapi.unwrapSendable(); 1168``` 1169 1170#### napi_remove_wrap_sendable 1171 1172移除并获取ArkTS对象包裹的native实例。 1173 1174cpp部分代码 1175 1176```cpp 1177#include "napi/native_api.h" 1178 1179static napi_value RemoveWrapSendable(napi_env env, napi_callback_info info) { 1180 napi_value val_true; 1181 napi_get_boolean(env, true, &val_true); 1182 napi_property_descriptor desc1[] = { 1183 {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr}, 1184 }; 1185 napi_value obj; 1186 napi_create_sendable_object_with_properties(env, 1, desc1, &obj); 1187 1188 const char* testStr = "test"; 1189 napi_wrap_sendable(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr); 1190 1191 char* tmpTestStr = nullptr; 1192 napi_remove_wrap_sendable(env, obj, (void**)&tmpTestStr); 1193 OH_LOG_INFO(LOG_APP, "native value is %{public}s", tmpTestStr); 1194 1195 return nullptr; 1196} 1197``` 1198 1199接口声明 1200 1201```ts 1202// index.d.ts 1203export const removeWrapSendable: () => void; 1204``` 1205 1206ArkTS侧示例代码 1207 1208```ts 1209import hilog from '@ohos.hilog' 1210import testNapi from 'libentry.so' 1211 1212testNapi.removeWrapSendable(); 1213``` 1214 1215以上代码如果要在native cpp中打印日志，需在CMakeLists.txt文件中添加以下配置信息（并添加头文件：#include "hilog/log.h"）： 1216 1217```text 1218// CMakeLists.txt 1219add_definitions( "-DLOG_DOMAIN=0xd0d0" ) 1220add_definitions( "-DLOG_TAG=\"testTag\"" ) 1221target_link_libraries(entry PUBLIC libhilog_ndk.z.so) 1222``` 1223
