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## 简介 10 11Node-API是用于封装JavaScript能力为Native插件的API，独立于底层JavaScript，并作为Node.js的一部分。 12 13## 支持的能力 14 15Node-API可以去除底层的JavaScript引擎的差异，提供一套稳定的接口。 16 17OpenHarmony的Node-API组件对Node-API的接口进行了重新实现，底层对接了ArkJS等引擎。当前支持Node-API标准库中的部分接口。 18 19## 引入Node-API能力 20 21如果开发者需要使用Node-API相关功能，首先请添加头文件： 22 23```cpp 24#include <napi/native_api.h> 25``` 26 27其次在CMakeLists.txt中添加以下动态链接库： 28 29``` 30libace_napi.z.so 31``` 32 33## 已从Node-API组件标准库中导出的符号列表 34 35从Node-API标准库导出的接口，其使用方法及行为基于[Node.js](https://nodejs.org/docs/latest-v12.x/api/n-api.html)，并进行了部分[能力拓展](#node-api组件扩展的符号列表)。 36 37|符号类型|符号名|说明|起始支持API版本| 38| --- | --- | --- | --- | 39|FUNC|napi_module_register|napi native模块注册接口。|10| 40|FUNC|napi_get_last_error_info|获取`napi_extended_error_info`结构体，其中包含最近一次出现的error信息。|10| 41|FUNC|napi_throw|抛出一个js value。|10| 42|FUNC|napi_throw_error|抛出一个带文本信息的js `Error`。|10| 43|FUNC|napi_throw_type_error|抛出一个带文本信息的js `TypeError`。|10| 44|FUNC|napi_throw_range_error|抛出一个带文本信息的js `RangeError`。|10| 45|FUNC|napi_is_error|判断`napi_value`是否表示为一个error对象。|10| 46|FUNC|napi_create_error|创建并获取一个带文本信息的js `Error`。|10| 47|FUNC|napi_create_type_error|创建并获取一个带文本信息的js `TypeError`。|10| 48|FUNC|napi_create_range_error|创建并获取一个带文本信息的js `RangeError`。|10| 49|FUNC|napi_get_and_clear_last_exception|获取并清除最近一次出现的异常。|10| 50|FUNC|napi_is_exception_pending|判断是否出现了异常。|10| 51|FUNC|napi_fatal_error|引发致命错误以立即终止进程。|10| 52|FUNC|napi_open_handle_scope|创建一个上下文环境使用。|10| 53|FUNC|napi_close_handle_scope|关闭传入的上下文环境，关闭后，全部在其中声明的引用都将被关闭。|10| 54|FUNC|napi_open_escapable_handle_scope|创建出一个可逃逸的handle scope，可将范围内声明的值返回到父作用域。|10| 55|FUNC|napi_close_escapable_handle_scope|关闭传入的可逃逸的handle scope。|10| 56|FUNC|napi_escape_handle|提升传入的js object的生命周期到其父作用域。|10| 57|FUNC|napi_create_reference|为`Object`创建一个reference，以延长其生命周期。调用者需要自己管理reference生命周期。|10| 58|FUNC|napi_delete_reference|删除传入的reference。|10| 59|FUNC|napi_reference_ref|增加传入的reference的引用计数，并获取该计数。|10| 60|FUNC|napi_reference_unref|减少传入的reference的引用计数，并获取该计数。|10| 61|FUNC|napi_get_reference_value|获取与reference相关联的js `Object`。|10| 62|FUNC|napi_create_array|创建并获取一个js `Array`。|10| 63|FUNC|napi_create_array_with_length|创建并获取一个指定长度的js `Array`。|10| 64|FUNC|napi_create_arraybuffer|创建并获取一个指定大小的js `ArrayBuffer`。|10| 65|FUNC|napi_create_external|分配一个附加有外部数据的js value。|10| 66|FUNC|napi_create_external_arraybuffer|分配一个附加有外部数据的js `ArrayBuffer`。|10| 67|FUNC|napi_create_object|创建一个默认的js `Object`。|10| 68|FUNC|napi_create_symbol|创建一个js `Symbol`。|10| 69|FUNC|napi_create_typedarray|通过现有的`ArrayBuffer`创建一个js `TypeArray`。|10| 70|FUNC|napi_create_dataview|通过现有的`ArrayBuffer`创建一个js `DataView`。|10| 71|FUNC|napi_create_int32|通过一个C的`int32_t`数据创建js `Number`。|10| 72|FUNC|napi_create_uint32|通过一个C的`uint32_t`数据创建js `Number`。|10| 73|FUNC|napi_create_int64|通过一个C的`int64_t`数据创建js `Number`。|10| 74|FUNC|napi_create_double|通过一个C的`double`数据创建js `Number`。|10| 75|FUNC|napi_create_string_latin1|通过ISO-8859-1编码的C字符串数据创建js `String`。|10| 76|FUNC|napi_create_string_utf8|通过UTF8编码的C字符串数据创建js `String`。|10| 77|FUNC|napi_create_string_utf16|通过UTF16编码的C字符串数据创建js `String`。|10| 78|FUNC|napi_get_array_length|获取array的length。|10| 79|FUNC|napi_get_arraybuffer_info|获取`ArrayBuffer`的底层data buffer及其长度。|10| 80|FUNC|napi_get_prototype|获取给定js `Object`的`prototype`。|10| 81|FUNC|napi_get_typedarray_info|获取给定`TypedArray`的各种属性。|10| 82|FUNC|napi_get_dataview_info|获取给定`DataView`的各种属性。|10| 83|FUNC|napi_get_value_bool|获取给定js `Boolean`对应的C bool值。|10| 84|FUNC|napi_get_value_double|获取给定js `Number`对应的C double值。|10| 85|FUNC|napi_get_value_external|获取先前通过napi_create_external()传递的外部数据指针。|10| 86|FUNC|napi_get_value_int32|获取给定js `Number`对应的C int32值。|10| 87|FUNC|napi_get_value_int64|获取给定js `Number`对应的C int64值。|10| 88|FUNC|napi_get_value_string_latin1|获取给定js value对应的ISO-8859-1编码的字符串。|10| 89|FUNC|napi_get_value_string_utf8|获取给定js value对应的UTF8编码的字符串。|10| 90|FUNC|napi_get_value_string_utf16|获取给定js value对应的UTF16编码的字符串。|10| 91|FUNC|napi_get_value_uint32|获取给定js `Number`对应的C uint32值。|10| 92|FUNC|napi_get_boolean|根据给定的C boolean值，获取js bool对象。|10| 93|FUNC|napi_get_global|获取`global`对象。|10| 94|FUNC|napi_get_null|获取`null`对象。|10| 95|FUNC|napi_get_undefined|获取`undefined`对象。|10| 96|FUNC|napi_coerce_to_bool|将给定的js value强转成js `Boolean`。|10| 97|FUNC|napi_coerce_to_number|将给定的js value强转成js `Number`。|10| 98|FUNC|napi_coerce_to_object|将给定的js value强转成js `Object`。|10| 99|FUNC|napi_coerce_to_string|将给定的js value强转成js `String`。|10| 100|FUNC|napi_typeof|获取给定js value的js type。|10| 101|FUNC|napi_instanceof|判断给定object是否为给定constructor的实例。|10| 102|FUNC|napi_is_array|判断给定js value是否为array。|10| 103|FUNC|napi_is_arraybuffer|判断给定js value是否为`ArrayBuffer`。|10| 104|FUNC|napi_is_typedarray|判断给定js value是否表示一个`TypedArray`。|10| 105|FUNC|napi_is_dataview|判断给定js value是否表示一个`DataView`。|10| 106|FUNC|napi_is_date|判断给定js value是否为js `Date`对象。|10| 107|FUNC|napi_strict_equals|判断给定的两个js value是否严格相等。|10| 108|FUNC|napi_get_property_names|以字符串数组的形式获取对象的可枚举属性的名称。|10| 109|FUNC|napi_set_property|对给定`Object`设置属性。|10| 110|FUNC|napi_get_property|获取给定`Object`的给定属性。|10| 111|FUNC|napi_has_property|判断给定对象中是否存在给定属性。|10| 112|FUNC|napi_delete_property|尝试从给定`Object`中删除给定`key`属性。|10| 113|FUNC|napi_has_own_property|判断给定`Object`中是否有名为`key`的own property。|10| 114|FUNC|napi_set_named_property|对给定`Object`设置一个给定名称的属性。|10| 115|FUNC|napi_get_named_property|获取给定`Object`中指定名称的属性。|10| 116|FUNC|napi_has_named_property|判断给定`Object`中是否有给定名称的属性。|10| 117|FUNC|napi_set_element|在给定`Object`的指定索引处，设置元素。|10| 118|FUNC|napi_get_element|获取给定`Object`指定索引处的元素。|10| 119|FUNC|napi_has_element|若给定`Object`的指定索引处拥有属性，获取该元素。|10| 120|FUNC|napi_delete_element|尝试删除给定`Object`的指定索引处的元素。|10| 121|FUNC|napi_define_properties|批量的向给定`Object`中定义属性。|10| 122|FUNC|napi_type_tag_object|将tag指针的值与`Object`关联。|10| 123|FUNC|napi_check_object_type_tag|判断给定的tag指针是否被关联到了js `Object`上。|10| 124|FUNC|napi_call_function|在Native方法中调用js function，即native call js。|10| 125|FUNC|napi_create_function|创建native方法给js使用，以便于js call native。|10| 126|FUNC|napi_get_cb_info|从给定的callback info中获取有关调用的详细信息，如参数和this指针。|10| 127|FUNC|napi_get_new_target|获取构造函数调用的`new.target`。|10| 128|FUNC|napi_new_instance|通过给定的构造函数，构建一个实例。|10| 129|FUNC|napi_define_class|定义与C++类相对应的JavaScript类。|10| 130|FUNC|napi_wrap|在js object上绑定一个native对象实例。|10| 131|FUNC|napi_unwrap|从js object上获取先前绑定的native对象实例。|10| 132|FUNC|napi_remove_wrap|从js object上获取先前绑定的native对象实例，并解除绑定。|10| 133|FUNC|napi_create_async_work|创建一个异步工作对象。|10| 134|FUNC|napi_delete_async_work|释放先前创建的异步工作对象。|10| 135|FUNC|napi_queue_async_work|将异步工作对象加到队列，由底层去调度执行。|10| 136|FUNC|napi_cancel_async_work|取消入队的异步任务。|10| 137|FUNC|napi_async_init|创建一个异步资源上下文环境（不支持与async_hook相关能力）。|11| 138|FUNC|napi_make_callback|在异步资源上下文环境中回调JS函数(不支持与async_hook相关能力)。|11| 139|FUNC|napi_async_destroy|销毁先前创建的异步资源上下文环境（不支持与async_hook相关能力）。|11| 140|FUNC|napi_open_callback_scope|创建一个回调作用域（不支持与async_hook相关能力）。|11| 141|FUNC|napi_close_callback_scope|关闭先前创建的回调作用域（不支持与async_hook相关能力）。|11| 142|FUNC|napi_get_node_version|获取node的版本信息。|10| 143|FUNC|napi_get_version|获取Node运行时支持的最高 N-API 版本。|10| 144|FUNC|napi_create_promise|创建一个延迟对象和js promise。|10| 145|FUNC|napi_resolve_deferred|resolve与js promise对象关联的延迟函数。|10| 146|FUNC|napi_reject_deferred|reject与js promise对象关联的延迟函数。|10| 147|FUNC|napi_is_promise|判断给定js value是否为promise对象。|10| 148|FUNC|napi_get_uv_event_loop|获取当前libuv loop实例。|10| 149|FUNC|napi_create_threadsafe_function|创建线程安全函数。|10| 150|FUNC|napi_get_threadsafe_function_context|获取线程安全函数中的context。|10| 151|FUNC|napi_call_threadsafe_function|调用线程安全函数。|10| 152|FUNC|napi_acquire_threadsafe_function|指示线程安全函数可以开始使用。|10| 153|FUNC|napi_release_threadsafe_function|指示线程安全函数将停止使用。|10| 154|FUNC|napi_ref_threadsafe_function|指示在主线程上运行的事件循环在线程安全函数被销毁之前不应退出。|10| 155|FUNC|napi_unref_threadsafe_function|指示在主线程上运行的事件循环可能会在线程安全函数被销毁之前退出。|10| 156|FUNC|napi_create_date|通过一个C的`double`数据创建js `Date`。|10| 157|FUNC|napi_get_date_value|获取给定js `Date`对应的C double值。|10| 158|FUNC|napi_create_bigint_int64|通过一个C的`int64`数据创建js `BigInt`。|10| 159|FUNC|napi_create_bigint_uint64|通过一个C的`uint64`数据创建js `BigInt`。|10| 160|FUNC|napi_create_bigint_words|通过一个C的`uint64`数组创建单个js `BigInt`。|10| 161|FUNC|napi_get_value_bigint_int64|获取给定js `BigInt`对应的C int64值。|10| 162|FUNC|napi_get_value_bigint_uint64|获取给定js `BigInt`对应的C uint64值。|10| 163|FUNC|napi_get_value_bigint_words|获取给定js `BigInt`对应的信息，包括符号位、64位小端序数组和数组中的元素个数。|10| 164|FUNC|napi_create_buffer|创建并获取一个指定大小的js `Buffer`。|10| 165|FUNC|napi_create_buffer_copy|创建并获取一个指定大小的js `Buffer`，并以给定数据进行初始化。|10| 166|FUNC|napi_create_external_buffer|创建并获取一个指定大小的js `Buffer`，并以给定数据进行初始化，该接口可为`Buffer`附带额外数据。|10| 167|FUNC|napi_get_buffer_info|获取js `Buffer`底层data及其长度。|10| 168|FUNC|napi_is_buffer|判断给定js value是否为`Buffer`对象。|10| 169|FUNC|napi_object_freeze|冻结给定的对象。|10| 170|FUNC|napi_object_seal|密封给定的对象。|10| 171|FUNC|napi_get_all_property_names|获取一个数组，其中包含此对象过滤后的属性名称。|10| 172|FUNC|napi_detach_arraybuffer|分离给定`ArrayBuffer`的底层数据。|10| 173|FUNC|napi_is_detached_arraybuffer|判断给定的`ArrayBuffer`是否已被分离过。|10| 174|FUNC|napi_run_script|将给定对象作为js代码运行。当前接口实际为空实现，可使用系统拓展接口`napi_run_script_path`接口，提升安全性。|10| 175|FUNC|napi_set_instance_data|绑定与当前运行的环境相关联的数据项。|11| 176|FUNC|napi_get_instance_data|检索与当前运行的环境相关联的数据项。|11| 177|FUNC|napi_add_env_cleanup_hook|注册环境清理钩子函数。|11| 178|FUNC|napi_remove_env_cleanup_hook|取消环境清理钩子函数。|11| 179|FUNC|napi_add_async_cleanup_hook|注册清理异步钩子函数。|11| 180|FUNC|napi_remove_async_cleanup_hook|取消清理异步钩子函数。|11| 181|FUNC|node_api_get_module_file_name|用于获取加载项加载位置的绝对路径。|11| 182|FUNC|napi_add_finalizer|当js `Object`中的对象被垃圾回收时调用注册的napi_finalize回调。|11| 183|FUNC|napi_fatal_exception|向js抛出 `UncaughtException`。|12| 184 185## 已导出符号列表与标准库对应符号的差异 186 187### napi_throw_error 188 189**返回：** 190 191- 当code为空指针时，标准库会返回napi_invalid_arg，而OpenHarmony中未做判断。 192 193- 该导出接口允许code属性设置失败。 194 195### napi_throw_type_error 196 197**返回：** 198 199- 当code为空指针时，标准库会返回napi_invalid_arg，而OpenHarmony中未做判断。 200 201- 该导出接口允许code属性设置失败。 202 203### napi_throw_range_error 204 205**返回：** 206 207- 当code为空指针时，标准库会返回napi_invalid_arg，而OpenHarmony中未做判断。 208 209- 该导出接口允许code属性设置失败。 210 211### napi_create_error 212 213**参数：** 214 215- code: 该导出接口支持String或Number类型。 216 217**返回：** 218 219- 当code类型不匹配时，该导出接口返回napi_invalid_arg。 220 221- 该导出接口允许code属性设置失败。 222 223### napi_create_type_error 224 225**参数：** 226 227- code: 该导出接口支持String或Number类型。 228 229**返回：** 230 231- 当code类型不匹配时，该导出接口返回napi_invalid_arg。 232 233- 该导出接口允许code属性设置失败。 234 235- OpenHarmony中创建的错误类型为Error。 236 237### napi_create_range_error 238 239**参数：** 240 241- code: OpenHarmony中支持String或Number类型。 242 243**返回：** 244 245- 当code类型不匹配时，该导出接口返回napi_invalid_arg。 246 247- 该导出接口允许code属性设置失败。 248 249- OpenHarmony中创建的错误类型为Error。 250 251### napi_create_reference 252 253**参数：** 254 255- value: 标准库中仅支持Object、Function、Symbol类型，而该导出接口对value的类型没有限制。 256 257### napi_delete_reference 258 259**说明：** 260 261- 在OpenHarmony中，如果创建强引用时注册了napi_finalize回调函数，调用该接口的时候会触发该napi_finalize回调。 262 263### napi_create_symbol 264 265**返回：** 266 267- 当入参description不为空且不是String对象时，该导出接口返回napi_invalid_arg。 268 269### napi_create_typedarray 270 271**返回：** 272 273- 当入参arraybuffer不为空且不为ArrayBuffer对象时，该导出接口返回napi_arraybuffer_expected。 274 275### napi_create_dataview 276 277**返回：** 278 279- 当入参arraybuffer不为空且不为ArrayBuffer对象时，该导出接口返回napi_arraybuffer_expected。 280 281- 如果byte_offset与byte_length的和大于arraybuffer的大小，该导出接口将会抛出RangeError异常，并返回napi_pending_exception。 282 283### napi_get_typedarray_info 284 285**参数：** 286 287- object: 该导出接口支持TypedArray或Sendable TypedArray（[Int8Array](../apis-arkts/arkts-apis-arkts-collections-Int8Array.md)、[Uint8Array](../apis-arkts/arkts-apis-arkts-collections-Uint8Array.md)、[Int16Array](../apis-arkts/arkts-apis-arkts-collections-Int16Array.md)、[Uint16Array](../apis-arkts/arkts-apis-arkts-collections-Uint16Array.md)、[Int32Array](../apis-arkts/arkts-apis-arkts-collections-Int32Array.md)、[Uint32Array](../apis-arkts/arkts-apis-arkts-collections-Uint32Array.md)、[Uint8ClampedArray](../apis-arkts/arkts-apis-arkts-collections-Uint8ClampedArray.md)、[Float32Array](../apis-arkts/arkts-apis-arkts-collections-Float32Array.md)）类型。 288 289**返回：** 290 291- 标准库接口中出参length返回typedarray的元素数量，而OpenHarmony的该导出接口返回typedarray中元素的字节长度。 292 293### napi_coerce_to_object 294 295**返回：** 296 297- 当value为undefined或null时，该导出接口返回napi_ok，出参result为undefined。 298 299### napi_instanceof 300 301**返回：** 302 303- 当参数object不是Object对象时，该导出接口直接返回napi_object_expected，result不做处理。 304 305- 当参数constructor不是Function对象时，该导出接口不会抛出异常，接口返回napi_function_expected。 306 307### napi_is_typedarray 308 309**参数：** 310 311- value: 该导出接口额外支持Sendable TypedArray（[Int8Array](../apis-arkts/arkts-apis-arkts-collections-Int8Array.md)、[Uint8Array](../apis-arkts/arkts-apis-arkts-collections-Uint8Array.md)、[Int16Array](../apis-arkts/arkts-apis-arkts-collections-Int16Array.md)、[Uint16Array](../apis-arkts/arkts-apis-arkts-collections-Uint16Array.md)、[Int32Array](../apis-arkts/arkts-apis-arkts-collections-Int32Array.md)、[Uint32Array](../apis-arkts/arkts-apis-arkts-collections-Uint32Array.md)、[Uint8ClampedArray](../apis-arkts/arkts-apis-arkts-collections-Uint8ClampedArray.md)、[Float32Array](../apis-arkts/arkts-apis-arkts-collections-Float32Array.md)）类型。 312 313### napi_get_property_names 314 315**返回：** 316 317- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 318 319### napi_set_property 320 321**返回：** 322 323- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 324 325### napi_get_property 326 327**返回：** 328 329- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 330 331### napi_has_property 332 333**返回：** 334 335- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 336 337### napi_delete_property 338 339**返回：** 340 341- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 342 343### napi_has_own_property 344 345**返回：** 346 347- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 348 349### napi_set_named_property 350 351**返回：** 352 353- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 354 355### napi_get_named_property 356 357**返回：** 358 359- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 360 361### napi_has_named_property 362 363**返回：** 364 365- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 366 367### napi_set_element 368 369**返回：** 370 371- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 372 373- 当设置的index超大的时候，标准库中会直接抛出异常并中断进程，OpenHarmony中会尝试分配内存，若分配失败则不对object进行修改。 374 375### napi_get_element 376 377**返回：** 378 379- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 380 381### napi_has_element 382 383**返回：** 384 385- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 386 387### napi_delete_element 388 389**返回：** 390 391- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 392 393### napi_define_properties 394 395**返回：** 396 397- 当参数object不是Object或Function对象时，该导出接口返回napi_object_expected。 398 399- 若在遍历设置属性的过程中触发异常，标准库中会直接将异常抛出，OpenHarmony中会清除异常继续执行。 400 401### napi_type_tag_object 402 403**返回：** 404 405- 当参数js_object不是Object或Function对象时，该导出接口返回napi_object_expected。 406 407### napi_check_object_type_tag 408 409**返回：** 410 411- 当参数js_object不是Object或Function对象时，该导出接口返回napi_object_expected。 412 413### napi_call_function 414 415**返回：** 416 417- 该导出接口不会去校验参数recv是否为nullptr。 418 419- 当参数func不是Function对象时，该导出接口返回napi_function_expected。 420 421### napi_new_instance 422 423**返回：** 424 425- 当参数constructor不是Function对象时，该导出接口返回napi_function_expected。 426 427### napi_define_class 428 429**返回：** 430 431- 当length不为NAPI_AUTO_LENGTH且大于INT_MAX时，该导出接口返回napi_object_expected。 432 433### napi_wrap 434 435**参数：** 436 437- finalize_cb: 标准库允许为空， OpenHarmony在该参数为空时，返回napi_invalid_arg。 438- result: 标准库返回弱引用， OpenHarmony在result不为空时返回强引用。 439 440**返回：** 441 442- 参数js_object不为Object或Function对象时，该导出接口返回napi_object_expected。 443 444### napi_unwrap 445 446**返回：** 447 448- 参数js_object不为Object或Function对象时，该导出接口返回napi_object_expected。 449 450### napi_remove_wrap 451 452**返回：** 453 454- 参数js_object不为Object或Function对象时，该导出接口返回napi_object_expected。 455 456**说明：** 457 458- 如果封装中关联有finalize回调，OpenHarmony中该导出接口将在移除封装前调用它。 459 460### napi_create_async_work 461 462**参数：** 463 464- 该导出接口暂时不支持async_hooks资源管理机制。 465 466- 该导出接口不会校验入参async_resource_name是否为String类型对象，入参async_resource_name推荐传入String对象，用于描述创建的异步工作对象。入参async_resource_name为String时，trace信息将包含该描述，反之传入非String对象，trace信息将不包含该描述。 467 468- 由于当前暂不支持async_hooks资源管理机制，入参async_resource暂时也不做处理。 469 470### napi_delete_async_work 471 472**参数：** 473 474- 该导出接口暂时不支持async_hooks资源管理机制。 475 476### napi_queue_async_work 477 478**参数：** 479 480- 该导出接口暂时不支持async_hooks资源管理机制。 481 482### napi_cancel_async_work 483 484**返回：** 485 486- 若因为底层uv导致取消任务失败，标准库会根据失败原因，返回napi_generic_failure或napi_invalid_arg或napi_cancelled，而在OpenHarmony上该导出接口不会去校验uv的返回值，开发者可以根据相关的日志去排查任务是否取消失败。 487 488### napi_async_init 489 490**说明：** 491 492- OpenHarmony暂不支持async_hooks资源管理机制。目前未实现与async_hooks交互的内容，该接口调用后并不会有async_hooks的相关操作。 493 494### napi_make_callback 495 496**说明：** 497 498- OpenHarmony暂不支持async_hooks资源管理机制。目前未实现与async_hooks交互的内容，该接口调用后并不会有async_hooks的相关操作。 499 500### napi_async_destroy 501 502**说明：** 503 504- OpenHarmony暂不支持async_hooks资源管理机制。目前未实现与async_hooks交互的内容，接口调用后并不会有async_hooks的相关操作。 505 506### napi_get_node_version 507 508**说明：** 509 510- OpenHarmony不需要获取node的版本，故当前该导出接口为空实现。 511 512### napi_resolve_deferred 513 514**说明：** 515 516- promise的then方法的resolve或者reject回调中出现异常时，如果promise没有catch块，代码会继续执行不会崩溃；如果promise有catch块，则异常会被该catch块捕获。 517 518### napi_reject_deferred 519 520**说明：** 521 522- promise的then方法的resolve或者reject回调中出现异常时，如果promise没有catch块，代码会继续执行不会崩溃；如果promise有catch块，则异常会被该catch块捕获。 523 524### napi_create_threadsafe_function 525 526**参数：** 527 528- initial_thread_count: OpenHarmony中上限为128。 529 530- async_resource: OpenHarmony中不做类型限制。 531 532- async_resource_name: OpenHarmony中不做类型限制。 533 534- func: OpenHarmony中不做类型限制。 535 536**说明：** 537 538- OpenHarmony中，创建线程安全函数的过程中没有注册cleanup hook方法，如有需要可以调用napi_add_env_cleanup_hook。 539 540### napi_call_threadsafe_function 541 542**说明：** 543 544- OpenHarmony调用uv_async_send接口前会检查env是否存活。 545 546- 调用uv_async_send接口失败时，OpenHarmony中会返回napi_generic_failure。 547 548### napi_release_threadsafe_function 549 550**说明：** 551 552- OpenHarmony调用uv_async_send接口前会检查env是否存活。 553 554- ThreadCount为0时，OpenHarmony中会返回napi_generic_failure。 555 556### napi_ref_threadsafe_function 557 558**说明：** 559 560- OpenHarmony中有校验func和env是否为同一ArkTS线程的过程，若不是同一线程则会返回napi_generic_failure。 561 562### napi_unref_threadsafe_function 563 564**说明：** 565 566- OpenHarmony中有校验func和env是否为同一ArkTS线程的过程，若不是同一线程则会返回napi_generic_failure。 567 568### napi_create_date 569 570**返回：** 571 572- 当入参正常但date创建失败时，标准库中返回napi_generic_failure，而OpenHarmony中将会抛出异常，并且接口返回napi_pending_exception。 573 574### napi_create_bigint_words 575 576**返回：** 577 578- 当入参正常但bigInt创建失败时，标准库中返回napi_generic_failure，而OpenHarmony中将会抛出异常，并且接口返回napi_pending_exception。 579 580### napi_get_value_bigint_words 581 582**返回：** 583 584- 当参数value不是BigInt对象时，OpenHarmony中返回napi_object_expected。 585 586### napi_create_buffer 587 588**返回：** 589 590- OpenHarmony中创建的buffer类型为ArrayBufferLike。 591 592- OpenHarmony中，size小于等于0时返回napi_invalid_arg。 593 594- OpenHarmony中，size大于2097152时返回napi_invalid_arg并打印错误日志。 595 596- OpenHarmony中，data为nullptr时返回napi_invalid_arg。 597 598- 标准库中，进入或退出接口前若有异常将直接返回napi_pending_exception，OpenHarmony中没有对此做校验。 599 600### napi_create_buffer_copy 601 602**返回：** 603 604- OpenHarmony中创建的buffer类型为ArrayBufferLike。 605 606- OpenHarmony中，length小于等于0时返回napi_invalid_arg。 607 608- OpenHarmony中，length大于2097152时返回napi_invalid_arg并打印错误日志。 609 610- OpenHarmony中，data为nullptr时返回napi_invalid_arg。 611 612- 标准库中，进入或退出接口前若有异常将直接返回napi_pending_exception，OpenHarmony中没有对此做校验。 613 614### napi_create_external_buffer 615 616**返回：** 617 618- OpenHarmony中创建的buffer类型为ArrayBufferLike。 619 620- OpenHarmony中，length小于等于0时返回napi_invalid_arg。 621 622- OpenHarmony中，length大于2097152时返回napi_invalid_arg并打印错误日志。 623 624- 标准库中，因未知原因导致创建失败时将返回napi_generic_failure，OpenHarmony中返回napi_pending_exception。 625 626### napi_get_buffer_info 627 628**返回：** 629 630- OpenHarmony会对value是否属于buffer进行判断，若不属于则返回napi_arraybuffer_expected。 631 632### napi_detach_arraybuffer 633 634**返回：** 635 636- 当入参arraybuffer不为Object对象时，该导出接口返回napi_object_expected；当arraybuffer是Object对象但不为ArrayBuffer对象时，该导出接口返回napi_invalid_arg。 637 638### napi_add_env_cleanup_hook 639 640**说明：** 641 642- data已注册到env中时，OpenHarmony仅打印异常日志。 643 644### napi_add_finalizer 645 646**返回：** 647 648- 入参js_object不是Object对象时，OpenHarmony中该导出接口返回napi_object_expected。 649 650**说明：** 651 652- OpenHarmony中，当强引用delete时直接进行回调，无需等到对象析构。 653 654- 回调主动抛出异常时，OpenHarmony会触发JSCrash。 655 656**说明：** 657 658- 标准库中返回弱引用， OpenHarmony在result不为空时返回强引用。 659 660### napi_fatal_exception 661 662**参数：** 663 664- err: OpenHarmony中仅支持Error类型，类型不匹配将返回napi_invalid_arg。 665 666### napi_get_uv_event_loop 667 668**返回：** 669 670- 参数env不是有效的napi_env（例如此env已被释放）时，该导出接口返回napi_generic_failure。 671 672### napi_create_array_with_length 673 674**返回：** 675 676- 当length数值过大时，标准库中会直接抛出异常并中断进程，OpenHarmony中会尝试分配内存，若分配失败则抛出异常并返回长度为0的array。 677 678### napi_create_arraybuffer 679 680**返回：** 681 682- 当length数值过大时，标准库中会直接抛出异常并中断进程，OpenHarmony中会尝试分配内存，若分配失败则抛出异常并返回undefined。 683 684## 未从Node-API组件标准库中导出的符号列表 685 686|符号类型|符号名|说明| 687| --- | --- | --- | 688|FUNC|napi_adjust_external_memory|调整js `Object`持有的外部内存。| 689 690## Node-API组件扩展的符号列表 691 692|符号类型|符号名|说明|起始支持API版本| 693| --- | --- | --- | --- | 694|FUNC|napi_queue_async_work_with_qos|将异步工作对象加到队列，由底层根据传入的qos优先级去调度执行。|10| 695|FUNC|napi_run_script_path|运行abc文件。|10| 696|FUNC|napi_load_module|将abc文件作为模块加载，返回模块的命名空间。|11| 697|FUNC|napi_create_object_with_properties|使用给定的napi_property_descriptor创建js `Object`。descriptor的键名必须为 string，且不可转为number。|11| 698|FUNC|napi_create_object_with_named_properties|使用给定的napi_value和键名创建js `Object`。键名必须为 string，且不可转为number。|11| 699|FUNC|napi_coerce_to_native_binding_object|强制将js `Object`和Native对象绑定。|11| 700|FUNC|napi_create_ark_runtime|创建基础运行时环境。|12| 701|FUNC|napi_destroy_ark_runtime|销毁基础运行时环境。|12| 702|FUNC|napi_run_event_loop|触发底层的事件循环。|12| 703|FUNC|napi_stop_event_loop|停止底层的事件循环。|12| 704|FUNC|napi_load_module_with_info|将abc文件作为模块加载，返回模块的命名空间。可在新创建的ArkTS基础运行时环境中使用。|12| 705|FUNC|napi_serialize|将ArkTS对象转换为native数据。|12| 706|FUNC|napi_deserialize|将native数据转为ArkTS对象。|12| 707|FUNC|napi_delete_serialization_data|删除序列化数据。|12| 708|FUNC|napi_call_threadsafe_function_with_priority|将指定优先级和入队方式的任务投递到ArkTS主线程。|12| 709|FUNC|napi_is_sendable|判断给定JS value是否是Sendable的。|12| 710|FUNC|napi_define_sendable_class|创建一个Sendable类。|12| 711|FUNC|napi_create_sendable_object_with_properties | 使用给定的napi_property_descriptor创建一个Sendable对象。|12| 712|FUNC|napi_create_sendable_array | 创建一个Sendable数组。|12| 713|FUNC|napi_create_sendable_array_with_length | 创建一个指定长度的Sendable数组。|12| 714|FUNC|napi_create_sendable_arraybuffer | 创建一个Sendable ArrayBuffer。|12| 715|FUNC|napi_create_sendable_typedarray | 创建一个Sendable TypedArray。|12| 716|FUNC|napi_wrap_sendable | 包裹一个native实例到ArkTS对象中。|12| 717|FUNC|napi_wrap_sendable_with_size | 包裹一个native实例到ArkTS对象中并指定大小。|12| 718|FUNC|napi_unwrap_sendable | 获取ArkTS对象包裹的native实例。|12| 719|FUNC|napi_remove_wrap_sendable | 移除并获取ArkTS对象包裹的native实例，移除后回调将不再触发，需手动delete释放内存。|12| 720|FUNC|napi_wrap_enhance | 在ArkTS对象上绑定一个Node-API模块对象实例并指定实例大小，开发者可以指定绑定的回调函数是否异步执行（若异步则需线程安全）。|18| 721|FUNC|napi_create_ark_context|创建一个新的运行时上下文环境。|20| 722|FUNC|napi_switch_ark_context|切换到指定的运行时上下文环境。|20| 723|FUNC|napi_destroy_ark_context|销毁通过接口napi_create_ark_context创建的一个上下文环境。|20| 724 725> 说明： 726> 727> 有关Sendable特性的介绍，详见[Sendable开发指导](../../arkts-utils/arkts-sendable.md)。 728 729### napi_qos_t 730 731```cpp 732typedef enum { 733 napi_qos_background = 0, // 低等级，用户不可见任务，例如数据同步、备份。 734 napi_qos_utility = 1, // 中低等级，不需要立即看到响应效果的任务，例如下载或导入数据。 735 napi_qos_default = 2, // 默认 736 napi_qos_user_initiated = 3, // 高等级，用户触发并且可见进展，例如打开文档。 737} napi_qos_t; 738``` 739 740**描述：** 741表示QoS的枚举值，QoS决定了线程调度的优先级。 742 743### napi_event_mode 744 745```cpp 746typedef enum { 747 napi_event_mode_default = 0, // 阻塞式的运行底层事件循环，直到循环中没有任何任务时退出事件循环。 748 napi_event_mode_nowait = 1, // 非阻塞式的运行底层事件循环，尝试去处理一个任务，处理完之后退出事件循环；如果事件循环中没有任务，立刻退出事件循环。 749} napi_event_mode; 750``` 751 752**描述：** 753用于运行事件循环的事件模式。 754 755### napi_queue_async_work_with_qos 756 757```cpp 758napi_status napi_queue_async_work_with_qos(napi_env env, 759 napi_async_work work, 760 napi_qos_t qos); 761``` 762 763**描述：** 764 765将异步工作对象加到队列，由底层根据传入的qos优先级去调度执行。 766 767**参数：** 768 769- [in] env: Node-API的环境对象，表示当前的执行环境。 770 771- [in] work: 一个表示异步工作项的对象。这个对象通常是通过napi_create_async_work函数创建的。 772 773- [in] qos: 决定了线程调度的优先级。 774 775**返回：** 776 777如果API成功，则返回napi_ok。 778 779### napi_run_script_path 780 781```cpp 782napi_status napi_run_script_path(napi_env env, 783 const char* abcPath, 784 napi_value* result); 785``` 786 787**描述：** 788 789运行指定abc文件。 790 791**参数：** 792 793- [in] env: Node-API的环境对象，表示当前的执行环境。 794 795- [in] abcPath: 要运行的脚本的JavaScript路径。这是一个字符串，指定了要运行的脚本文件的位置。 796 797- [out] result: 一个指向napi_value类型的指针，用于存储运行脚本的结果。 798 799**返回：** 800 801如果API成功，则返回napi_ok。 802 803### napi_load_module 804 805```cpp 806napi_status napi_load_module(napi_env env, 807 const char* path, 808 napi_value* result); 809``` 810 811**描述：** 812 813加载系统模块或开发者自定义的模块，返回模块的命名空间。 814 815**参数：** 816 817- [in] env: Node-API的环境对象，表示当前的执行环境。 818 819- [in] path: 要加载的系统模块的名称或开发者自定义模块的路径。 820 821- [out] result: 一个指向napi_value类型的指针，用于存储加载模块的结果。 822 823**返回：** 824 825如果API成功，则返回napi_ok。 826 827### napi_create_object_with_properties 828 829```cpp 830napi_status napi_create_object_with_properties(napi_env env, 831 napi_value* result, 832 size_t property_count, 833 const napi_property_descriptor* properties); 834``` 835 836**描述：** 837 838属性描述符napi_property_descriptor用于描述一个属性，它包括属性的名称获取和设置方法、属性特性等信息。通过传入这些描述符，可以在创建对象时就定义属性。 839 840使用给定的napi_property_descriptor创建js Object。descriptor的键名必须为string，且不可转为number。 841 842**参数：** 843 844- [in] env: Node-API的环境对象，表示当前的执行环境。 845 846- [out] result: 一个指向napi_value类型的指针，用于存储创建的对象。 847 848- [in] property_count: 要添加到对象中的属性的数量。 849 850- [in] properties: 一个指向napi_property_descriptor数组的指针，描述了要添加到对象中的属性的信息。 851 852**返回：** 853 854如果API成功，则返回napi_ok。 855 856### napi_create_object_with_named_properties 857 858```cpp 859napi_status napi_create_object_with_named_properties(napi_env env, 860 napi_value* result, 861 size_t property_count, 862 const char** keys, 863 const napi_value* values); 864``` 865 866**描述：** 867 868使用给定的napi_value和键名创建js Object。键名必须为string，且不可转为number。 869 870**参数：** 871 872- [in] env: Node-API的环境对象，表示当前的执行环境。 873 874- [out] result: 一个指向napi_value类型的指针，用于存储创建的对象。 875 876- [in] property_count: 要添加到对象中的属性的数量。 877 878- [in] keys: 一个指向const char*数组的指针，表示属性的名称。 879 880- [in] values: 一个指向napi_value数组的指针，表示属性的值，与属性名称一一对应。 881 882**返回：** 883 884如果API成功，则返回napi_ok。 885 886### napi_coerce_to_native_binding_object 887 888```cpp 889napi_status napi_coerce_to_native_binding_object(napi_env env, 890 napi_value js_object, 891 napi_native_binding_detach_callback detach_cb, 892 napi_native_binding_attach_callback attach_cb, 893 void* native_object, 894 void* hint); 895``` 896 897**描述：** 898 899用于给JS Object绑定回调和回调所需的参数，转成携带Native信息的JS Object。 900 901**参数：** 902 903- [in] env: Node-API的环境对象，表示当前的执行环境。 904 905- [in] js_object: 要转换的JavaScript对象。 906 907- [in] detach_cb: 解绑回调，一般在序列化时调用，可在对象解绑时执行一些清理操作。 908 909- [in] attach_cb: 绑定回调，一般在序列化时调用。 910 911- [in] native_object: 需要传递给回调的参数，不能为空。 912 913- [in] hint: 一个指针，可以用于传递附加的信息给回调函数。 914 915**返回：** 916 917如果API成功，则返回napi_ok。 918 919### napi_create_ark_runtime 920 921```cpp 922napi_status napi_create_ark_runtime(napi_env *env) 923``` 924 925**描述：** 926 927创建基础运行时环境，一个进程最多创建64个，并满足与[Worker](../../arkts-utils/worker-introduction.md)创建的子线程总数不超过80个。 928 929**参数：** 930 931- [in] env: Node-API的环境对象，表示当前的执行环境。 932 933**返回：** 934 935如果API成功，则返回napi_ok。 936 937### napi_destroy_ark_runtime 938 939```cpp 940napi_status napi_destroy_ark_runtime(napi_env *env) 941``` 942 943**描述：** 944 945销毁基础运行时环境。 946 947**参数：** 948 949- [in] env: Node-API的环境对象，表示当前的执行环境。 950 951**返回：** 952 953如果API成功，则返回napi_ok。 954 955### napi_run_event_loop 956 957```cpp 958napi_status napi_run_event_loop(napi_env env, napi_event_mode mode) 959``` 960 961**描述：** 962 963触发底层的事件循环。 964 965**参数：** 966 967- [in] env: Node-API的环境对象，表示当前的执行环境。 968- [in] mode: 用于运行事件循环的事件模式。 969 970**返回：** 971 972如果API成功，则返回napi_ok。 973 974### napi_stop_event_loop 975 976```cpp 977napi_status napi_stop_event_loop(napi_env env) 978``` 979 980**描述：** 981 982停止底层的事件循环。 983 984**参数：** 985 986- [in] env: Node-API的环境对象，表示当前的执行环境。 987 988**返回：** 989 990如果API成功，则返回napi_ok。 991 992### napi_load_module_with_info 993 994```cpp 995napi_status napi_load_module_with_info(napi_env env, 996 const char* path, 997 const char* module_info, 998 napi_value* result) 999``` 1000 1001**描述：** 1002 1003将abc文件作为模块加载，返回模块的命名空间。可在新创建的ArkTS基础运行时环境中使用。 1004 1005**参数：** 1006 1007- [in] env: Node-API的环境对象，表示当前的执行环境。 1008 1009- [in] path: 要加载的模块的路径。 1010 1011- [in] module_info: 模块信息。这是一个包含模块信息字符串。模块信息可以用于指定模块的版本、作者、描述等详细信息。 1012 1013- [out] result: 指向napi_value的指针，用于接收模块的结果。 1014 1015**返回：** 1016 1017如果API成功，则返回napi_ok。 1018 1019### napi_serialize 1020 1021```cpp 1022napi_status napi_serialize(napi_env env, 1023 napi_value object, 1024 napi_value transfer_list, 1025 napi_value clone_list, 1026 void** result) 1027``` 1028 1029**描述：** 1030 1031将ArkTS对象转换为native数据。 1032 1033**参数：** 1034 1035- [in] env: Node-API的环境对象，表示当前的执行环境。 1036 1037- [in] object: 要序列化的JavaScript对象。 1038 1039- [in] transfer_list: 传输列表，包含需要在序列化过程中转移的JavaScript对象。 1040 1041- [in] clone_list: 克隆列表，包含需要在序列化过程中克隆的JavaScript对象。 1042 1043- [out] result: 用于接收序列化结果的指针。在调用完成后，指向实际结果的指针会存储在此位置。 1044 1045**返回：** 1046 1047如果API成功，则返回napi_ok。 1048 1049### napi_deserialize 1050 1051```cpp 1052napi_status napi_deserialize(napi_env env, void* buffer, napi_value* object) 1053``` 1054 1055**描述：** 1056 1057将native数据转为ArkTS对象。 1058 1059**参数：** 1060 1061- [in] env: Node-API的环境对象，表示当前的执行环境。 1062 1063- [in] buffer: 指向包含二进制数据的指针。这些二进制数据需要被反序列化为JavaScript对象。 1064 1065- [out] object: 用于接收反序列化后的JavaScript对象。 1066 1067**返回：** 1068 1069如果API成功，则返回napi_ok。 1070 1071### napi_delete_serialization_data 1072 1073```cpp 1074napi_status napi_delete_serialization_data(napi_env env, void* buffer) 1075``` 1076 1077**描述：** 1078 1079删除序列化数据。 1080 1081**参数：** 1082 1083- [in] env: Node-API的环境对象，表示当前的执行环境。 1084 1085- [in] buffer: 指向包含序列化数据的内存缓冲区的指针。这些数据在序列化完成后不再需要，并且可以通过调用此函数来释放相应的内存。 1086 1087**返回：** 1088 1089如果API成功，则返回napi_ok。 1090 1091### napi_call_threadsafe_function_with_priority 1092 1093```cpp 1094napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func, 1095 void *data, 1096 napi_task_priority priority, 1097 bool isTail) 1098``` 1099 1100**描述：** 1101 1102将指定优先级和入队方式的任务投递到ArkTS主线程。 1103 1104**参数：** 1105 1106- [in] func: 线程安全函数对象，在创建线程安全函数时返回。 1107 1108- [in] data: 传递给 JavaScript 回调函数的参数数据。 1109 1110- [in] priority: 指定调用 JavaScript 回调函数的任务优先级。 1111 1112- [in] isTail: 一个布尔值，指示调用是否应该排队等待在事件循环的尾部执行。如果为 true，则调用将在事件循环的尾部执行；如果为 false，则调用将立即执行，不会排队等待。 1113 1114**返回：** 1115 1116如果API成功，则返回napi_ok。 1117 1118### napi_is_sendable 1119 1120```cpp 1121napi_status napi_is_sendable(napi_env env, napi_value value, bool* result) 1122``` 1123 1124**描述：** 1125 1126判断给定JS value是否是Sendable的。 1127 1128**参数：** 1129 1130- [in] env: Node-API的环境对象，表示当前的执行环境。 1131 1132- [in] value: 一个napi_value类型的参数，是需要判断的值。 1133 1134- [out] result: 一个bool类型的指针，用于存储判断结果。 1135 1136**返回：** 1137 1138如果API成功，则返回napi_ok。 1139 1140 1141### napi_define_sendable_class 1142 1143```cpp 1144napi_status napi_define_sendable_class(napi_env env, 1145 const char* utf8name, 1146 size_t length, 1147 napi_callback constructor, 1148 void* data, 1149 size_t property_count, 1150 const napi_property_descriptor* properties, 1151 napi_value parent, 1152 napi_value* result) 1153 1154 1155``` 1156 1157**描述：** 1158 1159创建一个Sendable类。 1160 1161**参数：** 1162 1163- [in] env: Node-API的环境对象，表示当前的执行环境。 1164 1165- [in] utf8name：一个const char*类型的参数，表示类的名称。 1166 1167- [in] length：一个size_t类型的参数，表示类名称的字节数。 1168 1169- [in] constructor：一个napi_callback类型的参数，表示类的构造函数。 1170 1171- [in] data：[可选]一个void*类型的参数，表示构造函数的附加数据。 1172 1173- [in] property_count：一个size_t类型的参数，表示类的属性数量。 1174 1175- [in] properties：[可选]一个const napi_property_descriptor*类型的参数，表示类的属性描述符数组。 1176 1177- [in] parent：[可选]一个napi_value类型的参数，表示父类。 1178 1179- [out] result：一个napi_value类型的指针，用于存储创建的对象。 1180 1181**返回：** 1182 1183如果API成功，则返回napi_ok。 1184 1185### napi_create_sendable_object_with_properties 1186 1187```cpp 1188napi_status napi_create_sendable_object_with_properties(napi_env env, 1189 size_t property_count, 1190 const napi_property_descriptor* properties, 1191 napi_value* result) 1192``` 1193 1194**描述：** 1195 1196使用给定的napi_property_descriptor创建一个Sendable对象。 1197 1198**参数：** 1199 1200- [in] env: Node-API的环境对象，表示当前的执行环境。 1201 1202- [in] property_count：一个size_t类型的参数，表示属性数量。 1203 1204- [in] properties：一个const napi_property_descriptor*类型的参数，表示属性描述符数组。 1205 1206- [out] result：一个napi_value类型的指针，用于存储创建的对象。 1207 1208**返回：** 1209 1210如果API成功，则返回napi_ok。 1211 1212### napi_create_sendable_array 1213 1214```cpp 1215napi_status napi_create_sendable_array(napi_env env, napi_value* result) 1216``` 1217 1218**描述：** 1219 1220创建一个Sendable数组。 1221 1222**参数：** 1223 1224- [in] env: Node-API的环境对象，表示当前的执行环境。 1225 1226- [out] result：一个napi_value类型的指针，用于存储创建的数组。 1227 1228**返回：** 1229 1230如果API成功，则返回napi_ok。 1231 1232### napi_create_sendable_array_with_length 1233 1234```cpp 1235napi_status napi_create_sendable_array_with_length(napi_env env, size_t length, napi_value* result) 1236``` 1237 1238**描述：** 1239 1240创建一个指定长度的Sendable数组。 1241 1242**参数：** 1243 1244- [in] env: Node-API的环境对象，表示当前的执行环境。 1245 1246- [in] length：一个size_t类型的参数，表示数组的长度。 1247 1248- [out] result：一个napi_value类型的指针，用于存储创建的数组。 1249 1250**返回：** 1251 1252如果API成功，则返回napi_ok。 1253 1254### napi_create_sendable_arraybuffer 1255 1256```cpp 1257napi_status napi_create_sendable_arraybuffer(napi_env env, size_t byte_length, void** data, napi_value* result) 1258``` 1259 1260**描述：** 1261 1262创建一个Sendable ArrayBuffer。 1263 1264**参数：** 1265 1266- [in] env: Node-API的环境对象，表示当前的执行环境。 1267 1268- [in] byte_length：要创建的ArrayBuffer的大小。 1269 1270- [in] data：指向底层字节缓冲区的指针。 1271 1272- [out] result：一个napi_value类型的指针，用于存储创建的ArrayBuffer。 1273 1274**返回：** 1275 1276如果API成功，则返回napi_ok。 1277 1278### napi_create_sendable_typedarray 1279 1280```cpp 1281napi_status napi_create_sendable_typedarray(napi_env env, 1282 napi_typedarray_type type, 1283 size_t length, 1284 napi_value arraybuffer, 1285 size_t byte_offset, 1286 napi_value* result); 1287``` 1288 1289**描述：** 1290 1291创建一个Sendable TypedArray。 1292 1293**参数：** 1294 1295- [in] env: Node-API的环境对象，表示当前的执行环境。 1296 1297- [in] type：TypedArray 的类型。 1298 1299- [in] length：TypedArray 的长度。 1300 1301- [in] arraybuffer：一个 ArrayBuffer 实例。 1302 1303- [in] byte_offset：ArrayBuffer 的偏移量。 1304 1305- [out] result：一个napi_value类型的指针，用于存储创建的TypedArray。 1306 1307**返回：** 1308 1309如果API成功，则返回napi_ok。 1310 1311### napi_wrap_sendable 1312 1313```cpp 1314napi_status napi_wrap_sendable(napi_env env, 1315 napi_value js_object, 1316 void* native_object, 1317 napi_finalize finalize_cb, 1318 void* finalize_hint); 1319``` 1320 1321**描述：** 1322 1323包裹一个native实例到ArkTS对象中。 1324 1325**参数：** 1326 1327- [in] env: Node-API的环境对象，表示当前的执行环境。 1328 1329- [in] js_object：ArkTS对象。 1330 1331- [in] native_object：将被包裹在ArkTS对象中的native实例。 1332 1333- [in] napi_finalize：[可选]ArkTS对象被销毁时调用的回调函数。 1334 1335- [in] finalize_hint：[可选]上下文提示，会传递给回调函数。 1336 1337**返回：** 1338 1339如果API成功，则返回napi_ok。 1340 1341### napi_wrap_sendable_with_size 1342 1343```cpp 1344napi_status napi_wrap_sendable_with_size(napi_env env, 1345 napi_value js_object, 1346 void* native_object, 1347 napi_finalize finalize_cb, 1348 void* finalize_hint, 1349 size_t native_binding_size); 1350``` 1351 1352**描述：** 1353 1354包装一个native实例到ArkTS对象中并指定大小。 1355 1356**参数：** 1357 1358- [in] env: Node-API的环境对象，表示当前的执行环境。 1359 1360- [in] js_object：ArkTS对象。 1361 1362- [in] native_object：将被包裹在ArkTS对象中的native实例。 1363 1364- [in] napi_finalize：[可选]ArkTS对象被销毁时调用的回调函数。 1365 1366- [in] finalize_hint：[可选]上下文提示，会传递给回调函数。 1367 1368- [in] native_binding_size：[可选]绑定的native实例的大小。 1369 1370**返回：** 1371 1372如果API成功，则返回napi_ok。 1373 1374### napi_unwrap_sendable 1375 1376```cpp 1377napi_status napi_unwrap_sendable(napi_env env, napi_value js_object, void** result) 1378``` 1379 1380**描述：** 1381 1382获取ArkTS对象包装的native实例。 1383 1384**参数：** 1385 1386- [in] env: Node-API的环境对象，表示当前的执行环境。 1387 1388- [in] js_object：ArkTS对象。 1389 1390- [out] result：包裹在ArkTS对象中的native实例。 1391 1392**返回：** 1393 1394如果API成功，则返回napi_ok。 1395 1396### napi_remove_wrap_sendable 1397 1398```cpp 1399napi_status napi_remove_wrap_sendable(napi_env env, napi_value js_object, void** result) 1400``` 1401 1402**描述：** 1403 1404移除并获取ArkTS对象包装的native实例，移除后回调将不再触发，需手动delete释放内存。 1405 1406**参数：** 1407 1408- [in] env: Node-API的环境对象，表示当前的执行环境。 1409 1410- [in] js_object：ArkTS对象。 1411 1412- [out] result：包裹在ArkTS对象中的native实例。 1413 1414**返回：** 1415 1416如果API成功，则返回napi_ok。 1417 1418### napi_wrap_enhance 1419 1420```cpp 1421napi_status napi_wrap_enhance(napi_env env, 1422 napi_value js_object, 1423 void* native_object, 1424 napi_finalize finalize_cb, 1425 bool async_finalizer, 1426 void* finalize_hint, 1427 size_t native_binding_size, 1428 napi_ref* result); 1429``` 1430 1431**描述：** 1432 1433在ArkTS对象上绑定一个Node-API模块对象实例并指定实例大小，开发者可以指定绑定的回调函数是否异步执行，如果异步执行，则回调函数必须是线程安全的。 1434 1435**参数：** 1436 1437- [in] env：Node-API的环境对象，表示当前的执行环境。 1438 1439- [in] js_object：ArkTS对象。 1440 1441- [in] native_object：将被包裹在ArkTS对象中的native实例。 1442 1443- [in] finalize_cb：[可选]ArkTS对象被销毁时调用的回调函数，详情请参见[napi_finalize回调函数说明](#napi_finalize回调函数说明)。 1444 1445- [in] async_finalizer：一个布尔值，表示ArkTS对象被销毁时调用的回调函数是否异步执行。如果为true，表示异步执行，需确保线程安全；如果为false，则表示同步执行。 1446 1447- [in] finalize_hint：[可选]上下文提示，会传递给回调函数。 1448 1449- [in] native_binding_size：[可选]绑定的native实例的大小。 1450 1451- [out] result：[可选]接收ArkTS对象引用的指针。 1452 1453**返回：** 1454 1455- napi_ok：如果API成功，则返回napi_ok。 1456 1457- napi_invalid_arg：参数env、js_object或native_object为空时返回。 1458 1459- napi_object_expected：参数js_object不是ArkTs对象或函数时返回。 1460 1461- napi_pending_exception：如果有未捕获的异常或执行过程中发生异常时返回。 1462 1463### napi_create_ark_context 1464 1465```cpp 1466napi_status napi_create_ark_context(napi_env env, napi_env* newEnv); 1467``` 1468 1469**描述：** 1470 1471创建一个新的运行时上下文环境。 1472使用该接口需要注意以下几点： 14731. 只支持通过最初的上下文环境创建新的上下文环境，禁止通过该接口创建的上下文环境去创建新的上下文环境。 14742. 当前该接口不支持在非主线程的ArkTS线程中调用。 14753. 调用该接口前，调用者需要保证当前上下文环境不存在异常，否则会导致该接口调用失败。 14764. 该接口创建的上下文环境暂时只支持加载部分ArkUI的native so文件，对于加载应用自带的native so和加载公共基础库的native so暂时不支持。 14775. 多上下文运行时环境不支持sendable特性。 14786. 通过napi_create_ark_context接口创建的运行时上下文环境暂时不支持console、timer等模块能力。 1479 1480**参数：** 1481 1482- [in] env：Node-API的环境对象，表示当前的执行环境。 1483 1484- [out] newEnv：新创建的运行时上下文环境。 1485 1486**返回：** 1487 1488如果API成功，则返回napi_ok。 1489 1490### napi_switch_ark_context 1491 1492```cpp 1493napi_status napi_switch_ark_context(napi_env env) 1494``` 1495 1496**描述：** 1497 1498切换到指定的运行时上下文环境。使用该接口需要注意以下几点： 14991. 当前该接口不支持在非主线程的ArkTS线程中调用。 15002. 调用该接口前，调用者需要保证当前上下文环境不存在异常，否则会导致该接口调用失败。 1501 1502**参数：** 1503 1504- [in] env：指定的运行时上下文环境。 1505 1506**返回：** 1507 1508如果API成功，则返回napi_ok。 1509 1510### napi_destroy_ark_context 1511 1512```cpp 1513napi_status napi_destroy_ark_context(napi_env env) 1514``` 1515 1516**描述：** 1517 1518销毁通过接口napi_create_ark_context创建的一个上下文环境。使用该接口需要注意以下几点： 15191. 当前该接口不支持在非主线程的ArkTS线程中调用。 15202. 该接口只能销毁通过napi_create_ark_context接口创建的运行时上下文环境。 15213. 不能通过该接口去销毁正在运行的上下文环境。 1522 1523**参数：** 1524 1525- [in] env：要销毁的运行时上下文环境。 1526 1527**返回：** 1528 1529如果API成功，则返回napi_ok。 1530 1531### napi_finalize回调函数说明 1532 1533```cpp 1534typedef void (*napi_finalize)(napi_env env, 1535 void* finalize_data, 1536 void* finalize_hint); 1537``` 1538 1539**描述：** 1540 1541用于定义在Node-API对象生命周期结束时触发的回调函数。 1542 1543**参数：** 1544 1545- [in] env：Node-API的环境对象，表示当前的执行环境。 1546 1547- [in] finalize_data：指向需要清理的用户数据的指针。 1548 1549- [in] finalize_hint：上下文提示，用于辅助清理过程。 1550 1551**返回：** 1552 1553- void：此回调函数无返回值。 1554 1555<!--no_check-->