1# Node-API支持的数据类型和接口 2<!--Kit: NDK--> 3<!--Subsystem: arkcompiler--> 4<!--Owner: @xliu-huanwei; @shilei123; @huanghello--> 5<!--Designer: @shilei123--> 6<!--Tester: @kirl75; @zsw_zhushiwei--> 7<!--Adviser: @fang-jinxu--> 8 9## Node-API的数据类型 10 11### napi_status 12 13是一个枚举数据类型，表示Node-API接口返回的状态信息。 14 15每当调用一个Node-API函数，都会返回该值，表示操作成功与否的相关信息。 16 17```c 18typedef enum { 19 napi_ok, 20 napi_invalid_arg, 21 napi_object_expected, 22 napi_string_expected, 23 napi_name_expected, 24 napi_function_expected, 25 napi_number_expected, 26 napi_boolean_expected, 27 napi_array_expected, 28 napi_generic_failure, 29 napi_pending_exception, 30 napi_cancelled, 31 napi_escape_called_twice, 32 napi_handle_scope_mismatch, 33 napi_callback_scope_mismatch, 34 napi_queue_full, 35 napi_closing, 36 napi_bigint_expected, 37 napi_date_expected, 38 napi_arraybuffer_expected, 39 napi_detachable_arraybuffer_expected, 40 napi_would_deadlock, /* unused */ 41 napi_no_external_buffers_allowed, 42 napi_cannot_run_js 43} napi_status; 44``` 45 46### napi_extended_error_info 47 48一个结构体，在调用Node-API接口不成功时存储了较为详细的错误信息。 49 50```c 51typedef struct { 52 const char *error_message; 53 void *engine_reserved; 54 uint32_t engine_error_code; 55 napi_status error_code; 56} napi_extended_error_info; 57``` 58 59### napi_value 60 61napi_value是一个C的结构体指针，表示一个ArkTS/JS对象的引用。napi_value持有了ArkTS/JS对象，同时，napi_value受[napi_handle_scope](#内存管理类型)管理，scope中napi_value持有的JS对象不会被释放；出scope后，napi_value将失效，不再持有对应的ArkTS/JS对象。 62 63### napi_env 64 65- 用于表示Node-API执行时的上下文，Native侧函数入参，并传递给函数中的Node-API接口。 66 67- napi_env与ArkTS/JS线程的上下文环境绑定，每一个napi_env都持有独立的运行时上下文环境，当ArkTS/JS线程退出之后，相应的napi_env将不再有效。 68 69- 禁止缓存napi_env，禁止在不同线程间传递napi_env。 70 71### napi_threadsafe_function 72 73[napi_threadsafe_function](use-napi-thread-safety.md)用来创建一个线程安全的ArkTS/JS函数，可以在不同的线程中调用。可以用于将异步操作的结果传递给ArkTS/JS环境，例如从另一个线程中读取数据或执行计算密集型操作。线程安全函数回调的执行仅在创建线程安全函数的ArkTS线程中执行。通过使用napi_threadsafe_function，可以实现ArkTS/JS和C++之间的高效通信，同时保持线程安全性。 74 75### napi_threadsafe_function_release_mode 76 77该枚举类型定义了两个常量，用于指定以哪一种方式来释放线程安全函数。 78 79```c 80typedef enum { 81 napi_tsfn_release, 82 napi_tsfn_abort 83} napi_threadsafe_function_release_mode; 84``` 85 86该值会传给napi_release_threadsafe_function。 87 88```cpp 89napi_release_threadsafe_function(napi_threadsafe_function func, 90 napi_threadsafe_function_release_mode mode); 91``` 92 93- mode值为napi_tsfn_release时：表示将tsfn中持有的线程数减一，当线程数减到0是，线程安全函数tsfn将被销毁。 94 95- mode值为napi_tsfn_abort时：该tsfn关闭，不能再调用此tsfn。 96 如果设置为napi_tsfn_abort，利用napi_call_threadsafe_function接口调用此tsfn时，该行为可能导致UAF问题————当napi_tsfn_abort被设置时，tsfn立刻关闭，不能再被调用。如果此时调用napi_call_threadsafe_function，系统可能会返回napi_closing状态，表示tsfn正在关闭，但是传递给tsfn的data并未被放入队列中，这意味着data可能未被正确处理。如果data指向的内存已经被释放（例如，tsfn的资源被释放），但调用者仍然尝试访问或使用data，就会出现UAF(Use-After-Free)问题。 97 98### napi_threadsafe_function_call_mode 99 100该枚举类型定义了两个常量，用于指定线程安全函数的调用模式。 101 102数据结构如下所示： 103 104```c 105typedef enum { 106 napi_tsfn_nonblocking, 107 napi_tsfn_blocking 108} napi_threadsafe_function_call_mode; 109``` 110 111- napi_tsfn_nonblocking：napi_call_threadsafe_function是非阻塞的，如果队列已满，则返回napi_queue_full，从而阻止数据添加到队列中。 112 113- napi_tsfn_blocking：napi_call_threadsafe_function是阻塞的，直至队列中有空间可用。 114 115### 内存管理类型 116 117Node-API包含以下内存管理类型： 118 119**napi_handle_scope** 120 121napi_handle_scope数据类型是用来管理ArkTS/JS对象的生命周期的。它允许ArkTS/JS对象在一定范围内保持活动状态，以便在ArkTS/JS代码中使用。在创建napi_handle_scope时，所有在该范围内创建的ArkTS/JS对象都会保持活动状态，直到scope被关闭。这样可以做到ArkTS/JS对象生命周期最小化，[避免发生内存泄漏问题](napi-guidelines.md#生命周期管理)。同时，napi_handle_scope也可参考<!--RP1-->生命周期类问题注意事项。<!--RP1End--> 122 123**napi_escapable_handle_scope** 124 125- 由napi_open_escapable_handle_scope接口创建，由napi_close_escapable_handle_scope接口关闭。 126 127- 表示一种特殊类型的句柄范围，用于将在escapable_handle_scope范围内创建的值返回给父scope。 128 129- 用于napi_escape_handle接口，将ArkTS/JS对象逃逸到父scope，以便在外部作用域使用。 130 131**napi_ref ** 132 133指向napi_value，允许用户管理ArkTS/JS值的生命周期。 134 135**napi_type_tag** 136 137该结构体定义了一个包含两个无符号64位整数的类型标签，用于标识一个Node-API值的类型信息。 138 139```c 140typedef struct { 141 uint64_t lower; 142 uint64_t upper; 143} napi_type_tag; 144``` 145 146- 存储了两个无符号64位整数的128位值，用它来标记ArkTS/JS对象，确保它们属于某种类型。 147 148- 比napi_instanceof更强的类型检查，如果对象的原型被操纵，napi_instanceof可能会存在误报。 149 150- type_tag与napi_wrap结合非常有用，因为它确保从包装对象检索的指针可以安全地转换为与先前应用于JavaScript对象的类型标记相对应的Native类型。 151 152**napi_async_cleanup_hook_handle** 153 154napi_async_cleanup_hook_handle是Node-API中用于管理异步资源生命周期的一种机制。它允许注册一个清理钩子（cleanup hook），该钩子仅在当前napi_env环境生命周期结束时被调用。通过使用 napi_async_cleanup_hook_handle，可以确保某些异步资源在环境销毁前得到妥善释放，从而避免资源泄漏。此外，在Node-API实现中，只要该结构未被释放，会延迟整个 napi_env 环境的销毁。在OpenHarmony中，该接口的行为基本等同于env生命周期相关的清理钩子，除了支持重复注册相同的上下文数据（data）外，其余行为与标准的env清理钩子一致。 155 156### 回调类型 157 158Node-API包含以下回调类型： 159 160**napi_callback_info** 161 162Native侧获取JS侧参数信息，传递给napi_get_cb_info，用于获取JS侧入参信息。 163 164**napi_callback** 165 166表示用户定义的Native函数，暴露给ArkTS/JS，即ArkTS/JS侧调用的接口；一般不需要在callback中创建handle或者callback scope。 167 168基本用法如下： 169 170```c 171typedef napi_value (*napi_callback)(napi_env, napi_callback_info); 172``` 173 174**napi_finalize** 175 176函数指针，用于传入napi_create_threadsafe_function、napi_set_instance_data、napi_wrap、napi_add_finalizer等接口。napi_finalize在对象被回收时会被调用。 177 178**napi_async_execute_callback** 179 180函数指针，用于napi_create_async_work接口。 181 182- 异步执行的Native函数，从工作池线程调用，可与事件循环线程并行执行。 183 184- 函数实现中必须避免调用非线程安全的Node-API。 185 186- Node-API调用可以在napi_async_complete_callback中执行。 187 188**napi_async_complete_callback** 189 190napi_async_complete_callback用于异步操作完成后的回调。当需要进行异步操作时，可以使用napi_create_async_work函数创建一个异步操作任务，并指定一个napi_async_complete_callback回调函数，在异步操作完成后会自动调用该回调函数，以便进行后续的处理。该回调函数的参数包括当前异步操作任务的状态和返回值等信息，可以根据这些信息进行相应的处理。 191 192**napi_threadsafe_function_call_js** 193 194函数指针，在事件循环线程中执行，可与ArkTS/JS交互，从而实现更加复杂的功能，用于napi_create_threadsafe_function(napi_env env,…,napi_threadsafe_function_call_js call_js_cb,...)接口。 195 196**napi_cleanup_hook** 197 198函数指针，用于napi_add_env_cleanup_hook接口，当环境销毁时会被执行。 199 200**napi_async_cleanup_hook** 201 202函数指针，用于napi_add_async_cleanup_hook接口，当环境销毁时会被执行。 203 204### 调度优先级 205 206QoS决定了线程调度的优先级，等级定义如下： 207 208```c 209typedef enum { 210 napi_qos_background = 0, 211 napi_qos_utility = 1, 212 napi_qos_default = 2, 213 napi_qos_user_initiated = 3, 214} napi_qos_t; 215``` 216 217| QoS等级 | 适用场景 | 218| -------- | -------- | 219| napi_qos_background | 低等级，用户不可见任务，例如数据同步、备份。 | 220| napi_qos_utility | 中低等级，不需要立即看到响应效果的任务，例如下载或导入数据。 | 221| napi_qos_default | 默认。 | 222| napi_qos_user_initiated | 高等级，用户触发并且可见进展，例如打开文档。 | 223 224### 事件循环模式 225 226napi提供了运行底层事件循环的两种模式, 其定义如下： 227 228```c 229typedef enum { 230 napi_event_mode_default = 0, 231 napi_event_mode_nowait = 1, 232} napi_event_mode; 233``` 234 235| 事件循环运行模式 | 解释说明 | 236| -------- | -------- | 237| napi_event_mode_default | 阻塞式的运行底层事件循环，直到循环中没有或活跃的uv_handle句柄时退出事件循环。 | 238| napi_event_mode_nowait | 非阻塞式的运行底层事件循环，尝试去处理一个任务，处理完之后退出事件循环；如果事件循环中没有任务，立刻退出事件循环。 | 239 240### 线程安全任务优先级 241 242napi提供了线程安全任务的优先级, 底层任务队列中的任务会根据其优先级被依次执行, 优先级的定义如下： 243 244```c 245typedef enum { 246 napi_priority_immediate = 0, 247 napi_priority_high = 1, 248 napi_priority_low = 2, 249 napi_priority_idle = 3, 250} napi_task_priority; 251``` 252 253| 任务优先级 | 解释说明 | 254| -------- | -------- | 255| napi_priority_immediate | 该优先级的级别最高。| 256| napi_priority_high | 该优先级的级别低于napi_priority_immediate。| 257| napi_priority_low | 该优先级的级别低于napi_priority_immediate和napi_priority_high。| 258| napi_priority_idle | 该优先级的级别最低。 | 259 260## 支持的Node-API接口 261 262Node-API接口在Node.js提供的原生模块基础上扩展，目前支持部分接口，具体可见下文。 263 264### 异步安全线程相关 265 266| 接口 | 功能说明 | 267| -------- | -------- | 268| napi_create_threadsafe_function | 创建线程安全函数。 | 269| napi_get_threadsafe_function_context | 获取线程安全函数中的context。 | 270| napi_call_threadsafe_function | 调用线程安全函数。 | 271| napi_acquire_threadsafe_function | 指示线程安全函数可以开始使用。 | 272| napi_release_threadsafe_function | 指示线程安全函数将停止使用。 | 273| napi_ref_threadsafe_function | 指示在主线程上运行的事件循环在线程安全函数被销毁之前不应退出。 | 274| napi_unref_threadsafe_function | 指示在主线程上运行的事件循环可能会在线程安全函数被销毁之前退出。 | 275 276### buffer相关 277 278| 接口 | 功能说明 | 279| -------- | -------- | 280| napi_create_buffer | 创建并获取一个指定大小的ArkTS Buffer。 | 281| napi_create_buffer_copy | 创建并获取一个指定大小的ArkTS Buffer，并以给定数据进行初始化。 | 282| napi_create_external_buffer | 创建并获取一个指定大小的ArkTS Buffer，使用给定的数据作为buffer对象的底层缓冲区，该接口可为Buffer附带额外数据。 | 283| napi_get_buffer_info | 获取JS Buffer底层data及其长度。 | 284| napi_is_buffer | 判断给定JS value是否为Buffer对象。 | 285| napi_create_external_arraybuffer | 分配一个附加有外部数据的JS ArrayBuffer。 | 286 287### string相关 288 289| 接口 | 功能说明 | 290| -------- | -------- | 291| napi_create_string_utf16 | 通过UTF16编码的C字符串数据创建ArkTS String。 | 292| napi_get_value_string_utf16 | 获取给定ArkTS value对应的UTF16编码的字符串。 | 293| napi_create_string_latin1 | 通过ISO-8859-1编码的C字符串数据创建ArkTS String。 | 294| napi_create_string_utf8 | 通过UTF8编码的C字符串数据创建ArkTS String。 | 295| napi_get_value_string_latin1 | 获取给定ArkTS value对应的ISO-8859-1编码的字符串。 | 296| napi_get_value_string_utf8 | 获取给定ArkTS value对应的UTF8编码的字符串。 | 297 298### date相关 299 300| 接口 | 功能说明 | 301| -------- | -------- | 302| napi_create_date | 通过一个C的double数据创建ArkTS Date。 | 303| napi_get_date_value | 获取给定ArkTS Date对应的C double值。 | 304| napi_is_date | 判断给定ArkTS value是否为ArkTS Date对象。 | 305 306### arraybuffer相关 307 308| 接口 | 功能说明 | 309| -------- | -------- | 310| napi_get_arraybuffer_info | 获取ArrayBuffer的底层缓冲区及其长度。 | 311| napi_is_arraybuffer | 判断给定ArkTS value是否为ArrayBuffer。 | 312| napi_detach_arraybuffer | 分离给定ArrayBuffer的底层数据。 | 313| napi_is_detached_arraybuffer | 判断给定的ArrayBuffer是否已被分离。 | 314| napi_create_arraybuffer | 创建并获取一个指定大小的JS ArrayBuffer。 | 315 316### module相关 317 318| 接口 | 功能说明 | 319| -------- | -------- | 320| napi_module_register | native模块注册接口。 | 321 322### 生命周期相关 323 324| 接口 | 功能说明 | 325| -------- | -------- | 326| napi_open_handle_scope | 创建一个napi_handle_scope。需要使用napi_close_handle_scope进行关闭。 | 327| napi_close_handle_scope | 关闭传入的napi_handle_scope，关闭后，全部在其中产生的napi_value都将被关闭。 | 328| napi_open_escapable_handle_scope | 创建出一个可逃逸的handle scope，可将范围内声明的值返回到父作用域。需要使用napi_close_escapable_handle_scope进行关闭。 | 329| napi_close_escapable_handle_scope | 关闭传入的可逃逸的handle scope。 | 330| napi_escape_handle | 提升传入的JS Object的生命周期到其父作用域。 | 331| napi_create_reference | 为Object创建一个napi_ref。调用者需要自己管理napi_ref生命周期。 | 332| napi_delete_reference | 删除传入的napi_ref。 | 333| napi_reference_ref | 增加传入的napi_ref的引用计数，并获取新的计数。 | 334| napi_reference_unref | 减少传入的napi_ref的引用计数，并获取新的计数。 | 335| napi_get_reference_value | 获取与napi_ref相关联的JS Object。 | 336| napi_add_finalizer | 当ArkTS Object中的对象被垃圾回收时调用注册的napi_finalize回调。 | 337 338### promise相关 339 340| 接口 | 功能说明 | 341| -------- | -------- | 342| napi_create_promise | 创建一个Promise对象。 | 343| napi_resolve_deferred | 对Promise关联的deferred对象进行兑现。 | 344| napi_reject_deferred | 对Promise关联的deferred对象进行拒绝。 | 345| napi_is_promise | 判断给定napi_value是否为Promise对象。 | 346 347### array相关 348 349| 接口 | 功能说明 | 350| -------- | -------- | 351| napi_create_array | 创建一个ArkTS Array。 | 352| napi_create_array_with_length | 创建并获取一个指定长度的ArkTS Array。 | 353| napi_get_array_length | 获取array的length。 | 354| napi_is_array | 判断给定ArkTS value是否为array。 | 355| napi_set_element | 在给定Object的指定索引处，设置属性值。 | 356| napi_get_element | 获取给定Object指定索引处的元素。 | 357| napi_has_element | 若给定Object的指定索引处拥有属性。 | 358| napi_delete_element | 尝试删除给定Object的指定索引处的元素。 | 359| napi_create_typedarray | 通过现有的ArrayBuffer创建一个ArkTS TypeArray。 | 360| napi_is_typedarray | 判断给定ArkTS value是否为TypeArray。| 361| napi_get_typedarray_info | 获取给定TypedArray的各种属性（例如：类型，长度，字节偏移量，ArrayBuffer等）。 | 362| napi_create_dataview | 通过现有的ArrayBuffer创建一个ArkTS DataView。 | 363| napi_is_dataview | 判断给定ArkTS value是否为DataView。| 364| napi_get_dataview_info | 获取给定DataView的各种属性。| 365 366### primitive相关 367 368| 接口 | 功能说明 | 369| -------- | -------- | 370| napi_get_boolean | 根据给定的C boolean值，获取JS Boolean对象。 | 371| napi_get_global | 获取global对象。 | 372| napi_get_null | 获取null对象。 | 373| napi_get_undefined | 获取undefined对象。 | 374| napi_coerce_to_bool | 将给定的JS value强转成JS Boolean。 | 375| napi_coerce_to_number | 将给定的JS value强转成JS Number。 | 376| napi_coerce_to_object | 将给定的JS value强转成JS Object。 | 377| napi_coerce_to_string | 将给定的JS value强转成JS String。 | 378 379### class相关 380 381| 接口 | 功能说明 | 382| -------- | -------- | 383| napi_new_instance | 通过给定的构造函数，构建一个实例。 | 384| napi_get_new_target | 获取构造函数调用的new.target。 | 385| napi_define_class | 定义与C++类相对应的JavaScript类。 | 386| napi_wrap | 在ArkTS对象上绑定一个Node-API模块对象实例。这个函数通常在将Node-API模块对象与ArkTS对象进行绑定时使用，以便在ArkTS中使用Native方法和属性。 | 387| napi_unwrap | 从ArkTS对象上获取之前绑定的Node-API模块对象实例。 | 388| napi_remove_wrap | 从ArkTS对象上获取之前绑定的Node-API模块对象实例，并解除绑定。 | 389 390### object相关 391 392| 接口 | 功能说明 | 393| -------- | -------- | 394| napi_get_prototype | 获取给定ArkTS Object的prototype。 | 395| napi_create_object | 创建一个默认的ArkTS Object。 | 396| napi_object_freeze | 冻结给定的对象。 | 397| napi_object_seal | 密封给定的对象。 | 398| napi_typeof | 获取给定ArkTS value的ArkTS Type。 | 399| napi_instanceof | 判断给定object是否为给定constructor的实例。 | 400| napi_type_tag_object | 将tag指针的值与Object关联。 | 401| napi_check_object_type_tag | 判断给定的tag指针是否被关联到了ArkTS Object上。 | 402| napi_create_symbol | 创建一个ArkTS Symbol对象。 | 403| napi_create_external | 用于创建一个ArkTS外部对象，该对象可以用于将C/C++中的自定义数据结构或对象传递到JS中，并且可以在ArkTS中访问其属性和方法。 | 404| napi_get_value_external | 用于获得napi_create_external创建的绑定了外部数据的ArkTS值，此函数可以在ArkTS和C/C++之间传递数据。 | 405 406### 基本数据类型相关 407 408| 接口 | 功能说明 | 409| -------- | -------- | 410| napi_create_int32 | 通过一个C的int32数据创建JS number。 | 411| napi_create_uint32 | 通过一个C的uint32数据创建JS number。 | 412| napi_create_int64 | 通过一个C的int64数据创建JS number。 | 413| napi_create_double | 通过一个C的double数据创建JS number。 | 414| napi_get_value_int32 | 获取给定JS number对应的C int32值。 | 415| napi_get_value_uint32 | 获取给定JS number对应的C uint32值。 | 416| napi_get_value_int64 | 获取给定JS number对应的C int64值。 | 417| napi_get_value_double | 获取给定JS number对应的C double值。 | 418|napi_get_value_bool|获取给定js Boolean对应的C bool值。| 419 420### bigint相关 421 422| 接口 | 功能说明 | 423| -------- | -------- | 424| napi_create_bigint_int64 | 通过一个C的int64数据创建JS BigInt。 | 425| napi_create_bigint_uint64 | 通过一个C的uint64数据创建JS BigInt。 | 426| napi_create_bigint_words | 通过一个C的uint64数组创建单个JS BigInt。 | 427| napi_get_value_bigint_int64 | 获取给定JS BigInt对应的C int64值。 | 428| napi_get_value_bigint_uint64 | 获取给定JS BigInt对应的C uint64值。 | 429| napi_get_value_bigint_words | 获取给定JS BigInt对应的信息，包括符号位、64位小端序数组和数组中的元素个数。 | 430 431### 异常和错误相关 432 433| 接口 | 功能说明 | 434| -------- | -------- | 435| napi_throw | 抛出一个JS value。 | 436| napi_throw_error | 用于抛出一个带文本信息的ArkTS Error。| 437| napi_throw_type_error | 抛出一个带文本信息的ArkTS TypeError。 | 438| napi_throw_range_error | 抛出一个带文本信息的ArkTS RangeError。 | 439| napi_is_error | 判断napi_value是否表示为一个error对象。 | 440| napi_create_error | 创建并获取一个带文本信息的ArkTS Error。 | 441| napi_create_type_error | 创建并获取一个带文本信息的ArkTS Error对象 | 442| napi_create_range_error | 创建并获取一个带文本信息的ArkTS Error对象。 | 443| napi_get_and_clear_last_exception | 获取并清除最近一次出现的异常。 | 444| napi_is_exception_pending | 判断是否出现了异常。 | 445| napi_fatal_error | 引发致命错误以立即终止进程。 | 446| napi_get_last_error_info | 获取napi_extended_error_info结构体，其中包含最近一次出现的error信息。 | 447| napi_fatal_exception | 抛出一个致命异常并终止进程, 同时产生相应的crash日志。 | 448 449### 属性相关 450 451| 接口 | 功能说明 | 452| -------- | -------- | 453| napi_get_property_names | 以字符串数组的形式获取对象的可枚举属性的名称。 | 454| napi_set_property | 对给定Object设置属性。 | 455| napi_get_property | 获取给定Object的给定属性。 | 456| napi_has_property | 判断给定对象中是否存在给定属性。 | 457| napi_delete_property | 尝试从给定Object中删除给定key属性。 | 458| napi_has_own_property | 判断给定Object中是否有名为key的own property。 | 459| napi_set_named_property | 对给定Object设置一个给定名称的属性。 | 460| napi_get_named_property | 获取给定Object中指定名称的属性。 | 461| napi_has_named_property | 判断给定Object中是否有给定名称的属性。 | 462| napi_define_properties | 批量的向给定Object中定义属性。 | 463| napi_get_all_property_names | 获取一个数组，其中包含此对象过滤后的属性名称。 | 464 465### 异步任务相关 466 467| 接口 | 功能说明 | 468| -------- | -------- | 469| napi_create_async_work | 创建一个异步工作对象。 | 470| napi_delete_async_work | 释放先前创建的异步工作对象。 | 471| napi_queue_async_work | 将异步工作对象加到队列，由底层去调度执行。 | 472| napi_cancel_async_work | 取消入队的异步任务。 | 473 474### 自定义异步操作 475 476| 接口 | 功能说明 | 477| -------- | -------- | 478| napi_async_init | 创建一个异步资源上下文环境（不支持与async_hook相关能力）。 | 479| napi_make_callback | 在异步资源上下文环境中回调JS函数（不支持与async_hook相关能力）。| 480| napi_async_destroy | 销毁先前创建的异步资源上下文环境（不支持与async_hook相关能力）。| 481| napi_open_callback_scope | 创建一个回调作用域（不支持与async_hook相关能力）。 | 482| napi_close_callback_scope | 关闭先前创建的回调作用域（不支持与async_hook相关能力）。| 483 484### uv相关 485 486| 接口 | 功能说明 | 487| -------- | -------- | 488| napi_get_uv_event_loop | 获取当前libuv loop实例。 | 489 490### 函数调用 491 492| 接口 | 功能说明 | 493| -------- | -------- | 494| napi_call_function | 在C/C++侧调用JS方法。 | 495| napi_get_cb_info | 从给定的callback info中获取有关调用的详细信息，如参数和this指针。 | 496 497### 环境生命周期 498 499| 接口 | 功能说明 | 500| -------- | -------- | 501| napi_set_instance_data | 绑定与当前运行的环境相关联的数据项。 | 502| napi_get_instance_data | 检索与当前运行的环境相关联的数据项。| 503 504### 对象生命周期管理 505 506| 接口 | 功能说明 | 507| -------- | -------- | 508| napi_add_env_cleanup_hook | 注册环境清理钩子函数。 | 509| napi_remove_env_cleanup_hook | 取消环境清理钩子函数。| 510| napi_add_async_cleanup_hook | 注册清理异步钩子函数。 | 511| napi_remove_async_cleanup_hook | 取消清理异步钩子函数。| 512 513### 扩展能力 514 515[Node-API组件扩展的符号列表](../reference/native-lib/napi.md#node-api组件扩展的符号列表) 516 517| 接口 | 功能说明 | 518| -------- | -------- | 519| napi_queue_async_work_with_qos | 将异步工作对象加到队列，由底层根据传入的qos优先级去调度执行。 | 520| napi_run_script_path | 运行指定的abc文件。 | 521| napi_load_module | 将abc文件作为模块加载，返回模块的命名空间。 | 522| napi_load_module_with_info | 将abc文件作为模块加载，返回模块的命名空间，可在ArkTS基础运行时环境中使用。 | 523| napi_create_object_with_properties | 使用给定的napi_property_descriptor创建js Object。descriptor的键名必须为string，且不可转为number。 | 524| napi_create_object_with_named_properties | 使用给定的napi_value和键名创建js Object。键名必须为string，且不可转为number。 | 525| napi_coerce_to_native_binding_object | 强制将js Object和Native对象绑定。 | 526| napi_create_ark_runtime|创建基础运行时环境。| 527| napi_destroy_ark_runtime|销毁基础运行时环境。| 528| napi_run_event_loop | 启动底层的事件循环。| 529| napi_stop_event_loop | 停止底层的事件循环。| 530| napi_serialize | 将ArkTS对象序列化为native数据。| 531| napi_deserialize | 将native数据反序列化为ArkTS对象。| 532| napi_delete_serialization_data | 删除序列化数据。| 533| napi_call_threadsafe_function_with_priority| 按照指定的优先级和入队策略，将任务投递到ArkTS主线程中。| 534| napi_is_sendable| 判断给定的JS value是否是Sendable的。| 535| napi_define_sendable_class| 创建一个Sendable类。| 536| napi_create_sendable_object_with_properties | 使用给定的napi_property_descriptor创建一个Sendable对象。| 537| napi_create_sendable_array | 创建一个Sendable数组。| 538| napi_create_sendable_array_with_length | 创建一个指定长度的Sendable数组。| 539| napi_create_sendable_arraybuffer | 创建一个Sendable ArrayBuffer。| 540| napi_create_sendable_typedarray | 创建一个Sendable TypedArray。| 541| napi_wrap_sendable | 包裹一个native实例到ArkTS对象中。| 542| napi_wrap_sendable_with_size | 包裹一个native实例到ArkTS对象中并指定大小。| 543| napi_unwrap_sendable | 获取ArkTS对象包裹的native实例。| 544| napi_remove_wrap_sendable | 移除并获取ArkTS对象包裹的native实例，移除后回调将不再触发，需手动delete释放内存。| 545| napi_wrap_enhance | 在ArkTS对象上绑定一个Node-API模块对象实例并指定实例大小，开发者可以指定绑定的回调函数是否异步执行，如果异步执行，则回调函数必须是线程安全的。 | 546|napi_create_ark_context| 创建一个新的上下文环境。| 547|napi_switch_ark_context| 切换到指定的运行时上下文环境。| 548|napi_destroy_ark_context| 销毁通过napi_create_ark_context创建的上下文环境。| 549 550**napi_queue_async_work_with_qos** 551 552```c 553napi_status napi_queue_async_work_with_qos(napi_env env, 554 napi_async_work work, 555 napi_qos_t qos); 556``` 557 558用法同napi_queue_async_work，但可以指定QoS等级。napi_queue_async_work_with_qos使用方法可参考指定异步任务调度优先级。QoS详细介绍可参考[QoS 开发指导](qos-guidelines.md)。 559 560**napi_run_script_path** 561 562```c 563napi_status napi_run_script_path(napi_env env, 564 const char* abcPath, 565 napi_value* result); 566``` 567**注：**使用限制说明文档：[使用napi_run_script_path接口执行包内abc文件的使用限制](https://developer.huawei.com/consumer/cn/doc/harmonyos-faqs/faqs-ndk-65) 568**napi_load_module** 569 570```c 571napi_status napi_load_module(napi_env env, 572 const char* path, 573 napi_value* result); 574``` 575 576**napi_create_object_with_properties** 577 578```c 579napi_status napi_create_object_with_properties(napi_env env, 580 napi_value* result, 581 size_t property_count, 582 const napi_property_descriptor* properties); 583``` 584 585**napi_create_object_with_named_properties** 586 587```c 588napi_status napi_create_object_with_named_properties(napi_env env, 589 napi_value* result, 590 size_t property_count, 591 const char** keys, 592 const napi_value* values); 593``` 594 595**napi_coerce_to_native_binding_object** 596 597```c 598napi_status napi_coerce_to_native_binding_object(napi_env env, 599 napi_value js_object, 600 napi_native_binding_detach_callback detach_cb, 601 napi_native_binding_attach_callback attach_cb, 602 void* native_object, 603 void* hint); 604``` 605 606**napi_create_ark_runtime** 607 608```c 609napi_status napi_create_ark_runtime(napi_env *env); 610``` 611[使用napi_create_ark_runtime、napi_destroy_ark_runtime接口创建ArkTS运行时环境](use-napi-ark-runtime.md)。 612 613**napi_destroy_ark_runtime** 614 615```c 616napi_status napi_destroy_ark_runtime(napi_env *env); 617``` 618 619**napi_run_event_loop** 620 621```c 622napi_status napi_run_event_loop(napi_env env, napi_event_mode mode); 623``` 624 625开发者只能在自己通过napi_create_ark_runtime创建的ArkTS运行环境中调用napi_run_event_loop与napi_stop_event_loop接口，使用方法可参考[使用扩展的Node-API接口在异步线程中运行和停止事件循环](use-napi-event-loop.md)。 626 627**napi_stop_event_loop** 628 629```c 630napi_status napi_stop_event_loop(napi_env env); 631``` 632 633**napi_serialize** 634 635```c 636napi_status napi_serialize(napi_env env, 637 napi_value object, 638 napi_value transfer_list, 639 napi_value clone_list, 640 void** result); 641``` 642 643**napi_deserialize** 644 645```c 646napi_status napi_deserialize(napi_env env, void* buffer, napi_value* object); 647``` 648 649**napi_delete_serialization_data** 650 651```c 652napi_status napi_delete_serialization_data(napi_env env, void* buffer); 653``` 654 655**napi_call_threadsafe_function_with_priority** 656 657```c 658napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func, 659 void *data, 660 napi_task_priority priority, 661 bool isTail); 662``` 663 664**napi_is_sendable** 665 666```c 667napi_status napi_is_sendable(napi_env env, napi_value value, bool* result); 668``` 669 670**napi_define_sendable_class** 671 672```c 673napi_status napi_define_sendable_class(napi_env env, 674 const char* utf8name, 675 size_t length, 676 napi_callback constructor, 677 void* data, 678 size_t property_count, 679 const napi_property_descriptor* properties, 680 napi_value parent, 681 napi_value* result); 682 683``` 684 685**napi_create_sendable_object_with_properties** 686 687```c 688napi_status napi_create_sendable_object_with_properties(napi_env env, 689 size_t property_count, 690 const napi_property_descriptor* properties, 691 napi_value* result); 692``` 693 694**napi_create_sendable_array** 695 696```c 697napi_status napi_create_sendable_array(napi_env env, napi_value* result); 698``` 699 700**napi_create_sendable_array_with_length** 701 702```c 703napi_status napi_create_sendable_array_with_length(napi_env env, size_t length, napi_value* result); 704``` 705 706**napi_create_sendable_arraybuffer** 707 708```c 709napi_status napi_create_sendable_arraybuffer(napi_env env, size_t byte_length, void** data, napi_value* result); 710``` 711 712**napi_create_sendable_typedarray** 713 714```c 715napi_status napi_create_sendable_typedarray(napi_env env, 716 napi_typedarray_type type, 717 size_t length, 718 napi_value arraybuffer, 719 size_t byte_offset, 720 napi_value* result); 721``` 722 723**napi_wrap_sendable** 724 725```c 726napi_status napi_wrap_sendable(napi_env env, 727 napi_value js_object, 728 void* native_object, 729 napi_finalize finalize_cb, 730 void* finalize_hint); 731``` 732 733**napi_wrap_sendable_with_size** 734 735```c 736napi_status napi_wrap_sendable_with_size(napi_env env, 737 napi_value js_object, 738 void* native_object, 739 napi_finalize finalize_cb, 740 void* finalize_hint, 741 size_t native_binding_size); 742``` 743 744**napi_unwrap_sendable** 745 746```c 747napi_status napi_unwrap_sendable(napi_env env, napi_value js_object, void** result); 748``` 749 750**napi_remove_wrap_sendable** 751 752```c 753napi_status napi_remove_wrap_sendable(napi_env env, napi_value js_object, void** result); 754``` 755 756**napi_wrap_enhance** 757 758```c 759napi_status napi_wrap_enhance(napi_env env, 760 napi_value js_object, 761 void* native_object, 762 napi_finalize finalize_cb, 763 bool async_finalizer, 764 void* finalize_hint, 765 size_t native_binding_size, 766 napi_ref* result); 767``` 768 769**napi_create_ark_context** 770```c 771napi_status napi_create_ark_context(napi_env env, 772 napi_env* newEnv); 773``` 774 775**napi_switch_ark_context** 776```c 777napi_status napi_switch_ark_context(napi_env env); 778``` 779 780**napi_destroy_ark_context** 781```c 782napi_status napi_destroy_ark_context(napi_env env); 783``` 784 785### 其他实用工具 786 787| 接口 | 功能说明 | 788| -------- | -------- | 789| napi_get_version | 获取Node运行时支持的最高 NAPI 版本。 | 790| node_api_get_module_file_name | 用于获取加载项加载位置的绝对路径。| 791| napi_strict_equals | 当需要确保两个值不仅值相等且类型也相同时（例如处理特定类型的数据结构或算法时），可以使用napi_strict_equals来保证数据一致性。 | 792