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 <hilog/log.h> 323#include <mutex> 324#include <unordered_set> 325#include <uv.h> 326#include "napi/native_api.h" 327 328class Object { 329public: 330 Object() = default; 331 ~Object() = default; 332 333 static Object* GetInstance() 334 { 335 Object* instance = new Object(); 336 return instance; 337 } 338 339 static napi_value GetAddress(napi_env env, napi_callback_info info) 340 { 341 napi_value thisVar = nullptr; 342 napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr); 343 if (thisVar == nullptr) { 344 return nullptr; 345 } 346 void* object = nullptr; 347 napi_unwrap(env, thisVar, &object); 348 if (object == nullptr) { 349 return nullptr; 350 } 351 uint64_t addressVal = reinterpret_cast<uint64_t>(object); 352 napi_value address = nullptr; 353 napi_create_bigint_uint64(env, addressVal, &address); 354 return address; 355 } 356 357 // 获取数组大小 358 static napi_value GetSetSize(napi_env env, napi_callback_info info) 359 { 360 napi_value thisVar = nullptr; 361 napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr); 362 if (thisVar == nullptr) { 363 return nullptr; 364 } 365 void* object = nullptr; 366 napi_unwrap(env, thisVar, &object); 367 if (object == nullptr) { 368 return nullptr; 369 } 370 std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_); 371 uint32_t setSize = reinterpret_cast<Object*>(object)->numberSet_.size(); 372 napi_value napiSize = nullptr; 373 napi_create_uint32(env, setSize, &napiSize); 374 return napiSize; 375 } 376 377 // 往数组里插入元素 378 static napi_value Store(napi_env env, napi_callback_info info) 379 { 380 size_t argc = 1; 381 napi_value args[1] = {nullptr}; 382 napi_value thisVar = nullptr; 383 napi_get_cb_info(env, info, &argc, args, &thisVar, nullptr); 384 if (argc != 1) { 385 napi_throw_error(env, nullptr, "Store args number must be one."); 386 return nullptr; 387 } 388 napi_valuetype type = napi_undefined; 389 napi_typeof(env, args[0], &type); 390 if (type != napi_number) { 391 napi_throw_error(env, nullptr, "Store args is not number."); 392 return nullptr; 393 } 394 if (thisVar == nullptr) { 395 return nullptr; 396 } 397 uint32_t value = 0; 398 napi_get_value_uint32(env, args[0], &value); 399 void* object = nullptr; 400 napi_unwrap(env, thisVar, &object); 401 if (object == nullptr) { 402 return nullptr; 403 } 404 std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_); 405 reinterpret_cast<Object *>(object)-> numberSet_.insert(value); 406 return nullptr; 407 } 408 409 // 删除数组元素 410 static napi_value Erase(napi_env env, napi_callback_info info) 411 { 412 size_t argc = 1; 413 napi_value args[1] = {nullptr}; 414 napi_value thisVar = nullptr; 415 napi_get_cb_info(env, info, &argc, args, &thisVar, nullptr); 416 if (argc != 1) { 417 napi_throw_error(env, nullptr, "Erase args number must be one."); 418 return nullptr; 419 } 420 napi_valuetype type = napi_undefined; 421 napi_typeof(env, args[0], &type); 422 if (type != napi_number) { 423 napi_throw_error(env, nullptr, "Erase args is not number."); 424 return nullptr; 425 } 426 if (thisVar == nullptr) { 427 return nullptr; 428 } 429 uint32_t value = 0; 430 napi_get_value_uint32(env, args[0], &value); 431 void* object = nullptr; 432 napi_unwrap(env, thisVar, &object); 433 if (object == nullptr) { 434 return nullptr; 435 } 436 std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_); 437 reinterpret_cast<Object *>(object)->numberSet_.erase(value); 438 return nullptr; 439 } 440 441 // 清空数组 442 static napi_value Clear(napi_env env, napi_callback_info info) 443 { 444 napi_value thisVar = nullptr; 445 napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr); 446 if (thisVar == nullptr) { 447 return nullptr; 448 } 449 void* object = nullptr; 450 napi_unwrap(env, thisVar, &object); 451 if (object == nullptr) { 452 return nullptr; 453 } 454 std::lock_guard<std::mutex> lock(reinterpret_cast<Object*>(object)->numberSetMutex_); 455 reinterpret_cast<Object *>(object)->numberSet_.clear(); 456 return nullptr; 457 } 458 459private: 460 Object(const Object &) = delete; 461 Object &operator=(const Object &) = delete; 462 463 std::unordered_set<uint32_t> numberSet_{}; 464 std::mutex numberSetMutex_{}; 465}; 466 467void FinializerCallback(napi_env env, void *data, void *hint) 468{ 469 return; 470} 471 472// 解绑回调，在序列化时调用，可在对象解绑时执行一些清理操作 473void* DetachCallback(napi_env env, void *value, void *hint) 474{ 475 return value; 476} 477 478// 绑定回调，在反序列化时调用 479napi_value AttachCallback(napi_env env, void* value, void* hint) 480{ 481 napi_value object = nullptr; 482 napi_create_object(env, &object); 483 napi_property_descriptor desc[] = { 484 {"getAddress", nullptr, Object::GetAddress, nullptr, nullptr, nullptr, napi_default, nullptr}, 485 {"getSetSize", nullptr, Object::GetSetSize, nullptr, nullptr, nullptr, napi_default, nullptr}, 486 {"store", nullptr, Object::Store, nullptr, nullptr, nullptr, napi_default, nullptr}, 487 {"erase", nullptr, Object::Erase, nullptr, nullptr, nullptr, napi_default, nullptr}, 488 {"clear", nullptr, Object::Clear, nullptr, nullptr, nullptr, napi_default, nullptr}}; 489 napi_define_properties(env, object, sizeof(desc) / sizeof(desc[0]), desc); 490 // 将JS对象object和native对象value生命周期进行绑定 491 napi_status status = napi_wrap(env, object, value, FinializerCallback, nullptr, nullptr); 492 if (status != napi_ok) { 493 OH_LOG_INFO(LOG_APP, "Node-API attachCallback is failed."); 494 } 495 // JS对象携带native信息 496 napi_coerce_to_native_binding_object(env, object, DetachCallback, AttachCallback, value, hint); 497 return object; 498} 499 500EXTERN_C_START 501static napi_value Init(napi_env env, napi_value exports) 502{ 503 napi_property_descriptor desc[] = { 504 {"getAddress", nullptr, Object::GetAddress, nullptr, nullptr, nullptr, napi_default, nullptr}, 505 {"getSetSize", nullptr, Object::GetSetSize, nullptr, nullptr, nullptr, napi_default, nullptr}, 506 {"store", nullptr, Object::Store, nullptr, nullptr, nullptr, napi_default, nullptr}, 507 {"erase", nullptr, Object::Erase, nullptr, nullptr, nullptr, napi_default, nullptr}, 508 {"clear", nullptr, Object::Clear, nullptr, nullptr, nullptr, napi_default, nullptr}}; 509 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 510 auto object = Object::GetInstance(); 511 napi_status status = napi_wrap(env, exports, reinterpret_cast<void*>(object), FinializerCallback, nullptr, nullptr); 512 if (status != napi_ok) { 513 delete object; 514 } 515 napi_coerce_to_native_binding_object(env, exports, DetachCallback, AttachCallback, reinterpret_cast<void*>(object), 516 nullptr); 517 return exports; 518} 519EXTERN_C_END 520 521static napi_module demoModule = { 522 .nm_version = 1, 523 .nm_flags = 0, 524 .nm_filename = nullptr, 525 .nm_register_func = Init, 526 .nm_modname = "entry", 527 .nm_priv = ((void*)0), 528 .reserved = { 0 }, 529}; 530 531extern "C" __attribute__((constructor)) void RegisterEntryModule(void) 532{ 533 napi_module_register(&demoModule); 534} 535``` 536 537接口声明 538 539```ts 540// index.d.ts 541export const getAddress: () => number; 542export const getSetSize: () => number; 543export const store: (a: number) => void; 544export const erase: (a: number) => void; 545export const clear: () => void; 546``` 547 548ArkTS侧示例代码 549 550```ts 551// index.ets 552import testNapi from 'libentry.so'; 553import taskpool from '@ohos.taskpool'; 554 555@Concurrent 556function getAddress() { 557 let address: number = testNapi.getAddress(); 558 console.info("taskpool:: address is " + address); 559} 560 561@Concurrent 562function store(a:number, b:number, c:number) { 563 let size:number = testNapi.getSetSize(); 564 console.info("set size is " + size + " before store"); 565 testNapi.store(a); 566 testNapi.store(b); 567 testNapi.store(c); 568 size = testNapi.getSetSize(); 569 console.info("set size is " + size + " after store"); 570} 571 572@Concurrent 573function erase(a:number) { 574 let size:number = testNapi.getSetSize(); 575 console.info("set size is " + size + " before erase"); 576 testNapi.erase(a); 577 size = testNapi.getSetSize(); 578 console.info("set size is " + size + " after erase"); 579} 580 581@Concurrent 582function clear() { 583 let size:number = testNapi.getSetSize(); 584 console.info("set size is " + size + " before clear"); 585 testNapi.clear(); 586 size = testNapi.getSetSize(); 587 console.info("set size is " + size + " after clear"); 588} 589 590async function test01(): Promise<void> { 591 let address:number = testNapi.getAddress(); 592 console.info("host thread address is " + address); 593 594 let task1 = new taskpool.Task(getAddress); 595 await taskpool.execute(task1); 596 597 let task2 = new taskpool.Task(store, 1, 2, 3); 598 await taskpool.execute(task2); 599 600 let task3 = new taskpool.Task(store, 4, 5, 6); 601 await taskpool.execute(task3); 602 603 let task4 = new taskpool.Task(erase, 3); 604 await taskpool.execute(task4); 605 606 let task5 = new taskpool.Task(erase, 5); 607 await taskpool.execute(task5); 608 609 let task6 = new taskpool.Task(clear); 610 await taskpool.execute(task6); 611} 612 613test01(); 614``` 615 616**注意事项** 617 618对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。 619 620 621 622## 事件循环 623 624### 接口描述 625 626| 接口 | 描述 | 627| -------- | -------- | 628| napi_run_event_loop | 触发底层的事件循环。 | 629| napi_stop_event_loop | 停止底层的事件循环。 | 630 631### 使用示例 632 633#### napi_run_event_loop、napi_stop_event_loop 634 635[使用扩展的Node-API接口在异步线程中运行和停止事件循环](use-napi-event-loop.md) 636 637## ArkTS基础运行时环境 638 639### 接口描述 640 641| 接口 | 描述 | 642| -------- | -------- | 643| napi_create_ark_runtime | 创建基础运行时环境。 | 644| napi_destroy_ark_runtime | 销毁基础运行时环境。 | 645 646### 使用示例 647 648#### napi_create_ark_runtime、napi_destroy_ark_runtime 649 650[使用Node-API接口创建ArkTS运行时环境](use-napi-ark-runtime.md) 651 652## 序列化和反序列化 653 654### 接口描述 655 656| 接口 | 描述 | 657| -------- | -------- | 658| napi_serialize | 将ArkTS对象转换为native数据。第一个参数env是接口执行的ArkTS环境；第二个参数object是待序列化的ArkTS对象；第三个参数transfer_list是存放需要以transfer传递的arrayBuffer的array，如不涉及可传undefined；第四个参数clone_list是存放需要克隆传递的Sendable对象的array，如不涉及可传undefined；第五个参数result是序列化结果。 | 659| napi_deserialize | 将native数据转为ArkTS对象。第一个参数env是接口执行的ArkTS环境；第二个参数buffer是序列化数据；第三个参数object是反序列化得到的结果。 | 660| napi_delete_serialization_data | 删除序列化数据。 | 661 662### 使用示例 663 664#### napi_serialize、napi_deserialize、napi_delete_serialization_data 665 666用于将ArkTS对象转换为native数据、将native数据转为ArkTS对象、删除序列化数据等操作。 667 668cpp部分代码 669 670```cpp 671#include "napi/native_api.h" 672 673static napi_value AboutSerialize(napi_env env, napi_callback_info info) 674{ 675 // 获取传入的ts的一个对象作为参数 676 size_t argc = 1; 677 napi_value args[1] = {nullptr}; 678 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 679 napi_value undefined = nullptr; 680 // 构造napi_serialize方法所需参数 681 napi_get_undefined(env, &undefined); 682 void *data = nullptr; 683 // 调用napi_serialize方法将ts对象转化为native数据 684 napi_status status = napi_serialize(env, args[0], undefined, undefined, &data); 685 if (status != napi_ok ||data == nullptr) { 686 napi_throw_error(env, nullptr, "Node-API napi_serialize fail"); 687 return nullptr; 688 } 689 // 构造napi_value类型的数据，用于接收将native数据转化为ts对象后的数据 690 napi_value result = nullptr; 691 napi_deserialize(env, data, &result); 692 napi_value number = nullptr; 693 // 获取native数据转化为ts对象后的数据中的numKey属性的值 694 napi_get_named_property(env, result, "numKey", &number); 695 // 判断获取到的属性值是否为number类型 696 napi_valuetype valuetype; 697 napi_typeof(env, number, &valuetype); 698 if (valuetype != napi_number) { 699 napi_throw_error(env, nullptr, "Node-API Wrong type of argument. Expects a number."); 700 return nullptr; 701 } 702 // 调用napi_delete_serialization_data方法删除序列化数据 703 napi_delete_serialization_data(env, data); 704 // 返回获取到的属性值 705 return number; 706} 707``` 708 709接口声明 710 711```ts 712// index.d.ts 713export const aboutSerialize: (obj: Object) => number; 714``` 715 716ArkTS侧示例代码 717 718```ts 719import hilog from '@ohos.hilog' 720import testNapi from 'libentry.so' 721class Obj { 722 numKey:number = 0; 723} 724let obj: Obj = { numKey: 500 }; 725hilog.info(0x0000, 'testTag', ' Node-API aboutSerialize: %{public}d', testNapi.aboutSerialize(obj)); 726``` 727 728## 根据任务指定的优先级和入队方式进行处理异步线程向ArkTS线程投递的任务 729 730### 接口描述 731 732| 接口 | 描述 | 733| -------- | -------- | 734| napi_call_threadsafe_function_with_priority | 将指定优先级和入队方式的任务投递到ArkTS主线程。 | 735 736### 使用示例 737 738#### napi_call_threadsafe_function_with_priority 739 740[使用Node-API接口从异步线程向ArkTS线程投递指定优先级和入队方式的的任务](use-call-threadsafe-function-with-priority.md) 741 742## Sendable相关 743 744### 接口描述 745 746| 接口 | 描述 | 747| -------------------------- | ---------------------------------- | 748| napi_is_sendable | 判断给定ArkTS value是否是Sendable的。 | 749| napi_define_sendable_class | 创建一个sendable类。 | 750| napi_create_sendable_object_with_properties | 使用给定的napi_property_descriptor创建一个sendable对象。| 751| napi_create_sendable_array | 创建一个sendable数组。| 752| napi_create_sendable_array_with_length | 创建一个指定长度的sendable数组。| 753| napi_create_sendable_arraybuffer | 创建一个sendable ArrayBuffer。| 754| napi_create_sendable_typedarray | 创建一个sendable TypedArray。| 755| napi_wrap_sendable | 包裹一个native实例到ArkTS对象中。| 756| napi_wrap_sendable_with_size | 包裹一个native实例到ArkTS对象中并指定大小。| 757| napi_unwrap_sendable | 获取ArkTS对象包裹的native实例。| 758| napi_remove_wrap_sendable | 移除并获取ArkTS对象包裹的native实例。| 759 760### 使用示例 761 762#### napi_is_sendable 763 764判断给定ArkTS value是否是Sendable的。 765 766cpp部分代码 767 768```cpp 769#include "napi/native_api.h" 770 771static napi_value IsSendable(napi_env env, napi_callback_info info) { 772 size_t argc = 1; 773 napi_value args[1] = {nullptr}; 774 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 775 bool isSendable = false; 776 napi_is_sendable(env, args[0], &isSendable); 777 napi_value result; 778 napi_get_boolean(env, isSendable, &result); 779 return result; 780} 781``` 782 783接口声明 784 785```ts 786// index.d.ts 787export const isSendable: <T>(a: T) => boolean; 788``` 789 790ArkTS侧示例代码 791 792```ts 793import hilog from '@ohos.hilog' 794import testNapi from 'libentry.so' 795 796let value = testNapi.isSendable('createObject'); 797hilog.info(0x0000, 'testTag', 'Node-API napi_is_sendable: %{public}s', JSON.stringify(value)); 798``` 799 800#### napi_define_sendable_class 801 802创建一个sendable类。 803 804cpp部分代码 805 806```cpp 807#include "napi/native_api.h" 808 809static napi_value func(napi_env env, napi_callback_info info) { 810 napi_value val; 811 napi_create_string_utf8(env, "func result", NAPI_AUTO_LENGTH, &val); 812 return val; 813} 814 815static napi_value DefineSendableClass(napi_env env) { 816 napi_value str; 817 napi_create_string_utf8(env, "str", NAPI_AUTO_LENGTH, &str); 818 819 napi_property_descriptor props[] = { 820 {"staticStr", nullptr, nullptr, nullptr, nullptr, str, 821 static_cast<napi_property_attributes>(napi_static | napi_writable), nullptr}, 822 {"staticFunc", nullptr, func, nullptr, nullptr, nullptr, napi_static, nullptr}, 823 {"str", nullptr, nullptr, nullptr, nullptr, str, static_cast<napi_property_attributes>(1 << 9 | napi_writable), 824 nullptr}, 825 {"func", nullptr, nullptr, nullptr, nullptr, nullptr, 826 static_cast<napi_property_attributes>(1 << 11 | napi_writable), nullptr}, 827 }; 828 829 napi_value sendableClass = nullptr; 830 napi_define_sendable_class( 831 env, "SendableClass", NAPI_AUTO_LENGTH, 832 [](napi_env env, napi_callback_info info) -> napi_value { 833 napi_value thisVar = nullptr; 834 napi_get_cb_info(env, info, nullptr, nullptr, &thisVar, nullptr); 835 napi_value str; 836 napi_create_string_utf8(env, "instance str", NAPI_AUTO_LENGTH, &str); 837 napi_property_descriptor props[] = { 838 {"str", nullptr, nullptr, nullptr, nullptr, str, napi_default, nullptr}, 839 {"func", nullptr, func, nullptr, nullptr, nullptr, napi_default, nullptr}, 840 }; 841 napi_define_properties(env, thisVar, sizeof(props) / sizeof(props[0]), props); 842 return thisVar; 843 }, 844 nullptr, sizeof(props) / sizeof(props[0]), props, nullptr, &sendableClass); 845 846 return sendableClass; 847} 848 849EXTERN_C_START 850static napi_value Init(napi_env env, napi_value exports) 851{ 852 napi_property_descriptor desc[] = {}; 853 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 854 napi_value cons = DefineSendableClass(env); 855 napi_set_named_property(env, exports, "SendableClass", cons); 856 return exports; 857} 858EXTERN_C_END 859 860static napi_module demoModule = { 861 .nm_version = 1, 862 .nm_flags = 0, 863 .nm_filename = nullptr, 864 .nm_register_func = Init, 865 .nm_modname = "entry", 866 .nm_priv = ((void*)0), 867 .reserved = { 0 }, 868}; 869 870extern "C" __attribute__((constructor)) void RegisterEntryModule(void) 871{ 872 napi_module_register(&demoModule); 873} 874``` 875 876接口声明 877 878```ts 879// index.d.ts 880@Sendable 881export class SendableClass { 882 static staticStr: string; 883 static staticFunc(): string; 884 str: string; 885 func(): string; 886} 887``` 888 889ArkTS侧示例代码 890 891```ts 892import hilog from '@ohos.hilog' 893import testNapi from 'libentry.so' 894 895let value = new testNapi.SendableClass(); 896hilog.info(0x0000, 'testTag', 'Node-API napi_define_sendable_class: %{public}s', value.str); 897``` 898 899#### napi_create_sendable_object_with_properties 900 901使用给定的napi_property_descriptor创建一个sendable对象。 902 903cpp部分代码 904 905```cpp 906#include "napi/native_api.h" 907 908static napi_value GetSendableObject(napi_env env, napi_callback_info info) { 909 napi_value val_true; 910 napi_get_boolean(env, true, &val_true); 911 napi_property_descriptor desc1[] = { 912 {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr}, 913 }; 914 napi_value obj; 915 napi_create_sendable_object_with_properties(env, 1, desc1, &obj); 916 return obj; 917} 918``` 919 920接口声明 921 922```ts 923// index.d.ts 924export const getSendableObject: () => { x: true }; 925``` 926 927ArkTS侧示例代码 928 929```ts 930import hilog from '@ohos.hilog' 931import testNapi from 'libentry.so' 932 933let value = testNapi.getSendableObject(); 934hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_object_with_properties: %{public}s', JSON.stringify(value)); 935``` 936 937#### napi_create_sendable_array 938 939创建一个sendable数组。 940 941cpp部分代码 942 943```cpp 944#include "napi/native_api.h" 945 946static napi_value GetSendableArray(napi_env env, napi_callback_info info) { 947 napi_value result = nullptr; 948 napi_create_sendable_array(env, &result); 949 return result; 950} 951``` 952 953接口声明 954 955```ts 956// index.d.ts 957export const getSendableArray: () => []; 958``` 959 960ArkTS侧示例代码 961 962```ts 963import hilog from '@ohos.hilog' 964import testNapi from 'libentry.so' 965 966let value = testNapi.getSendableArray(); 967hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_array: %{public}s', JSON.stringify(value)); 968``` 969 970#### napi_create_sendable_array_with_length 971 972创建一个指定长度的sendable数组。 973 974cpp部分代码 975 976```cpp 977static napi_value GetSendableArrayWithLength(napi_env env, napi_callback_info info) { 978 napi_value result = nullptr; 979 napi_create_sendable_array_with_length(env, 1, &result); 980 return result; 981} 982``` 983 984接口声明 985 986```ts 987// index.d.ts 988export const getSendableArrayWithLength: () => []; 989``` 990 991ArkTS侧示例代码 992 993```ts 994import hilog from '@ohos.hilog' 995import testNapi from 'libentry.so' 996 997let value = testNapi.getSendableArrayWithLength(); 998hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_array_with_length: %{public}s', JSON.stringify(value.length)); 999``` 1000 1001#### napi_create_sendable_arraybuffer 1002 1003创建一个sendable ArrayBuffer。 1004 1005cpp部分代码 1006 1007```cpp 1008#include "napi/native_api.h" 1009#include "hilog/log.h" 1010 1011static napi_value GetSendableArrayBuffer(napi_env env, napi_callback_info info) { 1012 static size_t LENGTH = 1024; 1013 void *data; 1014 napi_value result = nullptr; 1015 napi_create_sendable_arraybuffer(env, LENGTH, &data, &result); 1016 bool isArrayBuffer = false; 1017 napi_is_arraybuffer(env, result, &isArrayBuffer); 1018 OH_LOG_INFO(LOG_APP, "isArrayBuffer: %{public}d", isArrayBuffer); 1019 return result; 1020} 1021``` 1022 1023接口声明 1024 1025```ts 1026// index.d.ts 1027export const getSendableArrayBuffer: () => void; 1028``` 1029 1030ArkTS侧示例代码 1031 1032```ts 1033import hilog from '@ohos.hilog' 1034import testNapi from 'libentry.so' 1035 1036testNapi.getSendableArrayBuffer(); 1037``` 1038 1039#### napi_create_sendable_typedarray 1040 1041创建一个sendable TypedArray。 1042 1043cpp部分代码 1044 1045```cpp 1046#include "napi/native_api.h" 1047#include "hilog/log.h" 1048 1049static napi_value GetSendableTypedArray(napi_env env, napi_callback_info info) { 1050 static size_t LENGTH = 1024; 1051 static size_t OFFSET = 0; 1052 void *data; 1053 napi_value arraybuffer = nullptr; 1054 napi_create_sendable_arraybuffer(env, LENGTH, &data, &arraybuffer); 1055 1056 napi_value result = nullptr; 1057 napi_create_sendable_typedarray(env, napi_uint8_array, LENGTH, arraybuffer, OFFSET, &result); 1058 bool isTypedArray = false; 1059 napi_is_typedarray(env, result, &isTypedArray); 1060 OH_LOG_INFO(LOG_APP, "isTypedArray: %{public}d", isTypedArray); 1061 return result; 1062} 1063``` 1064 1065接口声明 1066 1067```ts 1068// index.d.ts 1069export const getSendableTypedArray: () => void; 1070``` 1071 1072ArkTS侧示例代码 1073 1074```ts 1075import hilog from '@ohos.hilog' 1076import testNapi from 'libentry.so' 1077 1078testNapi.getSendableTypedArray(); 1079``` 1080 1081#### napi_wrap_sendable 1082 1083包裹一个native实例到ArkTS对象中。 1084 1085cpp部分代码 1086 1087```cpp 1088#include "napi/native_api.h" 1089 1090static napi_value WrapSendable(napi_env env, napi_callback_info info) { 1091 napi_value val_true; 1092 napi_get_boolean(env, true, &val_true); 1093 napi_property_descriptor desc1[] = { 1094 {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr}, 1095 }; 1096 napi_value obj; 1097 napi_create_sendable_object_with_properties(env, 1, desc1, &obj); 1098 1099 const char* testStr = "test"; 1100 napi_wrap_sendable(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr); 1101 1102 return nullptr; 1103} 1104``` 1105 1106接口声明 1107 1108```ts 1109// index.d.ts 1110export const wrapSendable: () => void; 1111``` 1112 1113ArkTS侧示例代码 1114 1115```ts 1116import hilog from '@ohos.hilog' 1117import testNapi from 'libentry.so' 1118 1119testNapi.wrapSendable(); 1120``` 1121 1122#### napi_wrap_sendable_with_size 1123 1124包裹一个native实例到ArkTS对象中并指定大小。 1125 1126cpp部分代码 1127 1128```cpp 1129#include "napi/native_api.h" 1130 1131static napi_value WrapSendableWithSize(napi_env env, napi_callback_info info) { 1132 napi_value val_true; 1133 napi_get_boolean(env, true, &val_true); 1134 napi_property_descriptor desc1[] = { 1135 {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr}, 1136 }; 1137 napi_value obj; 1138 napi_create_sendable_object_with_properties(env, 1, desc1, &obj); 1139 1140 const char* testStr = "test"; 1141 napi_wrap_sendable_with_size(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr, 100); 1142 1143 return nullptr; 1144} 1145``` 1146 1147接口声明 1148 1149```ts 1150// index.d.ts 1151export const wrapSendableWithSize: () => void; 1152``` 1153 1154ArkTS侧示例代码 1155 1156```ts 1157import hilog from '@ohos.hilog' 1158import testNapi from 'libentry.so' 1159 1160testNapi.wrapSendableWithSize(); 1161``` 1162 1163#### napi_unwrap_sendable 1164 1165获取ArkTS对象包裹的native实例。 1166 1167cpp部分代码 1168 1169```cpp 1170#include "napi/native_api.h" 1171 1172static napi_value UnwrapSendable(napi_env env, napi_callback_info info) { 1173 napi_value val_true; 1174 napi_get_boolean(env, true, &val_true); 1175 napi_property_descriptor desc1[] = { 1176 {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr}, 1177 }; 1178 napi_value obj; 1179 napi_create_sendable_object_with_properties(env, 1, desc1, &obj); 1180 1181 const char* testStr = "test"; 1182 napi_wrap_sendable(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr); 1183 1184 char* tmpTestStr = nullptr; 1185 napi_unwrap_sendable(env, obj, (void**)&tmpTestStr); 1186 OH_LOG_INFO(LOG_APP, "native value is %{public}s", tmpTestStr); 1187 1188 return nullptr; 1189} 1190``` 1191 1192接口声明 1193 1194```ts 1195// index.d.ts 1196export const unwrapSendable: () => void; 1197``` 1198 1199ArkTS侧示例代码 1200 1201```ts 1202import hilog from '@ohos.hilog' 1203import testNapi from 'libentry.so' 1204 1205testNapi.unwrapSendable(); 1206``` 1207 1208#### napi_remove_wrap_sendable 1209 1210移除并获取ArkTS对象包裹的native实例。 1211 1212cpp部分代码 1213 1214```cpp 1215#include "napi/native_api.h" 1216 1217static napi_value RemoveWrapSendable(napi_env env, napi_callback_info info) { 1218 napi_value val_true; 1219 napi_get_boolean(env, true, &val_true); 1220 napi_property_descriptor desc1[] = { 1221 {"x", nullptr, nullptr, nullptr, nullptr, val_true, napi_default_jsproperty, nullptr}, 1222 }; 1223 napi_value obj; 1224 napi_create_sendable_object_with_properties(env, 1, desc1, &obj); 1225 1226 const char* testStr = "test"; 1227 napi_wrap_sendable(env, obj, (void*)testStr, [](napi_env env, void* data, void* hint) {}, nullptr); 1228 1229 char* tmpTestStr = nullptr; 1230 napi_remove_wrap_sendable(env, obj, (void**)&tmpTestStr); 1231 OH_LOG_INFO(LOG_APP, "native value is %{public}s", tmpTestStr); 1232 1233 return nullptr; 1234} 1235``` 1236 1237接口声明 1238 1239```ts 1240// index.d.ts 1241export const removeWrapSendable: () => void; 1242``` 1243 1244ArkTS侧示例代码 1245 1246```ts 1247import hilog from '@ohos.hilog' 1248import testNapi from 'libentry.so' 1249 1250testNapi.removeWrapSendable(); 1251``` 1252 1253以上代码如果要在native cpp中打印日志，需在CMakeLists.txt文件中添加以下配置信息（并添加头文件：#include "hilog/log.h"）： 1254 1255```text 1256// CMakeLists.txt 1257add_definitions( "-DLOG_DOMAIN=0xd0d0" ) 1258add_definitions( "-DLOG_TAG=\"testTag\"" ) 1259target_link_libraries(entry PUBLIC libhilog_ndk.z.so) 1260``` 1261
