diff --git a/zh-cn/application-dev/napi/napi-data-types-interfaces.md b/zh-cn/application-dev/napi/napi-data-types-interfaces.md index d874da8ab0dd13151139fc5dd16cb90ebacad312..b3ab691ed170fb686d94e9c47dae5c778847d200 100644 --- a/zh-cn/application-dev/napi/napi-data-types-interfaces.md +++ b/zh-cn/application-dev/napi/napi-data-types-interfaces.md @@ -6,7 +6,7 @@ 是一个枚举数据类型，表示Node-API接口返回的状态信息。 -每当调用一个Node-API函数，都会返回该值，表示操作成功与否的相关信息。 +调用Node-API函数后，返回值表示操作成功与否。 ```c typedef enum { @@ -52,15 +52,15 @@ typedef struct { ### napi_value -napi_value是一个C的结构体指针，表示一个JavaScript对象的引用。napi_value持有了JS对象，同时，napi_value受handle_scope管理，scope中napi_value持有的JS对象不会被释放；出scope后，napi_value将失效，不再持有对应的JS对象。 +napi_value 是一个C语言的结构体指针，表示JavaScript对象的引用。napi_value持有JS对象，并受handle_scope管理。在scope中，napi_value持有的JS对象不会被释放。出scope后，napi_value将失效，不再持有对应的JS对象。 ### napi_env - 用于表示Node-API执行时的上下文，Native侧函数入参，并传递给函数中的Node-API接口。 -- napi_env与JS线程绑定，JS线程退出后，napi_env将失效。 +- napi_env与JS线程绑定，JS线程退出后，napi_env失效。 -- 禁止缓存napi_env，禁止在不同线程中传递napi_env。 +- 禁止缓存napi_env，也不要将其在不同Worker之间传递。 ### napi_threadsafe_function @@ -77,7 +77,7 @@ typedef enum { } napi_threadsafe_function_release_mode; ``` -该值会传给napi_release_threadsafe_function。 +该值会传递给napi_release_threadsafe_function。 ```cpp napi_release_threadsafe_function(napi_threadsafe_function func, @@ -87,13 +87,13 @@ napi_release_threadsafe_function(napi_threadsafe_function func, - mode值为napi_tsfn_release时：表示当前线程不再调用此tsfn。 - mode值为napi_tsfn_abort时：该tsfn关闭，不能再调用此tsfn。 - 如果设置为napi_tsfn_abort，利用napi_call_threadsafe_function接口调用此tsfn时将返回napi_closing，tsfn函数并不会被放入queue中。 + 设置为napi_tsfn_abort时，使用napi_call_threadsafe_function接口调用此tsfn将返回napi_closing，且tsfn函数不会被放入队列。 ### napi_threadsafe_function_call_mode 该枚举类型定义了两个常量，用于指定线程安全函数的调用模式。 -数据结构如下所示： +数据结构： ```c typedef enum { @@ -112,7 +112,7 @@ Node-API包含以下内存管理类型： **napi_handle_scope** -napi_handle_scope数据类型是用来管理JavaScript对象的生命周期的。它允许JavaScript对象在一定范围内保持活动状态，以便在JavaScript代码中使用。在创建napi_handle_scope时，所有在该范围内创建的JavaScript对象都会保持活动状态，直到结束。这样可以做到JavaScript对象生命周期最小化，[避免发生内存泄漏问题](napi-guidelines.md#生命周期管理)。同时，napi_handle_scope也可参考[生命周期类问题注意事项](../dfx/cppcrash-guidelines.md#案例4生命周期类问题)。 +napi_handle_scope数据类型用于管理JavaScript对象的生命周期。它允许JavaScript对象在一定范围内保持活动状态，以便在JavaScript代码中使用。在创建napi_handle_scope时，所有在该范围内创建的JavaScript对象都会保持活动状态，直到结束。这样可以做到JavaScript对象生命周期最小化，[避免发生内存泄漏问题](napi-guidelines.md#生命周期管理)。同时，napi_handle_scope也可参考[生命周期类问题注意事项](../dfx/cppcrash-guidelines.md#案例4生命周期类问题)。 **napi_escapable_handle_scope** @@ -120,7 +120,7 @@ napi_handle_scope数据类型是用来管理JavaScript对象的生命周期的 - 表示一种特殊类型的句柄范围，用于将在escapable_handle_scope范围内创建的值返回给父scope。 -- 用于napi_escape_handle接口，将escape_handle_scope提升到JS对象，以便在外部作用域使用。 +- 用于napi_escape_handle接口，将escape_handle_scope提升到JS对象。 **napi_ref** @@ -128,7 +128,7 @@ napi_handle_scope数据类型是用来管理JavaScript对象的生命周期的 **napi_type_tag** -该结构体定义了一个包含两个无符号64位整数的类型标签，用于标识一个Node-API值的类型信息。 +该结构体定义了一个包含两个无符号64位整数的类型标签，标识Node-API值的类型信息。 ```c typedef struct { @@ -137,15 +137,15 @@ typedef struct { } napi_type_tag; ``` -- 存储了两个无符号64位整数的128位值，用它来标记JavaScript对象，确保它们属于某种类型。 +- 该结构体定义了一个包含两个无符号64位整数的128位值的类型标签，用于标记JavaScript对象，确保它们属于某种类型。 -- 比napi_instanceof更强的类型检查，如果对象的原型被操纵，napi_instanceof可能会报告误报。 +- 比napi_instanceof更强的类型检查，对象原型被操纵时可能会报告误报。 -- type_tag与napi_wrap结合非常有用，因为它确保从包装对象检索的指针可以安全地转换为与先前应用于JavaScript对象的类型标记相对应的Native类型。 +- type_tag与napi_wrap结合非常有用，确保从包装对象检索的指针可以安全地转换为与先前应用于JavaScript对象的类型标记相对应的Native类型。 **napi_async_cleanup_hook_handle** -napi_async_cleanup_hook_handle用于注册异步操作的回调函数。它主要用于在异步操作完成或被取消时执行清理操作，例如释放资源或撤销操作。使用napi_async_cleanup_hook_handle可以确保在异步操作完成或被取消时，相关资源得到正确的释放和清理，从而避免内存泄漏等问题。 +napi_async_cleanup_hook_handle用于注册异步操作的回调函数。主要在异步操作完成或被取消时执行清理操作，如释放资源或撤销操作。使用napi_async_cleanup_hook_handle可以确保相关资源在异步操作完成或被取消时正确释放和清理，避免内存泄漏。 ### 回调类型 @@ -153,11 +153,11 @@ Node-API包含以下回调类型： **napi_callback_info** -Native侧获取JS侧参数信息，传递给napi_get_cb_info，用于获取JS侧入参信息。 +Native侧获取JS侧参数信息并传递给napi_get_cb_info，以获取JS侧入参信息。 **napi_callback** -表示用户定义的Native函数，暴露给JavaScript，即JS侧调用的接口；一般不在此callback中创建handle或者callback scope。 +用户定义的Native函数暴露给JavaScript，即JS侧调用的接口；通常不在该回调中创建handle或callback scope。 基本用法如下： @@ -167,7 +167,7 @@ typedef napi_value (*napi_callback)(napi_env, napi_callback_info); **napi_finalize** -函数指针，用于传入napi_create_threadsafe_function和napi_set_instance_data等接口。napi_finalize在对象被回收时会被调用。 +函数指针用于传入napi_create_threadsafe_function和napi_set_instance_data接口。napi_finalize在对象被回收时调用。 **napi_async_execute_callback** @@ -181,19 +181,19 @@ typedef napi_value (*napi_callback)(napi_env, napi_callback_info); **napi_async_complete_callback** -napi_async_complete_callback用于异步操作完成后的回调。当需要进行异步操作时，可以使用napi_create_async_work函数创建一个异步操作任务，并指定一个napi_async_complete_callback回调函数，在异步操作完成后会自动调用该回调函数，以便进行后续的处理。该回调函数的参数包括当前异步操作任务的状态和返回值等信息，可以根据这些信息进行相应的处理。 +napi_async_complete_callback用于异步操作完成后的回调。需要进行异步操作时，使用napi_create_async_work创建异步任务，并指定napi_async_complete_callback回调函数，异步操作完成后，该回调函数会自动调用，处理任务状态和返回值等信息。 **napi_threadsafe_function_call_js** -函数指针，在主线程中与独立线程中的JavaScript代码进行交互，从而实现更加复杂的功能，用于napi_create_threadsafe_function(napi_env env,…,napi_threadsafe_function_call_js call_js_cb,...)接口。 +函数指针用于在主线程中与独立线程中的JavaScript代码进行交互，以实现更加复杂的功能，用于napi_create_threadsafe_function(napi_env env,…,napi_threadsafe_function_call_js call_js_cb,...)接口。 **napi_cleanup_hook** -函数指针，用于napi_add_env_cleanup_hook接口，当环境销毁时会被执行。 +函数指针用于napi_add_env_cleanup_hook接口，在环境销毁时执行。 **napi_async_cleanup_hook** -函数指针，用于napi_add_async_cleanup_hook接口，当环境销毁时会被执行。 +函数指针用于napi_add_async_cleanup_hook接口，在环境销毁时执行。 ### 调度优先级 @@ -201,10 +201,10 @@ QoS决定了线程调度的优先级，等级定义如下： ```c typedef enum { - napi_qos_background = 0, - napi_qos_utility = 1, - napi_qos_default = 2, - napi_qos_user_initiated = 3, + napi_qos_background = 0, + napi_qos_utility = 1, + napi_qos_default = 2, + napi_qos_user_initiated = 3, } napi_qos_t; ``` @@ -217,7 +217,7 @@ typedef enum { ### 事件循环模式 -napi提供了运行底层事件循环的两种模式, 其定义如下： +napi提供了两种模式来运行底层事件循环，其定义如下： ```c typedef enum { @@ -233,7 +233,7 @@ typedef enum { ### 线程安全任务优先级 -napi提供了线程安全任务的优先级, 底层任务队列中的任务会根据其优先级被依次执行, 优先级的定义如下： +napi提供了线程安全任务的优先级。底层任务队列中的任务会根据其优先级被依次执行，优先级的定义如下： ```c typedef enum { @@ -246,14 +246,14 @@ typedef enum { | 任务优先级 | 解释说明 | | -------- | -------- | -| napi_priority_immediate | 该优先级的级别最高。| -| napi_priority_high | 该优先级的级别低于napi_priority_immediate。| -| napi_priority_low | 该优先级的级别低于napi_priority_immediate和napi_priority_high。| -| napi_priority_idle | 该优先级的级别最低。 | +| napi_priority_immediate | 优先级最高。| +| napi_priority_high | 优先级低于napi_priority_immediate。| +| napi_priority_low | 优先级低于napi_priority_immediate和napi_priority_high。| +| napi_priority_idle | 优先级最低。 | ## 支持的Node-API接口 -Node-API接口在Node.js提供的原生模块基础上扩展，目前支持部分接口，具体可见下文。 +Node-API接口在Node.js原生模块基础上进行了扩展，目前支持部分接口，具体见下文。 ### 异步安全线程相关 @@ -271,9 +271,9 @@ Node-API接口在Node.js提供的原生模块基础上扩展，目前支持部 | 接口 | 功能说明 | | -------- | -------- | -| napi_create_buffer | 创建并获取一个指定大小的JS Buffer。 | -| napi_create_buffer_copy | 创建并获取一个指定大小的JS Buffer，并以给定数据进行初始化。 | -| napi_create_external_buffer | 创建并获取一个指定大小的JS Buffer，并以给定数据进行初始化，该接口可为Buffer附带额外数据。 | +| napi_create_buffer | 创建并获取指定大小的JS Buffer。 | +| napi_create_buffer_copy | 创建并获取指定大小的JS Buffer，并以给定数据进行初始化。 | +| napi_create_external_buffer | 创建并获取指定大小的JS Buffer，并以给定数据进行初始化，该接口可为Buffer附带额外数据。 | | napi_get_buffer_info | 获取JS Buffer底层data及其长度。 | | napi_is_buffer | 判断给定JS value是否为Buffer对象。 | | napi_create_external_arraybuffer | 分配一个附加有外部数据的JS ArrayBuffer。 | @@ -282,18 +282,18 @@ Node-API接口在Node.js提供的原生模块基础上扩展，目前支持部 | 接口 | 功能说明 | | -------- | -------- | -| napi_create_string_utf16 | 通过UTF16编码的C字符串数据创建JS String。 | -| napi_get_value_string_utf16 | 获取给定JS vaule对应的UTF16编码的字符串。 | -| napi_create_string_latin1 | 通过ISO-8859-1编码的C字符串数据创建JS String。 | -| napi_create_string_utf8 | 通过UTF8编码的C字符串数据创建JS String。 | -| napi_get_value_string_latin1 | 获取给定JS vaule对应的ISO-8859-1编码的字符串。 | -| napi_get_value_string_utf8 | 获取给定JS vaule对应的UTF8编码的字符串。 | +| napi_create_string_utf16 | 通过UTF16编码的C字符串创建JS String。 | +| napi_get_value_string_utf16 | 获取给定JS value对应的UTF16编码的字符串。 | +| napi_create_string_latin1 | 通过ISO-8859-1编码的C字符串创建JS String。 | +| napi_create_string_utf8 | 通过UTF8编码的C字符串创建JS String。 | +| napi_get_value_string_latin1 | 获取给定JS value对应的ISO-8859-1编码的字符串。 | +| napi_get_value_string_utf8 | 获取给定JS value对应的UTF8编码的字符串。 | ### date相关 | 接口 | 功能说明 | | -------- | -------- | -| napi_create_date | 通过一个C的double数据创建JS Date。 | +| napi_create_date | 通过C的double数据创建JS Date。 | | napi_get_date_value | 获取给定JS Date对应的C double值。 | | napi_is_date | 判断给定JS value是否为JS Date对象。 | @@ -311,7 +311,7 @@ Node-API接口在Node.js提供的原生模块基础上扩展，目前支持部 | 接口 | 功能说明 | | -------- | -------- | -| napi_module_register | native模块注册接口。 | +| napi_module_register | 注册native模块。 | ### 生命周期相关 @@ -394,8 +394,8 @@ Node-API接口在Node.js提供的原生模块基础上扩展，目前支持部 | napi_type_tag_object | 将tag指针的值与Object关联。 | | napi_check_object_type_tag | 判断给定的tag指针是否被关联到了JS Object上。 | | napi_create_symbol | 创建一个JS Symbol对象。 | -| napi_create_external | 用于创建一个JS外部对象，该对象可以用于将C/C++中的自定义数据结构或对象传递到JS中，并且可以在JS中访问其属性和方法。 | -| napi_get_value_external | 用于获得napi_create_external创建的绑定了外部数据的JS值，此函数可以在JS和C/C++之间传递数据。 | +| napi_create_external | 用于创建一个JS外部对象，该对象可以用于将C/C++中的自定义数据结构或对象传递到JavaScript值中，并且可以在JavaScript值中访问其属性和方法。 | +| napi_get_value_external | 用于获得napi_create_external创建的绑定了外部数据的JavaScript值，此函数可以在JS和C/C++之间传递数据。 | ### 基本数据类型相关 @@ -500,9 +500,9 @@ Node-API接口在Node.js提供的原生模块基础上扩展，目前支持部 | 接口 | 功能说明 | | -------- | -------- | | napi_add_env_cleanup_hook | 注册环境清理钩子函数。 | -| napi_remove_env_cleanup_hook | 取消环境清理钩子函数。| +| napi_remove_env_cleanup_hook | 移除环境清理钩子函数。| | napi_add_async_cleanup_hook | 注册清理异步钩子函数。 | -| napi_remove_async_cleanup_hook | 取消清理异步钩子函数。| +| napi_remove_async_cleanup_hook | 移除清理异步钩子函数。| ### 扩展能力 @@ -535,8 +535,8 @@ Node-API接口在Node.js提供的原生模块基础上扩展，目前支持部 | napi_wrap_sendable | 包裹一个native实例到ArkTS对象中。| | napi_wrap_sendable_with_size | 包裹一个native实例到ArkTS对象中并指定大小。| | napi_unwrap_sendable | 获取ArkTS对象包裹的native实例。| -| napi_remove_wrap_sendable | 移除并获取ArkTS对象包裹的native实例，移除后回调将不再触发，需手动delete释放内存。| -| napi_wrap_enhance | 在ArkTS对象上绑定一个Node-API模块对象实例并指定实例大小，开发者可以指定绑定的回调函数是否异步执行，如果异步执行，则回调函数必须是线程安全的。 | +| napi_remove_wrap_sendable | 移除并获取ArkTS对象包裹的native实例。| +| napi_wrap_enhance | 在ArkTS对象上绑定一个Node-API模块对象实例并指定实例大小，可以指定回调函数是否异步执行。若异步执行，回调函数必须是线程安全的。| |napi_create_ark_context| 创建一个新的上下文环境。| |napi_destroy_ark_context| 销毁通过napi_create_ark_context创建的上下文环境。| @@ -548,7 +548,7 @@ napi_status napi_queue_async_work_with_qos(napi_env env, napi_qos_t qos); ``` -用法同napi_queue_async_work，但可以指定QoS等级。napi_queue_async_work_with_qos使用方法可参考指定异步任务调度优先级。QoS详细介绍可参考[QoS 开发指导](qos-guidelines.md)。 +用法同napi_queue_async_work，但可以指定QoS等级。napi_queue_async_work_with_qos使用方法可参考指定异步任务调度优先级。QoS详细介绍可参考[QoS 开发指导](qos-guidelines.md) #### napi_run_script_path @@ -601,7 +601,7 @@ napi_status napi_coerce_to_native_binding_object(napi_env env, ```c napi_status napi_create_ark_runtime(napi_env *env); ``` -[使用napi_create_ark_runtime、napi_destroy_ark_runtime接口创建ArkTS运行时环境](use-napi-ark-runtime.md)。 +[使用napi_create_ark_runtime、napi_destroy_ark_runtime接口创建ArkTS运行时环境](use-napi-ark-runtime.md) #### napi_destroy_ark_runtime @@ -615,7 +615,7 @@ napi_status napi_destroy_ark_runtime(napi_env *env); napi_status napi_run_event_loop(napi_env env, napi_event_mode mode); ``` -开发者只能在自己通过napi_create_ark_runtime创建的ArkTS运行环境中调用napi_run_event_loop与napi_stop_event_loop接口，使用方法可参考[使用扩展的Node-API接口在异步线程中运行和停止事件循环](use-napi-event-loop.md)。 +只能在通过napi_create_ark_runtime创建的ArkTS运行环境中调用napi_run_event_loop与napi_stop_event_loop接口。使用方法可参考[使用扩展的Node-API接口在异步线程中运行和停止事件循环](use-napi-event-loop.md)。 #### napi_stop_event_loop diff --git a/zh-cn/application-dev/napi/napi-guidelines.md b/zh-cn/application-dev/napi/napi-guidelines.md index 67eb498b93b4c138a1d43aeec4bc18a222fbe96a..4eff395cbdedb8e084d5fd214a8d25a28a85a88e 100644 --- a/zh-cn/application-dev/napi/napi-guidelines.md +++ b/zh-cn/application-dev/napi/napi-guidelines.md @@ -85,7 +85,7 @@ for (int i = 0; i < 100000; i++) { **【规则】** 多引擎实例场景下，禁止通过Node-API跨引擎实例访问JS对象。 -引擎实例是一个独立运行环境，JS对象创建访问等操作必须在同一个引擎实例中进行。若在不同引擎实例中操作同一个对象，可能会引发程序崩溃。引擎实例在接口中体现为napi_env。 +引擎实例是一个独立运行环境，JS对象的创建和访问必须在同一个引擎实例中进行。不同引擎实例操作同一对象可能会引发程序崩溃。引擎实例在接口中体现为napi_env。 **错误示例**： @@ -106,7 +106,7 @@ if (status != napi_ok) { } ``` -所有的JS对象都隶属于具体的某一napi_env，不可将env1的对象，设置到env2中的对象中。在env2中一旦访问到env1的对象，程序可能会发生崩溃。 +所有JS对象都隶属于特定的napi_env。不可将env1中的对象设置到env2中的对象中，否则在env2中访问env1的对象时，可能会导致程序崩溃。 ## 异常处理 @@ -135,7 +135,7 @@ if (status != napi_ok) { } ``` -如上示例中，步骤1或者步骤2出现异常时，步骤3都不会正常进行。只有当方法的返回值是napi_ok时，才能保持继续正常运行；否则后续流程可能会出现不可预期的行为。 +如上示例中，步骤1或步骤2出现异常时，步骤3不会正常进行。只有当方法的返回值是napi_ok时，才能继续正常运行；否则后续流程可能出现不可预期的行为。 ## 异步任务 @@ -150,7 +150,7 @@ if (status != napi_ok) { **正确示例**： ```cpp -void CallbackTest(CallbackContext* context) +void callbackTest(CallbackContext* context) { uv_loop_s* loop = nullptr; napi_get_uv_event_loop(context->env, &loop); @@ -195,7 +195,7 @@ void CallbackTest(CallbackContext* context) **【规则】** 使用napi_wrap接口，如果最后一个参数result传递不为nullptr，需要开发者在合适的时机调用napi_remove_wrap函数主动删除创建的napi_ref。 -napi_wrap接口定义如下： +napi_wrap接口定义如下所示： ```cpp napi_wrap(napi_env env, napi_value js_object, void* native_object, napi_finalize finalize_cb, void* finalize_hint, napi_ref* result) @@ -223,7 +223,7 @@ napi_remove_wrap(env, jsobject, &nativeObjectResult); **【建议】** 存储值类型数据时，使用ArrayBuffer代替JSArray来提高应用性能。 -使用JSArray作为容器储存数据，支持几乎所有的JS数据类型。 +使用JSArray作为容器存储数据，支持几乎所有的JS数据类型。 使用napi_set_element方法对JSArray存储值类型数据（如int32）时，同样会涉及到与运行时的交互，造成不必要的开销。 @@ -281,7 +281,7 @@ napi_create_arraybuffer等同于JS代码中的`new ArrayBuffer(size)`，其生 > **说明：** > -> 以下数据为千次循环写入累计数据，为更好的体现出差异，已对设备核心频率进行限制。 +> 以下数据为千次循环写入累计数据，为更清晰地体现出差异，已对设备的核心频率进行了限制。 | 容器类型 | Benchmark数据（us） | | ----------- | ------------------- | @@ -290,20 +290,20 @@ napi_create_arraybuffer等同于JS代码中的`new ArrayBuffer(size)`，其生 ## 数据转换 -**【建议】** 尽可能的减少数据转换次数，避免不必要的复制。 +**【建议】** 减少数据转换次数，避免不必要的复制。 -- **减少数据转换次数：** 频繁的数据转换可能会导致性能下降，可以通过批量处理数据或者使用更高效的数据结构来优化性能。 +- **减少数据转换次数：** 频繁的数据转换可能导致性能下降，可通过批量处理数据或者使用更高效的数据结构来优化。 - **避免不必要的数据复制：** 在进行数据转换时，可以使用Node-API提供的接口来直接访问原始数据，而不是创建新的副本。 -- **使用缓存：** 如果某些数据在多次转换中都会被使用到，可以考虑使用缓存来避免重复的数据转换。缓存可以减少不必要的计算，提高性能。 +- **使用缓存：** 若数据在多次转换中重复使用，考虑使用缓存以减少计算，提升性能。 ## 模块注册与模块命名 **【规则】** -nm_register_func对应的函数需要加上修饰符static，防止与其他so里的符号冲突。 +nm_register_func对应的函数需添加static修饰符，以防止与其他so中的符号冲突。 -模块注册的入口，即使用__attribute__((constructor))修饰函数的函数名需要确保与其他模块不同。 +模块注册的入口函数，即使用__attribute__((constructor))修饰的函数名，需确保与其他模块不同。 -模块实现中.nm_modname字段需要与模块名完全匹配，区分大小写。 +模块实现中.nm_modname字段需与模块名完全匹配，区分大小写。 **错误示例** 以下代码为模块名为nativerender时的错误示例 @@ -400,7 +400,7 @@ extern "C" void napi_onLoad() ## 正确的使用napi_create_external系列接口创建的JS Object -**【规则】** napi_create_external系列接口创建出来的JS对象仅允许在当前线程传递和使用，跨线程传递（如使用worker的post_message）将会导致应用crash。若需跨线程传递绑定有Native对象的JS对象，请使用napi_coerce_to_native_binding_object接口绑定JS对象和Native对象。 +**【规则】** napi_create_external系列接口创建的JS对象仅限当前线程传递和使用，跨线程传递（如使用worker的post_message）将导致应用crash。若需跨线程传递绑定有Native对象的JS对象，请使用napi_coerce_to_native_binding_object接口绑定JS对象和Native对象。 **错误示例** @@ -441,9 +441,9 @@ mWorker.terminate(); ## 防止重复释放获取的buffer -**【规则】** 使用napi_get_arraybuffer_info等接口，参数data资源开发者不允许释放，data的生命周期受引擎管理。 +**【规则】** 使用napi_get_arraybuffer_info等接口时，参数data资源不允许释放，其生命周期由引擎管理。 -这里以napi_get_arraybuffer_info为例，该接口定义如下： +以napi_get_arraybuffer_info为例，该接口定义如下： ```cpp napi_get_arraybuffer_info(napi_env env, napi_value arraybuffer, void** data, size_t* byte_length) @@ -477,9 +477,9 @@ delete arrayBufferPtr; // 这一步是禁止的，创建的arrayBufferPtr生命 **【建议】** 合理使用napi_object_freeze和napi_object_seal来控制对象以及对象属性的可变性。 -napi_object_freeze等同于Object.freeze语义，freeze后对象的所有属性都不可能以任何方式被修改；napi_object_seal等同于Object.seal语义，对象不可增删属性。两者的主要区别是，freeze不能改属性的值，seal还可以改属性的值。 +napi_object_freeze等同于Object.freeze语义，freeze后对象的所有属性都无法以任何方式被修改；napi_object_seal等同于Object.seal语义，对象不可增删属性。两者的主要区别是，freeze不能改属性的值，seal还可以改属性的值。 -开发者使用以上语义时，需确保约束条件是自己需要的，一旦违背以上语义严格模式下就会抛出Error（默认严格模式）。 +使用以上语义时，需确保约束条件符合需求，一旦违背这些语义，在严格模式下（默认启用）会抛出错误。 ## 参考文档 diff --git a/zh-cn/application-dev/napi/napi-introduction.md b/zh-cn/application-dev/napi/napi-introduction.md index 9b24302922d0e90092afebd363ecc227db5accc1..33bd97b956579a4ae26e688c9c716ec3f7698cca 100644 --- a/zh-cn/application-dev/napi/napi-introduction.md +++ b/zh-cn/application-dev/napi/napi-introduction.md @@ -10,11 +10,11 @@ OpenHarmony Node-API是基于Node.js 12.x LTS的[Node-API](https://nodejs.org/do > > OpenHarmony Node-API与Node.js 12.x LTS的Node-API规范的接口异同点，详见[Node-API参考](../reference/native-lib/napi.md) -一般情况下OpenHarmony应用开发使用ArkTS/JS语言，但部分场景由于性能、效率等要求，比如游戏、物理模拟等，需要依赖使用现有的C/C++库。Node-API规范封装了I/O、CPU密集型、OS底层等能力并对外暴露ArkTS/JS接口，从而实现ArkTS/JS和C/C++的交互。主要场景如下： +OpenHarmony应用开发通常使用ArkTS/JS语言，但在性能和效率要求较高的场景下，如游戏和物理模拟，需要使用现有的C/C++库。Node-API规范封装了I/O、CPU密集型和OS底层等能力，并对外提供ArkTS/JS接口，实现ArkTS/JS与C/C++的交互。主要场景包括： -- 系统可以将框架层丰富的模块功能通过ArkTS/JS接口开放给上层应用。 +- 系统通过ArkTS/JS接口将框架层的丰富模块功能开放给上层应用。 -- 应用开发者也可以选择将一些对性能、底层系统调用有要求的核心功能用C/C++封装实现，再通过ArkTS/JS接口使用，提高应用本身的执行效率。 +- 应用开发者可以选择将核心功能用C/C++封装实现，再通过ArkTS/JS接口调用，提高执行效率。 ## Node-API的组成架构 @@ -24,15 +24,15 @@ OpenHarmony Node-API是基于Node.js 12.x LTS的[Node-API](https://nodejs.org/do - Native Module：开发者使用Node-API开发的模块，用于在ArkTS侧导入使用。 -- Node-API：实现ArkTS与C/C++交互的逻辑。 +- Node-API：实现ArkTS与C/C++的交互。 -- ModuleManager：Native模块管理，包括加载、查找等。 +- ModuleManager：管理Native模块，包括加载和查找等。 - ScopeManager：管理napi_value的生命周期。 - ReferenceManager：管理napi_ref的生命周期。 -- NativeEngine：ArkTS引擎抽象层，统一ArkTS引擎在Node-API层的接口行为。 +- NativeEngine：ArkTS引擎的抽象层，统一ArkTS引擎在Node-API层的接口行为。 - ArkCompiler ArkTS Runtime：ArkTS运行时。 diff --git a/zh-cn/application-dev/napi/use-napi-about-array.md b/zh-cn/application-dev/napi/use-napi-about-array.md index b5726fdd0d67315f9aa0f23f0d4da9dd9cd7f545..cc1eaca1781641ab51ad93d5f639bd4479c7dc6e 100644 --- a/zh-cn/application-dev/napi/use-napi-about-array.md +++ b/zh-cn/application-dev/napi/use-napi-about-array.md @@ -2,11 +2,11 @@ ## 简介 -使用Node-API接口进行array相关开发时，调用相关接口可以在Node-API模块中直接操作和处理ArkTS中的数组。 +使用Node-API接口进行array相关开发时，可以直接在Node-API模块中调用相关接口，操作和处理ArkTS中的数组。 ## 基本概念 -使用Node-API接口进行数组（array）相关开发时，涉及的基本概念主要包括数组的创建、访问、修改、遍历以及与数组相关的操作。这些概念对于理解如何在Node-API模块中与ArkTS数组交互非常重要。以下是一些关键概念： +使用Node-API接口进行数组（array）相关开发时，涉及的概念包括数组的创建、访问、修改、遍历以及与数组相关的操作。这些概念对于理解如何在Node-API模块中与ArkTS数组交互非常重要。以下是一些关键概念： - **数组的创建**：在Node-API模块中需要创建一个新的ArkTS数组，可以使用napi_create_array接口创建数组，将数组传递给ArkTS层。 - **数组相关操作**：在Node-API模块中通过对应的接口获取ArkTS数组的长度、检索指定索引处的元素以及设置指定索引处的元素值，从而实现Node-API模块与ArkTS数组的交互。 @@ -16,23 +16,23 @@ ## 场景和功能介绍 -使用Node-API接口进行数组相关开发时，可以处理各种涉及ArkTS数组的操作和交互场景。以下是几个具体的使用场景介绍： +使用Node-API接口进行数组开发时，可以处理各种涉及ArkTS数组的操作和交互。以下是几个具体的使用场景： | 接口 | 描述 | | -------- | -------- | -| napi_create_array | 用于在Node-API模块中向ArkTS层创建一个ArkTS数组对象。 | -| napi_create_array_with_length | 用于在Node-API模块中向ArkTS层创建指定长度的ArkTS数组时。 | -| napi_get_array_length | 用于在Node-API模块中获取ArkTS数组对象的长度。 | -| napi_is_array | 用于在Node-API模块中判断一个napi_value值是否为数组。 | -| napi_set_element | 用于在Node-API模块中对ArkTS数组对象的特定索引处设置一个值。 | -| napi_get_element | 用于在Node-API模块中从ArkTS数组对象的特定索引处获取一个值。 | -| napi_has_element | 用于在Node-API模块中判断ArkTS数组对象请求索引处是否包含元素。 | -| napi_delete_element | 用于在Node-API模块中从ArkTS数组对象中删除请求索引对应的元素。 | -| napi_create_typedarray | 用于在Node-API模块中创建指定类型的TypedArray，例如Uint8Array、Int32Array等，通常用于将Node-API模块中的数据转换为ArkTS中的TypedArray，以便进行高性能的数据处理操作。 | -| napi_is_typedarray | 用于在Node-API模块中判断一个给定的napi_value是否为TypedArray对象。 | -| napi_get_typedarray_info | 用于在Node-API模块中获得某个TypedArray的各种属性。 | -| napi_create_dataview | 用于在Node-API模块中创建一个DataView对象，可以访问和操作二进制数据。 | -| napi_is_dataview | 用于在Node-API模块中判断给定的napi_value是否为ArkTS中的DataView对象。 | -| napi_get_dataview_info | 用于在Node-API模块中获得某个DataView的各种属性。 | +| napi_create_array | 在Node-API模块中创建一个ArkTS数组对象。 | +| napi_create_array_with_length | 在Node-API模块中创建指定长度的ArkTS数组。 | +| napi_get_array_length | 在Node-API模块中获取ArkTS数组对象的长度。 | +| napi_is_array | 在Node-API模块中判断一个napi_value值是否为数组对象。 | +| napi_set_element | 在Node-API模块中对ArkTS数组对象的特定索引处设置一个值。 | +| napi_get_element | 在Node-API模块中从ArkTS数组对象的特定索引处获取一个值。 | +| napi_has_element | 在Node-API模块中判断ArkTS数组对象请求索引处是否包含元素。 | +| napi_delete_element | 在Node-API模块中从ArkTS数组对象中删除请求索引对应的元素。 | +| napi_create_typedarray | 在Node-API模块中创建指定类型的TypedArray，例如Uint8Array、Int32Array等，通常用于将Node-API模块中的数据转换为ArkTS中的TypedArray，以便进行高性能的数据处理操作。 | +| napi_is_typedarray | 在Node-API模块中判断一个给定的napi_value值是否为TypedArray对象。 | +| napi_get_typedarray_info | 在Node-API模块中获得某个TypedArray的各种属性。 | +| napi_create_dataview | 在Node-API模块中创建一个DataView对象，用来访问和操作二进制数据。 | +| napi_is_dataview | 在Node-API模块中判断一个给定的napi_value值是否为DataView对象。 | +| napi_get_dataview_info | 在Node-API模块中获得某个DataView的各种属性。 | ## 使用示例 @@ -40,7 +40,7 @@ Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程 ### napi_create_array -用于在Node-API模块中创建一个ArkTS数组。 +在Node-API模块中创建指定长度的ArkTS数组。 cpp部分代码 @@ -83,7 +83,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_array:%{public}s', JSON ### napi_create_array_with_length -用于在Node-API模块中创建一个具有指定长度的ArkTS数组。 +用于在Node-API模块中创建指定长度的ArkTS数组。 cpp部分代码 @@ -126,7 +126,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_array_with_length:%{pub ### napi_get_array_length -获取给定array的长度。 +获取数组的长度。 cpp部分代码 @@ -174,7 +174,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API get_array_length:%{public}d', testN ### napi_is_array -判断给定ArkTS值是否为数组。 +判断给定的napi_value值是否为数组。 cpp部分代码 @@ -227,8 +227,8 @@ try { ### napi_set_element -用于在ArkTS数组中设置指定索引位置的元素。 -对于以索引值为键的object，可以使用napi_set_element来设置属性值。 +在ArkTS数组中设置指定索引位置的元素。 +对于以索引值为键的object，使用napi_set_element来设置属性值。 cpp部分代码 @@ -291,7 +291,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_set_element arr[4]: %{public}s ### napi_get_element -用于从ArkTS数组中获取请求索引位置的元素值。请求索引值应在数组的有效范围内，如果索引超出数组长度，函数会返回undefined。 +从ArkTS数组中获取指定索引位置的元素值。请求索引值必须在数组的有效范围内，超出范围则返回undefined。 cpp部分代码 @@ -347,7 +347,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_element arr[null]: %{publi ### napi_has_element -用于判断ArkTS数组是否具有指定索引的元素。如果索引超出了对象的有效范围，函数返回false，表示没有元素。 +判断ArkTS数组对象的指定索引处是否包含元素。如果索引超出了对象的有效范围，函数返回false，表示没有元素。 cpp部分代码 @@ -393,7 +393,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_has_element arr[7]: %{public}s ### napi_delete_element -用于从ArkTS数组对象中删除请求索引的元素。 +从ArkTS数组对象中删除请求索引处的元素。 cpp部分代码 @@ -442,7 +442,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_element arr[0]: %{public}d ### napi_create_typedarray -用于在Node-API模块中通过现有的ArrayBuffer创建指定类型的ArkTS TypedArray。 +用于在Node-API模块中，通过现有的ArrayBuffer创建指定类型的TypedArray。 cpp部分代码 @@ -574,7 +574,7 @@ EXTERN_C_END ### napi_is_typedarray -用于在Node-API模块中判断ArkTS侧给定的napi_value是否为TypedArray对象。 +用于在Node-API模块中，判断一个给定的napi_value值是否为TypedArray对象。 cpp部分代码 @@ -627,7 +627,7 @@ try { ### napi_get_typedarray_info -获取给定TypedArray的各种属性。 +获取TypedArray的各种属性。 cpp部分代码 @@ -717,7 +717,7 @@ hilog.info(0x0000, 'Node-API', 'get_typedarray_info_byte_offset: %{public}d', te ### napi_create_dataview -创建dataview对象，便于访问和操作二进制数据，需要提供一个指向二进制数据的缓冲区，并指定要包含的字节数。 +创建DataView对象，用于访问和操作二进制数据，需提供缓冲区并指定字节数。 cpp部分代码 @@ -779,7 +779,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API dataView第一个数据：%{public} ### napi_is_dataview -用于在Node-API模块中判断ArkTS侧给定的napi_value是否为DataView。 +用于在Node-API模块中，判断一个给定的napi_value值是否为DataView。 cpp部分代码 @@ -834,7 +834,7 @@ try { ### napi_get_dataview_info -获取给定DataView的各种属性。 +获取DataView的各种属性。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-about-bigint.md b/zh-cn/application-dev/napi/use-napi-about-bigint.md index 5cefa0527e4c468e0ee03e905a25913d193b5e9b..8279de3098f50ba2a37327b359b4f919421e53ba 100644 --- a/zh-cn/application-dev/napi/use-napi-about-bigint.md +++ b/zh-cn/application-dev/napi/use-napi-about-bigint.md @@ -2,15 +2,15 @@ ## 简介 -BigInt是ArkTS中用于表示任意精度整数的数据类型，它能够处理比Number类型更大范围的整数值。通过Node-API提供的接口，可以在Node-API模块中创建、获取和操作BigInt类型值，从而实现与BigInt相关的功能扩展。 +BigInt是ArkTS中用于表示任意精度整数的数据类型，它能够处理比Number类型更大范围的整数值。Node-API提供接口用于创建、获取和操作BigInt类型值，从而实现与BigInt相关的功能扩展。 ## 基本概念 在使用Node-API接口操作BigInt类型值时，需要理解以下基本概念： -- **BigInt类型：** BigInt是ArkTS中的一种数据类型，用于表示任意精度的整数。与Number类型不同，BigInt类型可以精确表示非常大的整数，而不会丢失精度或溢出。 +- **BigInt类型：** BigInt是ArkTS中用于表示任意精度整数的数据类型。与Number类型不同，BigInt类型可以精确表示非常大的整数，而不会丢失精度或溢出。 - **BigInt创建：** 使用Node-API提供的接口，可以通过传递C的int64或uint64数据来创建对应的ArkTS BigInt。这使得在Node-API模块中可以方便地创建BigInt类型值。 -- **BigInt操作：** Node-API提供了多个接口用于操作BigInt类型值。通过这些接口，可以获取BigInt的数值，进行数值转换，以及执行常见的算术和位运算操作。 +- **BigInt操作：** Node-API提供了多个接口用于操作BigInt类型值。这些接口可以获取BigInt的数值，进行数值转换，执行算术和位运算操作。 ## 场景和功能介绍 @@ -26,11 +26,11 @@ BigInt是ArkTS中用于表示任意精度整数的数据类型，它能够处理 ## 使用示例 -Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 +Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅展示接口对应的C++及ArkTS相关代码。 ### napi_create_bigint_int64 -这个函数用于在给定的Node-API环境中依据一个带有符号的64位整数创建一个ArkTS的BigInt对象。 +这个函数在给定的Node-API环境中，根据一个带符号的64位整数创建一个ArkTS的BigInt对象。 cpp部分代码 @@ -66,7 +66,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_bigint_int64: %{public} ### napi_create_bigint_uint64 -这个函数用于在给定的Node-API环境中依据一个无符号的64位整数创建一个ArkTS的BigInt对象。 +这个函数在给定的Node-API环境中，根据无符号64位整数创建ArkTS的BigInt对象。 cpp部分代码 @@ -102,7 +102,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_bigint_uint64: %{public ### napi_create_bigint_words -这个函数用于在给定的Node-API环境中由一系列无符号64位整数创建一个ArkTS的BigInt对象。 +这个函数在Node-API环境中使用一系列无符号64位整数创建一个ArkTS的BigInt对象。 cpp部分代码 @@ -146,7 +146,7 @@ try { ### napi_get_value_bigint_int64 -用于从传入的参数中提取64位整数的BigInt数据，以供后续处理。 +从传入的参数中获取64位整数的BigInt数据，供后续处理。 cpp部分代码 @@ -197,7 +197,7 @@ try { ### napi_get_value_bigint_uint64 -用于从传入的参数中提取无符号64位整数的BigInt数据，以供后续处理。 +从传入的参数中获取无符号64位整数的BigInt数据，供后续处理。 cpp部分代码 @@ -248,7 +248,7 @@ try { ### napi_get_value_bigint_words -用于获取ArkTS的BigInt对象底层的64位无符号（uint64）二进制字节数据。 +获取ArkTS的BigInt对象底层的64位无符号字节数据。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-about-buffer.md b/zh-cn/application-dev/napi/use-napi-about-buffer.md index 3769f8cb246fbf60e0484b27b33d7505f78077a3..37de516b42e75fd96ff8e5d4827bb3743183bbac 100644 --- a/zh-cn/application-dev/napi/use-napi-about-buffer.md +++ b/zh-cn/application-dev/napi/use-napi-about-buffer.md @@ -6,14 +6,14 @@ ## 基本概念 -使用Node-API接口进行buffer相关开发时，使用Buffer对象与ArkTS代码之间进行二进制数据的有效交互，以便在Node-API模块创建、操纵和传递Buffer对象到ArkTS，从而处理和传递二进制数据，比如文件I/O、网络传输等。 +使用Node-API接口进行buffer相关开发时，使用Buffer对象与ArkTS代码进行二进制数据的有效交互，以便在Node-API模块中创建、操纵和传递Buffer对象到ArkTS，处理和传递二进制数据，比如文件I/O、网络传输等。 - **Buffer对象**：用于表示一段二进制数据的对象。 - **外部Buffer**：在Node-API模块中创建的Buffer，可以与现有的数据关联起来而不需要复制数据到新的Buffer中。 ## 场景和功能使用 -以下这些接口用于有效地与ArkTS层进行交互，这使Node-API模块能够更好地处理ArkTS层的二进制数据，比如处理文件I/O、网络传输等操作： +以下接口用于与ArkTS层有效交互，使Node-API模块能够更好地处理ArkTS层的二进制数据，如文件I/O和网络传输等： | 接口 | 描述 | | -------- | -------- | | napi_create_buffer | 用于创建并获取一个指定大小的ArkTS Buffer。 | @@ -25,11 +25,11 @@ ## 使用示例 -Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 +Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅展示接口对应的C++和ArkTS代码。 ### napi_create_buffer -此接口用于创建Buffer对象。Buffer对象是用于在Node-API模块中操作二进制数据的一种特殊类型。 +此接口用于创建Buffer对象。Buffer对象在Node-API模块中用于操作二进制数据。 cpp部分代码 @@ -72,7 +72,7 @@ try { ### napi_create_buffer_copy -本接口是Node-API中用于创建并复制数据到Buffer对象的函数。它可以在Node-API模块中创建一个新的Buffer对象，并将指定的数据复制到该Buffer对象中。 +本接口在Node-API模块中用于创建并复制数据到Buffer对象。它创建新的Buffer对象，并将指定数据复制到此对象中。 cpp部分代码 @@ -115,7 +115,7 @@ try { ### napi_create_external_buffer -当希望在ArkTS中使用现有的Node-API模块内存块，而不需要额外的拷贝时，可以使用napi_create_external_buffer。这将允许ArkTS层直接访问并操作该内存，避免额外的内存分配和拷贝操作。 +在ArkTS中使用现有的Node-API模块内存块时，可以使用napi_create_external_buffer。这允许ArkTS层直接访问并操作该内存，避免额外的内存分配和拷贝。 cpp部分代码 @@ -171,7 +171,7 @@ try { ### napi_get_buffer_info -在ArkTS中需要对Buffer对象中的数据执行特定的操作时，可以使用此接口来获取指向数据的指针和数据长度。这样可以在Node-API模块直接对数据进行操作，而无需进行数据的拷贝。 +在ArkTS中，可以使用此接口获取Buffer对象的数据指针和长度，直接在Node-API模块中操作数据，避免数据拷贝。 cpp部分代码 @@ -222,7 +222,7 @@ try { ### napi_is_buffer -判断给定ArkTS value是否为Buffer对象。 +此接口用于判断给定ArkTS value是否为Buffer对象。 cpp部分代码 @@ -268,7 +268,7 @@ try { ### napi_create_external_arraybuffer -分配一个附加有外部数据的ArkTS ArrayBuffer。 +此接口用于分配一个附加有外部数据的ArkTS ArrayBuffer。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-about-class.md b/zh-cn/application-dev/napi/use-napi-about-class.md index f358931b0f513eca2b1bc4092b4153a9f330e192..5a24593112cc791afc39339c98390cf0c9c86c56 100644 --- a/zh-cn/application-dev/napi/use-napi-about-class.md +++ b/zh-cn/application-dev/napi/use-napi-about-class.md @@ -2,18 +2,18 @@ ## 简介 -使用Node-API接口进行class相关开发，处理ArkTS中的类，例如定义类、构造实例等。 +使用Node-API接口开发class相关功能，处理ArkTS中的类，如定义类和创建实例等。 ## 基本概念 -在使用Node-API接口进行class相关开发时，需要理解以下基本概念： +使用Node-API接口进行class相关开发时，需要理解以下基本概念： -- **类**：类是用于创建对象的模板。它提供了一种封装数据和行为的方式，以便于对数据进行处理和操作。类在ArkTS中是建立在原型（prototype）的基础上的，并且还引入了一些类独有的语法和语义。 -- **实例**：实例是通过类创建具体的对象。类定义了对象的结构和行为，而实例则是类的具体表现。通过实例化类，我们可以访问类中定义的属性和方法，并且每个实例都具有自己的属性值。 +- **类**：类是用于创建对象的模板。它提供了一种封装数据和行为的方式，以便于对数据进行处理和操作。类在ArkTS中基于原型（prototype）建立，并引入了类独有的语法和语义。 +- **实例**：实例是通过类创建的具体对象。类定义了对象的结构和行为，实例则是类的具体表现。通过实例化类，可以访问类中定义的属性和方法，每个实例都具有自己的属性值。 ## 场景和功能介绍 -以下Node-API接口主要用于处理class。他们的使用场景如下： +以下Node-API接口主要用于处理class。这些接口的使用场景包括： | 接口 | 描述 | | -------- | -------- | | napi_new_instance | 需要通过给定的构造函数构建一个实例时，可以使用这个函数。 | @@ -29,7 +29,7 @@ Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程 ### napi_new_instance -通过给定的构造函数实例化一个对象，将这个对象返回ArkTS侧使用。 +通过给定的构造函数创建一个对象，并将其返回给ArkTS侧使用。 > **说明：** > @@ -79,7 +79,7 @@ hilog.info(0x0000, 'Node-API', 'napi_new_instance %{public}s', JSON.stringify(ob 用于获取构造函数的new.target值。在ArkTS中，new.target是一个特殊的元属性，用于在构造函数中判断是否通过new关键字调用了该构造函数。 -示例代码可以参考链接： +示例代码请参考链接： [Native与ArkTS对象绑定](use-napi-object-wrap.md) @@ -87,7 +87,7 @@ hilog.info(0x0000, 'Node-API', 'napi_new_instance %{public}s', JSON.stringify(ob 用于定义一个ArkTS类。该函数允许在Node-API模块中创建一个ArkTS类，并将类的方法和属性与相应的Node-API模块关联起来。 -示例代码可以参考链接： +示例代码请参考链接： [Native与ArkTS对象绑定](use-napi-object-wrap.md) @@ -101,7 +101,7 @@ hilog.info(0x0000, 'Node-API', 'napi_new_instance %{public}s', JSON.stringify(ob ### napi_unwrap -从一个被包装的对象中解除包装并获取与之关联的数据指针。 +解除包装对象并获取关联的数据指针。 > **说明：** > @@ -109,7 +109,7 @@ hilog.info(0x0000, 'Node-API', 'napi_new_instance %{public}s', JSON.stringify(ob ### napi_remove_wrap -从ArkTS object上获取先前绑定的native对象实例，并解除绑定。 +从ArkTS object上获取先前绑定的native对象实例并解除绑定。 > **说明：** > diff --git a/zh-cn/application-dev/napi/use-napi-about-cleanuphook.md b/zh-cn/application-dev/napi/use-napi-about-cleanuphook.md index 8b8b4e4976e77dc11346f7dd20224cbd7cbad886..07dd44285cf2b05c37c66fbb0b87ec0696a02ff9 100644 --- a/zh-cn/application-dev/napi/use-napi-about-cleanuphook.md +++ b/zh-cn/application-dev/napi/use-napi-about-cleanuphook.md @@ -2,20 +2,20 @@ ## 简介 -使用Node-API接口在进程退出时处理未释放资源，在Node-API模块注册清理钩子，一旦当前环境退出，这些钩子就会运行，使所有资源都被正确释放。 +使用Node-API接口在进程退出时处理未释放资源，注册清理钩子，环境退出时运行这些钩子，确保资源正确释放。 ## 基本概念 Node-API提供了注册和取消注册清理钩子函数的功能，以下是相关概念： -- **资源管理**：在ArkTS中，通常需要管理一些系统资源，比如内存、文件句柄、网络连接等。这些资源必须在Node-API模块的生命周期中正确地创建、使用和释放，以避免资源泄漏和程序崩溃。资源管理通常包括初始化资源、在合适的时候清理资源，以及在清理资源时执行必要的操作，比如关闭文件或断开网络连接。 -- **钩子函数（Hook）**：钩子函数是一种在特定事件或时间点自动执行的回调函数。在Node-API模块的上下文中，清理钩子函数通常用于在环境或进程退出时执行资源清理任务。这是因为环境或进程退出时，操作系统可能不会立即回收所有资源，因此需要通过清理钩子函数来确保所有资源都被正确释放。 +- **资源管理**：在ArkTS中，需要管理内存、文件句柄、网络连接等系统资源。这些资源必须在Node-API模块的生命周期中正确创建、使用和释放，以避免资源泄漏和程序崩溃。资源管理包括初始化资源、适时清理资源，并在清理时执行必要操作，如关闭文件、断开网络连接。 +- **钩子函数（Hook）**：钩子函数是在特定事件或时间点自动执行的回调函数。在Node-API模块的上下文中，清理钩子函数通常用于在环境或进程退出时执行资源清理任务。这是因为环境或进程退出时，操作系统可能不会立即回收所有资源，因此需要通过清理钩子函数来确保所有资源都被正确释放。 -以上这些基本概念是理解和使用Node-API接口注册环境清理钩子的基础，下面将介绍具体的接口和使用示例。 +以上基本概念是理解和使用Node-API接口注册环境清理钩子的基础。 ## 场景和功能介绍 -以下Node-API接口用于注册和取消不同类型的清理钩子。他们的使用场景如下： +以下Node-API接口用于注册和取消不同类型的清理钩子。使用场景包括： | 接口 | 描述 | | -------- | -------- | @@ -30,13 +30,13 @@ Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程 ### napi_add_env_cleanup_hook -用于注册一个环境清理钩子函数，该函数将在环境退出时执行。这是确保资源在环境销毁前得到清理的重要机制。 +用于注册环境清理钩子函数，该函数在环境退出时执行，确保资源在环境销毁前得到清理。 -需要注意的是，napi_add_env_cleanup_hook接口并不支持对同一arg绑定多个回调。若出现env已销毁，但cleanup回调未被执行的情况。可以在启用ArkTS运行时[多线程检测](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-multi-thread-check)功能的前提下，查看hilog流水日志`AddCleanupHook Failed, data cannot register multiple times.`来查找发生注册失败的调用。 +需要注意的是，napi_add_env_cleanup_hook接口不支持对同一arg绑定多个回调。若env已被销毁，但cleanup回调未被执行，可以在启用ArkTS运行时[多线程检测](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-multi-thread-check)功能后，通过查看hilog流水日志`AddCleanupHook Failed, data cannot register multiple times.`信息来查找注册失败的调用。 ### napi_remove_env_cleanup_hook -用于取消之前注册的环境清理钩子函数。在某些情况下，需要在插件卸载或资源被重新分配时取消钩子函数。 +用于取消之前注册的环境清理钩子函数。可以在插件卸载或资源被重新分配时取消钩子函数。 cpp部分代码 @@ -142,11 +142,11 @@ worker相关开发配置和流程参考以下链接： ### napi_add_async_cleanup_hook -这个接口用于注册一个异步清理钩子函数，该函数将在环境退出时异步执行。与同步钩子不同，异步钩子允许在进程退出时进行更长时间的操作，而不会阻塞进程退出。 +此接口用于注册一个异步清理钩子函数，该函数将在环境退出时异步执行。与同步钩子不同，异步钩子允许在进程退出时进行更长时间的操作，而不会阻塞进程退出。 ### napi_remove_async_cleanup_hook -这个接口用于取消之前注册的异步清理钩子函数。与取消同步钩子类似，这通常是在不再需要钩子函数时进行的操作。 +这个接口用于取消之前注册的异步清理钩子函数。与取消同步钩子类似，通常在不再需要钩子函数时使用。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-about-date.md b/zh-cn/application-dev/napi/use-napi-about-date.md index f3fc9f3a5e8f1d9272de492ecb2c5c90519b1ef9..cdb5ac3c884acd618232bcc1287d6252a6648033 100644 --- a/zh-cn/application-dev/napi/use-napi-about-date.md +++ b/zh-cn/application-dev/napi/use-napi-about-date.md @@ -6,28 +6,28 @@ Node-API中date相关接口用于处理ArkTS Date对象，并在Node-API模块 ## 基本概念 -在Node-API的中，ArkTS Date对象的数据表示从UTC时间1970年1月1日0时0分0秒起至现在的总毫秒数。 +在Node-API中，ArkTS Date对象的数据表示从UTC时间1970年1月1日0时0分0秒起至现在的总毫秒数。 -ArkTS Date对象提供了一种在ArkTS中表示和操作日期和时间的方式。它们允许您创建表示特定时刻的日期对象，执行各种日期和时间相关的计算（如添加或减去时间间隔），以及格式化日期为字符串以供显示。 +ArkTS Date对象提供了表示和操作日期和时间的方式。可以创建日期对象，执行日期和时间的计算（如添加或减去时间间隔），以及格式化日期为字符串。 -在Node-API中，通过提供与Date对象交互的函数，Node-API模块能够更紧密地与ArkTS环境集成，执行更复杂的日期和时间相关操作。 +Node-API提供与Date对象交互的函数，模块能够与ArkTS环境集成，执行更复杂的日期和时间操作。 ## 场景和功能介绍 -以下Node-API函数通常在开发Node-API模块中与ArkTS的Date对象进行交互时使用，来处理和操作日期数据。以下是一些可能的使用场景： +以下Node-API函数在开发Node-API模块中与ArkTS Date对象进行交互时使用，用于处理和操作日期数据。这些函数的使用场景包括： | 接口 | 描述 | | -------- | -------- | -| napi_create_date | 在需要根据当前系统时间或特定计算生成一个Date对象时，可通过使用此接口创建表示这些时间的ArkTS Date对象，然后将其传递给ArkTS代码进行进一步处理。 | -| napi_get_date_value | 在Node-API模块中接收到一个ArkTS的Date对象，并且需要获取其对应的时间戳或日期值时，可以使用此接口。| -| napi_is_date | 在需要确定一个ArkTS对象是否为Date对象时，可使用此接口判断给定的值是否为Date对象。例如，在接收函数参数时，需要验证参数是否为Date对象以确保正确的数据类型。 | +| napi_create_date | 在需要根据当前系统时间或特定计算生成Date对象时，使用此接口创建表示这些时间的ArkTS Date对象，然后传递给ArkTS代码进行处理。 | +| napi_get_date_value | 在Node-API模块中接收ArkTS Date对象时，可以使用此接口获取其时间戳或日期值。| +| napi_is_date | 在需要确定一个ArkTS对象是否为Date对象时，使用此接口判断给定的值是否为Date对象。例如，接收函数参数时，验证参数是否为Date对象以确保正确的数据类型。 | ## 使用示例 -Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 +Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅展示接口对应的C++和ArkTS相关代码。 ### napi_create_date -通过一个C++的double数据创建ArkTS的Date。 +使用C++ double数据创建ArkTS Date。 cpp部分代码 @@ -63,7 +63,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_date: %{public}s', test ### napi_get_date_value -获取给定ArkTS Date对应的C++ double值。 +获取ArkTS Date的C++ double值。 cpp部分代码 @@ -118,7 +118,7 @@ try { ### napi_is_date -判断给定ArkTS value是否为ArkTS Date对象。 +判断ArkTS value是否为ArkTS Date对象。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-about-environmental-life-cycle.md b/zh-cn/application-dev/napi/use-napi-about-environmental-life-cycle.md index 0713bddd7ee55042c9aa3cd105ca89a74c66d6be..a37f7a4a00c4397ad3025a59befe4f85fe0820e3 100644 --- a/zh-cn/application-dev/napi/use-napi-about-environmental-life-cycle.md +++ b/zh-cn/application-dev/napi/use-napi-about-environmental-life-cycle.md @@ -2,15 +2,15 @@ ## 简介 -在Node-API模块中，我们可以使用Node-API接口将特定数据与当前的环境相关联，并在需要时检索该数据。 +在Node-API模块中，使用Node-API接口将特定数据与当前环境相关联，并在需要时检索数据。 ## 基本概念 -在Node-API中的关联数据是指将自定义的C++数据结构的生命周期与当前环境的生命周期相关联，这意味着只要当前运行环境存在，关联数据就会保持有效。 +在Node-API中，关联数据是指将自定义的C++数据结构的生命周期与当前环境的生命周期相关联，这样只要当前环境存在，关联数据就保持有效。 ## 场景和功能介绍 -以下接口可以帮助我们在Node-API模块中更方便地管理对象实例所需的状态信息、引用计数或其他自定义数据，他们的使用场景如下： +以下接口可在Node-API模块中更方便地管理对象实例所需的状态信息、引用计数或其他自定义数据，使用场景如下： | 接口 | 描述 | | -------- | -------- | | napi_set_instance_data | 绑定与当前运行的环境相关联的数据项。 | @@ -18,11 +18,11 @@ ## 使用示例 -Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 +Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅展示接口对应C++及ArkTS相关代码。 ### napi_set_instance_data -将需要绑定的数据与当前运行的环境相关联。 +将需要绑定的数据与当前环境相关联。 cpp部分代码 @@ -85,7 +85,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_set_instance_data:%{public}s', ### napi_get_instance_data -检索出与当前运行的环境相关联的数据项。 +检索出与当前环境相关联的数据项。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-about-error.md b/zh-cn/application-dev/napi/use-napi-about-error.md index fed94273e92a78181ff5bdbc74f0fbc82e9fa26d..93060bb59acbd10d84a2d8a0f9f60eeedfe6bb20 100644 --- a/zh-cn/application-dev/napi/use-napi-about-error.md +++ b/zh-cn/application-dev/napi/use-napi-about-error.md @@ -2,40 +2,40 @@ ## 简介 -使用Node-API接口进行错误处理开发，使得在Node-API模块中能够更好地管理和响应错误情况。通过合理使用这些函数，可以提高模块的稳定性和可靠性。 +使用Node-API接口进行错误处理开发，使得在Node-API模块中能够更好地管理和响应错误情况，提高模块的稳定性和可靠性。 ## 基本概念 -在ArkTS编程中，异常和错误是常见的概念。异常表示发生了某种意外情况，而错误则指示程序无法正确执行某些操作。Node-API提供了一系列方法来帮助开发者在Node-API模块中处理ArkTS中的异常和错误。下面是一些基本概念： +在ArkTS编程中，异常和错误是常见的概念。异常表示意外情况，错误指示程序无法正确执行操作。Node-API提供了一系列方法，帮助开发者在Node-API模块中处理这些异常和错误。以下是一些基本概念： - **异常（Exception）**：在程序执行过程中可能会出现的意外情况，可以是语法错误、运行时错误或逻辑错误，例如除以零或对未定义变量的操作。 - **错误（Error）**：表示程序无法顺利执行某些操作，可以是由底层系统、API函数或开发者自定义的。 - **类型错误（Type Error）**：表示操作或值的类型不符合预期的情况，通常是由于错误的数据类型导致的。 - **范围错误（Range Error）**：表示一个值不在预期的范围内，例如对数组长度之外的索引进行访问。 -这些基本概念在异常和错误处理中非常重要，开发者需要通过适当的方法来捕获、处理或向用户报告这些异常和错误，以确保程序的稳定性和正确性。Node-API提供的方法可以帮助开发者在Node-API模块中处理ArkTS中的异常和错误。 +基本概念在异常和错误处理中至关重要，开发者需通过适当的方法捕获、处理或报告异常和错误，以确保程序稳定和正确。Node-API提供的方法有助于在Node-API模块中处理ArkTS的异常和错误。 ## 场景和功能介绍 -以下Node-API接口主要用于与ArkTS交互时处理错误和异常情况。他们的使用场景如下： +以下Node-API接口主要用于与ArkTS交互时处理错误和异常。这些接口的使用场景包括： | 接口 | 描述 | | -------- | -------- | | napi_create_error、napi_create_type_error、napi_create_range_error | 在C/C++中需要创建一个错误对象时，可以使用这些函数。创建的错误对象可以使用napi_throw抛出到ArkTS。 | -| napi_throw | 当在C/C++中出现了错误或异常情况时，通过使用napi_create_error或napi_get_last_error_info方法创建或获取ArkTS Error对象，使用该方法抛出已有的ArkTS Error对象。 | -| napi_throw_error、napi_throw_type_error、napi_throw_range_error | 当在C/C++中出现了错误或异常情况时，可以使用这些函数来抛出ArkTS中的异常。 | +| napi_throw | 当在C/C++中出现了错误或异常情况时，使用napi_create_error或napi_get_last_error_info创建或获取ArkTS Error对象，并使用该方法抛出该对象。 | +| napi_throw_error、napi_throw_type_error、napi_throw_range_error | 当在C/C++中遇到错误或异常情况时，使用这些函数来抛出ArkTS中的异常。 | | napi_is_error | 检查一个napi_value是否代表一个错误对象时，可以使用这个函数。 | -| napi_get_and_clear_last_exception | 当你需要获取最近一次出现的异常，并将异常队列清空时，可以使用这个函数。 | -| napi_is_exception_pending | 当你需要判断是否有未处理的异常时，可以使用这个函数。 | -| napi_fatal_error | 当遇到严重错误或不可恢复的情况时，可以使用这个函数引发致命错误来立即终止进程。 | -| napi_fatal_exception | 抛出一个致命异常并终止进程, 同时产生相应的crash日志。| +| napi_get_and_clear_last_exception | 获取最近一次出现的异常，并清空异常队列。 | +| napi_is_exception_pending | 判断是否有未处理的异常时，使用此函数。 | +| napi_fatal_error | 当遇到严重错误或不可恢复的情况时，使用该函数引发致命错误，立即终止进程。 | +| napi_fatal_exception | 抛出一个致命异常并终止进程, 同时，生成相应的crash日志。| ## 使用示例 -Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 +Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅展示接口对应的C++及ArkTS相关代码。 ### napi_get_last_error_info -用于获取最后一次发生的错误信息，包括错误码、错误消息以及错误进栈信息，即使存在挂起的ArkTS异常，也可以调用此API。 +获取最后一次发生的错误信息，包括错误码、错误消息和错误进栈信息，即使存在挂起的ArkTS异常，也能调用此API。 cpp部分代码 @@ -91,7 +91,7 @@ try { ### napi_create_type_error -创建并获取一个带文本信息的ArkTS TypeError。 +创建并获取带文本信息的ArkTS TypeError。 cpp部分代码 @@ -133,7 +133,7 @@ try { ### napi_create_range_error -创建并获取一个带文本信息的ArkTS RangeError。 +创建并获取带文本信息的ArkTS RangeError。 cpp部分代码 @@ -175,11 +175,11 @@ try { ### napi_create_error -创建并获取一个带文本信息的ArkTS Error。 +创建并获取带文本信息的ArkTS Error。 ### napi_throw -用于在Node-API模块中抛出ArkTS异常的函数。当在本机代码中发生错误或检测到不符合预期的情况时，可以使用此接口来抛出一个ArkTS异常，使其能够被捕获并处理。 +在Node-API模块中，使用此函数抛出ArkTS异常。当在本机代码中发生错误或检测到不符合预期的情况时，通过该接口抛出异常，以便捕获和处理。 cpp部分代码 @@ -225,7 +225,7 @@ try { ### napi_throw_error -用于抛出一个带文本信息的ArkTS Error。 +抛出带文本信息的ArkTS Error。 cpp部分代码 @@ -284,7 +284,7 @@ try { ### napi_throw_type_error -创建并获取一个带文本信息的ArkTS TypeError。 +创建并获取带文本信息的ArkTS TypeError。 cpp部分代码 @@ -343,7 +343,7 @@ try { ### napi_throw_range_error -创建并获取一个带文本信息的ArkTS RangeError。 +创建并获取带文本信息的ArkTS RangeError。 cpp部分代码 @@ -409,7 +409,7 @@ try { ### napi_is_error -用于判断给定的napi_value是否表示一个error对象。 +判断napi_value是否表示error对象。 cpp部分代码 @@ -457,7 +457,7 @@ try { ### napi_get_and_clear_last_exception -用于获取并清除最近一次出现的异常。 +获取并清除最近一次异常。 cpp部分代码 @@ -497,7 +497,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_and_clear_last_exception, ### napi_is_exception_pending -用于判断是否出现了异常。 +判断是否出现异常。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-about-extension.md b/zh-cn/application-dev/napi/use-napi-about-extension.md index c5578a80361d45abeb311846337d65e89f90193c..6554c4f3a3c3ec38478dafec3cde8f9e52c0f132 100644 --- a/zh-cn/application-dev/napi/use-napi-about-extension.md +++ b/zh-cn/application-dev/napi/use-napi-about-extension.md @@ -2,9 +2,9 @@ ## 简介 -[扩展能力](napi-data-types-interfaces.md#扩展能力)接口进一步扩展了Node-API的功能，提供了一些额外的接口，用于在Node-API模块中与ArkTS进行更灵活的交互和定制，这些接口可以用于创建自定义ArkTS对象等场景。 +[扩展能力](napi-data-types-interfaces.md#扩展能力)接口进一步扩展了Node-API的功能，提供了一些额外的接口，用于在Node-API模块中与ArkTS进行更灵活的交互和定制。这些接口可以用于创建自定义ArkTS对象等场景。 -Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 +Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)。本文仅展示接口对应的C++及ArkTS相关代码。 ## 模块加载 @@ -13,8 +13,8 @@ Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程 | 接口 | 描述 | | -------- | -------- | | napi_load_module | 用于在Node-API模块中将abc文件作为模块加载，返回模块的命名空间，适用于需要在运行时动态加载模块或资源的应用程序，从而实现灵活的扩展和定制。 | -| napi_load_module_with_info | 用于在Node-API中进行模块的加载，当模块加载出来之后，可以使用函数napi_get_property获取模块导出的变量，也可以使用napi_get_named_property获取模块导出的函数，该函数可以在[新创建的ArkTS基础运行时环境](use-napi-ark-runtime.md)中使用。 | -| napi_module_register | 有些功能可能需要通过Node-API模块来实现以获得更好的性能，通过将这些功能实现为自定义模块并注册到ArkTS环境中，可以在一定程度上提高整体的性能。 | +| napi_load_module_with_info | 用于在Node-API中加载模块，模块加载完成后，可以使用napi_get_property获取模块导出的变量，或使用napi_get_named_property获取模块导出的函数。该函数适用于[新创建的ArkTS基础运行时环境](use-napi-ark-runtime.md)。 | +| napi_module_register | 通过将某些功能实现为Node-API模块并注册到ArkTS环境中，可以在一定程度上提高整体性能。 | ### 使用示例 @@ -28,7 +28,7 @@ Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程 #### napi_module_register -在ArkTS代码环境中使用Node-API模块编写的代码来实现特定的功能，可以将这部分功能封装成自定义模块，然后通过napi_module_register将其注册到ArkTS代码环境中，以实现功能的扩展和复用。 +在ArkTS代码环境中，使用Node-API模块编写的代码来实现特定的功能。可以将这部分功能封装成自定义模块，然后通过napi_module_register将其注册到ArkTS代码环境中，以实现功能的扩展和复用。 cpp部分代码 @@ -110,8 +110,8 @@ hilog.info(0x0000, 'testTag', 'Test Node-API 2 + 3 = %{public}d', testNapi.add(2 | 接口 | 描述 | | -------- | -------- | -| napi_create_object_with_properties | 用于在Node-API模块中使用给定的napi_property_descriptor创建ArkTS Object。descriptor的键名必须为string，且不可转为number。 | -| napi_create_object_with_named_properties | 用于在Node-API模块中使用给定的napi_value和键名创建ArkTS Object。键名必须为string，且不可转为number。 | +| napi_create_object_with_properties | 用于在Node-API模块中使用给定的napi_property_descriptor创建ArkTS Object。descriptor的键名必须为string，不可转为number。 | +| napi_create_object_with_named_properties | 用于在Node-API模块中使用给定的napi_value和键名创建ArkTS Object。键名必须为string，不可转为number。 | ### 使用示例 @@ -163,7 +163,7 @@ hilog.info(0x0000, 'testTag', 'Node-API napi_create_object_with_properties:%{pub #### napi_create_object_with_named_properties -用于使用给定的napi_value和键名创建一个ArkTS对象，并且给定的键名必须为string，且不可转为number。 +用于使用给定的napi_value和键名创建一个ArkTS对象，并且键名必须为string，且不可转为number。 cpp部分代码 @@ -223,7 +223,7 @@ hilog.info(0x0000, 'testTag', 'Node-API napi_create_object_with_named_properties #### napi_run_script_path -在Node-API模块中运行abc文件。 +在Node-API模块中运行指定的abc文件。 cpp部分代码 @@ -274,7 +274,7 @@ test.js代码，将js代码编成.abc文件，步骤如下： 1. 在SDK的ets/build-tools/ets-loader/bin/ark/build-win/bin目录下放置test.js文件 2. 执行命令如es2abc.exe test.js --output test.abc后便可生成test.abc文件 -放入指定路径中：/entry/resources/rawfile +将文件放入指定路径：/entry/resources/rawfile ```js function add(a, b) { @@ -289,13 +289,13 @@ add(1, 2); | 接口 | 描述 | | -------- | -------- | -| napi_queue_async_work_with_qos | 用于将异步工作对象加入队列，让开发者能够根据QoS优先级来管理和调度异步工作的执行，从而更好地满足程序的性能和响应需求。 | +| napi_queue_async_work_with_qos | 用于将异步工作对象加入队列，根据QoS优先级来管理和调度异步工作，更好地满足程序的性能和响应需求。 | ### 使用示例 #### napi_queue_async_work_with_qos -将异步工作对象加到队列，由底层根据传入的qos优先级去调度执行。 +将异步工作对象加入队列，底层根据传入的qos优先级进行调度执行。 [指定异步任务调度优先级](../performance/develop-Native-modules-using-NAPI-safely-and-efficiently.md#指定异步任务调度优先级) @@ -307,13 +307,13 @@ add(1, 2); | 接口 | 描述 | | -------- | -------- | -| napi_coerce_to_native_binding_object | 用于给ArkTS对象绑定回调和回调所需的参数，其作用是为了给ArkTS对象携带Native信息。 | +| napi_coerce_to_native_binding_object | 用于给ArkTS对象绑定回调及其所需参数，为ArkTS对象携带Native信息。 | ### 使用示例 #### napi_coerce_to_native_binding_object -用于给ArkTS Object绑定回调和回调所需的参数，给ArkTS Object携带Native信息。 +用于给ArkTS对象绑定回调及其所需参数，为ArkTS对象携带Native信息。 cpp部分代码 @@ -615,7 +615,7 @@ test01(); **注意事项** -对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。 +对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。 ![napi_coerce_to_native_binding_object](figures/napi_coerce_to_native_binding_object.png) @@ -725,7 +725,7 @@ let obj: Obj = { numKey: 500 }; hilog.info(0x0000, 'testTag', ' Node-API aboutSerialize: %{public}d', testNapi.aboutSerialize(obj)); ``` -## 根据任务指定的优先级和入队方式进行处理异步线程向ArkTS线程投递的任务 +## 根据任务指定的优先级和入队方式，处理异步线程向ArkTS线程投递的任务 ### 接口描述 @@ -745,23 +745,23 @@ hilog.info(0x0000, 'testTag', ' Node-API aboutSerialize: %{public}d', testNapi.a | 接口 | 描述 | | -------------------------- | ---------------------------------- | -| napi_is_sendable | 判断给定ArkTS value是否是Sendable的。 | -| napi_define_sendable_class | 创建一个sendable类。 | -| napi_create_sendable_object_with_properties | 使用给定的napi_property_descriptor创建一个sendable对象。| -| napi_create_sendable_array | 创建一个sendable数组。| -| napi_create_sendable_array_with_length | 创建一个指定长度的sendable数组。| -| napi_create_sendable_arraybuffer | 创建一个sendable ArrayBuffer。| -| napi_create_sendable_typedarray | 创建一个sendable TypedArray。| -| napi_wrap_sendable | 包裹一个native实例到ArkTS对象中。| -| napi_wrap_sendable_with_size | 包裹一个native实例到ArkTS对象中并指定大小。| +| napi_is_sendable | 判断给定的ArkTS value是否是Sendable。 | +| napi_define_sendable_class | 创建sendable类。 | +| napi_create_sendable_object_with_properties | 使用napi_property_descriptor创建sendable对象。| +| napi_create_sendable_array | 创建sendable数组。| +| napi_create_sendable_array_with_length | 创建指定长度的sendable数组。| +| napi_create_sendable_arraybuffer | 创建sendable ArrayBuffer。| +| napi_create_sendable_typedarray | 创建sendable TypedArray。| +| napi_wrap_sendable | 包裹native实例到ArkTS对象中。| +| napi_wrap_sendable_with_size | 包裹native实例到ArkTS对象中并指定大小。| | napi_unwrap_sendable | 获取ArkTS对象包裹的native实例。| -| napi_remove_wrap_sendable | 移除并获取ArkTS对象包裹的native实例，移除后回调将不再触发，需手动delete释放内存。| +| napi_remove_wrap_sendable | 移除并获取ArkTS对象包裹的native实例。| ### 使用示例 #### napi_is_sendable -判断给定ArkTS value是否是Sendable的。 +判断给定的ArkTS value是否是Sendable。 cpp部分代码 @@ -799,7 +799,7 @@ hilog.info(0x0000, 'testTag', 'Node-API napi_is_sendable: %{public}s', JSON.stri #### napi_define_sendable_class -创建一个sendable类。 +创建sendable类。 cpp部分代码 @@ -898,7 +898,7 @@ hilog.info(0x0000, 'testTag', 'Node-API napi_define_sendable_class: %{public}s', #### napi_create_sendable_object_with_properties -使用给定的napi_property_descriptor创建一个sendable对象。 +使用napi_property_descriptor创建sendable对象。 cpp部分代码 @@ -936,7 +936,7 @@ hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_object_with_propert #### napi_create_sendable_array -创建一个sendable数组。 +创建sendable数组。 cpp部分代码 @@ -969,7 +969,7 @@ hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_array: %{public}s', #### napi_create_sendable_array_with_length -创建一个指定长度的sendable数组。 +创建指定长度的sendable数组。 cpp部分代码 @@ -1000,7 +1000,7 @@ hilog.info(0x0000, 'testTag', 'Node-API napi_create_sendable_array_with_length: #### napi_create_sendable_arraybuffer -创建一个sendable ArrayBuffer。 +创建sendable ArrayBuffer。 cpp部分代码 @@ -1038,7 +1038,7 @@ testNapi.getSendableArrayBuffer(); #### napi_create_sendable_typedarray -创建一个sendable TypedArray。 +创建sendable TypedArray。 cpp部分代码 @@ -1080,7 +1080,7 @@ testNapi.getSendableTypedArray(); #### napi_wrap_sendable -包裹一个native实例到ArkTS对象中。 +包裹native实例到ArkTS对象中。 cpp部分代码 @@ -1121,7 +1121,7 @@ testNapi.wrapSendable(); #### napi_wrap_sendable_with_size -包裹一个native实例到ArkTS对象中并指定大小。 +包裹一个native实例到ArkTS对象中，并设置其大小。 cpp部分代码 @@ -1207,7 +1207,7 @@ testNapi.unwrapSendable(); #### napi_remove_wrap_sendable -移除并获取ArkTS对象包裹的native实例，移除后回调将不再触发，需手动delete释放内存。 +移除并获取ArkTS对象中包裹的native实例。 cpp部分代码 @@ -1266,13 +1266,13 @@ target_link_libraries(entry PUBLIC libhilog_ndk.z.so) | 接口 | 描述 | | -------- | -------- | -| napi_wrap_enhance | 在ArkTS对象上绑定一个Node-API模块对象实例并指定实例大小，开发者可以指定绑定的回调函数是否异步执行，如果异步执行，则回调函数必须是线程安全的。 | +| napi_wrap_enhance | 在ArkTS对象上绑定一个Node-API模块对象实例并指定实例大小。开发者可指定回调函数的执行模式，若为异步执行，回调函数需确保线程安全。 | ### 使用示例 #### napi_wrap_enhance -在ArkTS对象上绑定一个Node-API模块对象实例并指定实例大小，开发者可以指定绑定的回调函数是否异步执行，如果异步执行，则回调函数必须是线程安全的。 +在ArkTS对象上绑定一个Node-API模块对象实例并指定实例大小。开发者可指定回调函数的执行模式，若为异步执行，回调函数需确保线程安全。 cpp部分代码 @@ -1322,8 +1322,8 @@ testNapi.testNapiWrapEnhance(); | 接口 | 描述 | | -------- | -------- | -| napi_create_ark_context | 创建基础运行时上下文环境。 | -| napi_destroy_ark_context | 销毁基础运行时上下文环境。 | +| napi_create_ark_context | 创建基础运行时的上下文环境。 | +| napi_destroy_ark_context | 销毁基础运行时的上下文环境。 | ### 使用示例 #### napi_create_ark_context、napi_destroy_ark_context diff --git a/zh-cn/application-dev/napi/use-napi-about-function.md b/zh-cn/application-dev/napi/use-napi-about-function.md index cd5b1637ab9eb6ec556902e0184a1e7ef3774247..2d933cb6805781e8759f0ec416621e8fe7329e3a 100644 --- a/zh-cn/application-dev/napi/use-napi-about-function.md +++ b/zh-cn/application-dev/napi/use-napi-about-function.md @@ -2,11 +2,11 @@ ## 简介 -函数调用允许开发者从Node-API模块中调用ArkTS函数，并传递参数进行调用，或者直接在Node-API模块中创建一个ArkTS方法。 +函数调用允许开发者从Node-API模块中调用ArkTS函数并传递参数，或在Node-API模块中创建ArkTS方法。 ## 基本概念 -函数是一种非常重要的编程概念，可以执行特定的任务或操作、提高代码的可读性、把复杂任务简化、提高代码复用性以及支持代码的组织与管理。每个函数可以负责不同的功能，提供一种将代码模块化和组织结构化的方式，使其更易于理解、维护和重用。 +函数是编程中的重要概念，用于执行特定任务或操作、提高代码可读性、简化复杂任务、增强代码复用性，并支持代码的组织与管理。每个函数负责不同的功能，提供一种将代码模块化和组织结构化的方式，便于理解、维护和重用。 ## 场景和功能介绍 @@ -18,7 +18,7 @@ ## 使用示例 -Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。napi_create_function方法除外，具体使用见示例。 +Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅展示Node-API接口对应的C++和ArkTS代码。napi_create_function方法的具体使用见示例。 ## napi_get_cb_info @@ -106,7 +106,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_cb_info get thisArg:%{publ ## napi_call_function 在C/C++侧对ArkTS函数进行调用。 -注意事项：napi_call_function传入的argv的长度必须大于等于argc声明的数量，且被初始化成nullptr。 +注意事项：确保napi_call_function传入的argv的长度大于等于argc声明的数量，且初始化为nullptr。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-about-object.md b/zh-cn/application-dev/napi/use-napi-about-object.md index 1faedb4c015c5950f7117305d4b3bdb53ac2adf2..b373d9481c33b24aed7bb4cb971f44ef2597ef1e 100644 --- a/zh-cn/application-dev/napi/use-napi-about-object.md +++ b/zh-cn/application-dev/napi/use-napi-about-object.md @@ -2,11 +2,11 @@ ## 简介 -使用Node-API接口进行object相关开发，处理ArkTS对象的基本操作的功能，例如创建对象、获取原型、冻结和密封对象，检查对象的类型等。这些操作是在处理ArkTS对象时非常常见的，提供了一种与ArkTS对象交互的方式。 +使用Node-API接口进行object相关开发，处理ArkTS对象的基本操作，如创建对象、获取原型、冻结和密封对象，检查对象类型等。这些操作提供了与ArkTS对象交互的方式。 ## 基本概念 -在Node-API接口开发中，经常需要定义和操作对象。例如，创建一个API接口，该接口接受一个对象作为输入参数，对该对象执行某些操作，并返回一个结果对象。在这个过程中，需要确保接口的定义清晰、规范，并且与对象的属性和方法相兼容。 +在Node-API接口开发中，经常需要定义和操作对象。例如，创建一个API接口，接受对象作为输入参数，对该对象进行某些操作，并返回一个结果对象。在这个过程中，需要确保接口的定义清晰、规范，并与对象的属性和方法兼容。 - **接口（API）**：接口定义了组件之间的交互协议，包括输入参数、输出结果以及可能的错误处理。通过接口，组件可以相互调用和交换数据，而无需了解对方的内部实现细节。 - **对象（Object）**：在ArkTS，对象是一种复合数据类型，允许存储多个不同类型的值作为一个单独的实体。对象是属性和方法的集合。属性是与对象相关联的值，而方法则是对象可以执行的操作。 @@ -16,17 +16,17 @@ 以下Node-API接口主要用于操作和管理ArkTS对象，使用场景介绍： | 接口 | 描述 | | -------- | -------- | -| napi_get_prototype | 当需要获取一个ArkTS对象的原型时，可以使用这个接口。通过这个接口可以在C/C++中获取到这个原型对象。 | -| napi_create_object | 在Node-API模块中创建一个默认的ArkTS对象。 | -| napi_object_freeze | 当需要确保一个对象不会被修改时（immutable），可以使用这个接口来冻结该对象，使其属性不可更改。 | -| napi_object_seal | 类似于napi_object_freeze，napi_object_seal用于密封给定的对象，使其属性不可添加或删除，但可以修改属性的值。 | -| napi_typeof | 在处理传入的ArkTS值时，可以使用这个接口来获取其类型，以便进行相应的处理。 | -| napi_instanceof | 当需要在Node-API模块中确定一个对象是否为特定构造函数的实例时，可以使用这个接口。 | +| napi_get_prototype | 当需要获取一个ArkTS对象的原型时，可以使用这个接口。 | +| napi_create_object | 创建一个默认的ArkTS对象。 | +| napi_object_freeze | 当需要确保一个对象不会被修改时（immutable），使用该接口来冻结该对象，使其属性不可更改。 | +| napi_object_seal | 类似于napi_object_freeze，napi_object_seal用于密封给定的对象，使其属性不可添加或删除，但可修改属性值。 | +| napi_typeof | 在处理传入的ArkTS值时，可以使用这个接口来获取其类型。 | +| napi_instanceof | 当需要在Node-API模块中确定一个对象是否为特定构造函数的实例时，可以使用该接口。 | | napi_type_tag_object | 可以将指针的特定值与ArkTS对象关联起来，这对于一些自定义的内部对象标记非常有用。 | | napi_check_object_type_tag | 使用此接口可以检查给定的对象上是否关联了特定类型的标记。 | | napi_create_symbol | 创建一个ArkTS Symbol对象。 | -| napi_create_external | 用于创建一个ArkTS外部对象，该对象可以用于将C/C++中的自定义数据结构或对象传递到ArkTS中，并且可以在ArkTS中访问其属性和方法。 | -| napi_get_value_external | 用于获得napi_create_external创建的绑定了外部数据的ArkTS值，此函数可以在ArkTS和C/C++之间传递数据。 | +| napi_create_external | 用于创建一个ArkTS外部对象，该对象可以将C/C++中的自定义数据结构或对象传递到ArkTS中，并在ArkTS中访问其属性和方法。 | +| napi_get_value_external | 用于获得napi_create_external创建的绑定了外部数据的ArkTS值。此函数可以在ArkTS和C/C++之间传递数据。 | 这些接口为开发人员提供了在Node-API模块中处理ArkTS对象的灵活性和功能性，可以实现从创建对象到管理对象属性以及类型检查等多种操作。 @@ -36,7 +36,7 @@ Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程 ### napi_get_prototype -可以获得给定ArkTS对象的prototype。 +可以获取给定ArkTS对象的prototype。 cpp部分代码 @@ -198,7 +198,7 @@ try { ### napi_object_seal -封闭一个对象后，无法向其添加新的属性，也无法删除或修改现有属性的可配置性。但是，可以继续修改已有属性的值。 +密封一个对象后，无法向其添加新的属性，也无法删除或修改现有属性的可配置性。但可以修改已有属性的值。 cpp部分代码 @@ -425,9 +425,9 @@ try { ### napi_check_object_type_tag -验证一个ArkTS对象是否带有特定类型标签。 +验证ArkTS对象是否带有特定类型标签。 -类型标签提供了一种在Node-API模块和ArkTS对象之间建立强类型关联的机制，使得原生代码能够更准确地识别和处理特定的ArkTS对象。 +类型标签提供了一种在Node-API模块和ArkTS对象之间建立强类型关联的机制，使原生代码能够更准确地识别和处理特定的ArkTS对象。 cpp部分代码 @@ -512,7 +512,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_check_object_type_tag objB -> ### napi_create_external -创建包装自定义的C/C++对象并将其公开给ArkTS代码。这种情况下，我们可以使用napi_create_external来创建一个包含指向自定义对象的指针的Node-API值，以便让ArkTS代码能够访问和操作该对象。 +创建包装自定义的C/C++对象并公开给ArkTS代码。这种情况下，可以使用napi_create_external来创建一个包含指向自定义对象的指针的Node-API值，使ArkTS代码能够访问和操作该对象。 cpp部分代码 @@ -583,7 +583,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_external:%{public}s', t ### napi_get_value_external -napi_create_external可以创建包装自定义的C/C++对象并将其公开给ArkTS代码，而napi_get_value_external就是用来获得napi_create_external所创建的外部对象的。 +napi_create_external可以创建包装自定义的C/C++对象，将其公开给ArkTS代码，而napi_get_value_external用来获得napi_create_external所创建的外部对象。 cpp部分代码 @@ -624,7 +624,7 @@ hilog.info(0x0000, 'Node-API', 'get_value_external:%{public}d', testNapi.getValu ### napi_create_symbol -用于创建一个新的Symbol。Symbol是一种特殊的数据类型，用于表示唯一的标识符。与字符串或数字不同，符号的值是唯一的，即使两个符号具有相同的描述，它们也是不相等的。符号通常用作对象属性的键，以确保属性的唯一性。 +创建一个新的Symbol。Symbol是一种特殊的数据类型，用于表示唯一的标识符。与字符串或数字不同，符号的值是唯一的，即使两个符号具有相同的描述，它们也是不相等的。符号通常用作对象属性的键，以确保属性的唯一性。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-about-other-practical-tools.md b/zh-cn/application-dev/napi/use-napi-about-other-practical-tools.md index 8555881c14341854e5119b5a541e716b5c6db673..204cdd4c7d1ad8629fdff845d6274a778dc0f239 100644 --- a/zh-cn/application-dev/napi/use-napi-about-other-practical-tools.md +++ b/zh-cn/application-dev/napi/use-napi-about-other-practical-tools.md @@ -2,26 +2,26 @@ ## 简介 -Node-API接口提供了一些实用接口，可以帮助开发者更好地进行Node-API相关开发。 +Node-API接口提供了一些实用接口，帮助开发者进行Node-API开发。 ## 基本概念 -- **模块加载：** 在Node-API模块中，模块是指包含特定功能的ArkTS文件，通过import导入lib共享库中的模块。了解Node-API模块中的加载机制以及模块之间的依赖关系对于理解node_api_get_module_file_name接口的使用很有帮助。 +- **模块加载：** 在Node-API模块中，模块是指包含特定功能的ArkTS文件，通过import导入lib共享库中的模块。了解Node-API模块中的加载机制以及模块间的依赖关系，有助于理解node_api_get_module_file_name接口的使用。 - **文件路径和URL：** node_api_get_module_file_name返回的是加载项的绝对路径的URL。 -- **比较ArkTS值严格相等：** 比较两个ArkTS值是否严格相等。严格相等比较不会进行类型转换，它要求两个值的类型和值完全相同才会返回true。 -- **处理异步操作：**：通过Libuv可以实现异步操作，避免阻塞主线程，使得程序可以同时执行多个任务而不会出现阻塞现象。 -- **实现事件循环：**：Libuv提供了事件循环机制，可以处理事件、触发回调函数，并管理事件队列，使得Node-API模块能够实现事件驱动的编程模型。 +- **比较ArkTS值严格相等：** 比较两个ArkTS值是否严格相等。严格相等比较不会进行类型转换，它要求两个值的类型和值完全相同。 +- **处理异步操作：** 通过Libuv实现异步操作，避免阻塞主线程，使程序能够同时执行多个任务而不会出现阻塞现象。 +- **实现事件循环：** Libuv提供事件循环机制，可以处理事件、触发回调函数并管理事件队列，使得Node-API模块能够实现事件驱动的编程模型。 ## 场景和功能介绍 | 接口 | 描述 | | -------- | -------- | | node_api_get_module_file_name | 获取加载项加载位置的绝对路径。 | -| napi_strict_equals | 在某些情况下，希望确保两个值不仅具有相同的值，还具有相同的类型。例如，如果正在处理一些需要特定类型的数据结构或算法，使用napi_strict_equals可以确保数据的一致性。 | +| napi_strict_equals | 在某些情况下，用来确保两个值不仅值相同，类型也相同。例如，处理一些需要特定类型的数据结构或算法时，使用napi_strict_equals可以确保数据的一致性。 | ## 使用示例 -Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 +Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅展示接口对应的C++和ArkTS代码。 ### node_api_get_module_file_name diff --git a/zh-cn/application-dev/napi/use-napi-about-primitive.md b/zh-cn/application-dev/napi/use-napi-about-primitive.md index 7f0da4b52c592488b5e15281c407a66c017403c8..a01366626f1c5619e99c90c444ca1294f403fcc7 100644 --- a/zh-cn/application-dev/napi/use-napi-about-primitive.md +++ b/zh-cn/application-dev/napi/use-napi-about-primitive.md @@ -2,17 +2,17 @@ ## 简介 -在使用Node-API接口时，开发人员可以实现在Node-API模块中与ArkTS对象的交互，并进行数据转换和获取特定对象的操作，它们在不同的场景中发挥着重要的作用，使开发人员能够更灵活地处理ArkTS值和对象。 +在使用Node-API接口时，开发人员可以在Node-API模块中与ArkTS对象交互，进行数据转换和获取特定对象的操作，这些功能在不同的场景中发挥着重要作用，使开发人员能够更灵活地处理ArkTS值和对象。 ## 基本概念 -在使用Node-API操作ArkTS对象时，有一些基本概念需要了解： +在使用Node-API操作ArkTS对象时，需要了解一些基本概念： - **ArkTS值到C/C++类型的转换：** 在Node-API模块中，可以使用Node-API函数将ArkTS值转换为C/C++的数据类型，如将ArkTS数值转换为C/C++的整数、将ArkTS字符串转换为C/C++的字符数组等。同样，也可以将C/C++的数据类型转换为ArkTS值，以便将结果返回给ArkTS代码。 ## 场景和功能介绍 -以下接口用于从C/C++代码中与ArkTS进行交互，传递数据并执行操作，它们的使用场景如下： +以下接口用于从C/C++代码中与ArkTS进行交互，传递数据并执行操作。它们的使用场景如下： | 接口 | 描述 | | -------- | -------- | | napi_coerce_to_bool | 用于将给定的ArkTS value强转成ArkTS boolean值。 | @@ -27,7 +27,7 @@ ## 使用示例 -Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 +Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅展示接口对应的C++和ArkTS代码。 ### napi_coerce_to_bool @@ -216,7 +216,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_coerce_to_string:%{public}s', ### napi_get_boolean -用于根据给定的C boolean值，获取等价的ArkTS Boolean对象。 +根据给定的C boolean值，获取等价的ArkTS boolean对象。 cpp部分代码 @@ -263,7 +263,7 @@ hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_boolean:%{public}s', data) ### napi_get_value_bool -使用这个函数将ArkTS中的布尔值转为等价的C布尔值。 +使用这个函数将ArkTS中的布尔值转换为等价的C布尔值。 cpp部分代码 @@ -309,7 +309,7 @@ hilog.info(0x0000, 'Node-API', 'get_value_bool_false %{public}s', testNapi.getVa ### napi_get_global -用于获取全局ArkTS对象。该函数的主要作用是获取表示ArkTS全局对象的napi_value，使得C/C++模块能够与ArkTS运行时的全局对象进行交互。 +获取全局ArkTS对象。该函数用于获取表示ArkTS全局对象的napi_value，使得C/C++模块能够与ArkTS运行时的全局对象进行交互。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-basic-data-types.md b/zh-cn/application-dev/napi/use-napi-basic-data-types.md index 29d815efaa69c3049d10dffaa0cdbf5bd7ae5af8..b91354bf7fe87bbc0770ea873859736525a3947f 100644 --- a/zh-cn/application-dev/napi/use-napi-basic-data-types.md +++ b/zh-cn/application-dev/napi/use-napi-basic-data-types.md @@ -2,14 +2,14 @@ ## 简介 -ArkTS的Number类型是一个双精度64位二进制格式IEEE 754值。只有在-2^53+1到2^53-1范围内（闭区间）的整数才能在不丢失精度的情况下被表示，在超过该取值范围的情况下，需要使用BigInt对应的NPI接口来处理更大范围的整数。 +ArkTS的Number类型是一个双精度64位二进制格式IEEE 754值。只有在-2^53+1到2^53-1范围内（闭区间）的整数才能在不丢失精度的情况下被表示，超过该范围的整数需要使用BigInt对应的NPI接口处理。 ## 基本概念 -当使用Node-API接口进行数值类型的创建和获取时，有一些基本概念需要了解： +使用Node-API接口创建和获取数值类型时，需了解一些基本概念： -- **数值类型** 在使用Node-API接口时，可能需要从Node-API模块数值类型转换为ArkTS数值类型值，或者从ArkTS数据类型值转换为Node-API模块数值类型。在进行数据类型转换时，需要注意数据范围是否匹配，以及有无符号整数和双精度数值等区别。 -- **错误处理** 在使用这些接口时，需要对可能发生的错误进行适当处理。比如，在创建整数值时可能发生内存分配错误或其他运行时错误，需要使用Node-API提供的错误处理机制来捕获并处理这些错误。 +- **数值类型** 在使用Node-API接口时，需要从Node-API模块数值类型转换为ArkTS数值类型值，或者从ArkTS数值类型值转换为Node-API模块数值类型。在进行数据类型转换时，需要注意数据范围是否匹配，以及有无符号整数和双精度数值等区别。 +- **错误处理** 在使用这些接口时，需要处理可能发生的错误。例如，创建整数值时可能发生内存分配错误或其他运行时错误，应使用Node-API提供的错误处理机制来捕获并处理这些错误。 - **ArkTS交互** 在开发过程中，需要考虑如何将创建的数值类型值与ArkTS环境进行交互，包括传递参数、返回值等。 ## 场景和功能介绍 @@ -18,9 +18,9 @@ ArkTS的Number类型是一个双精度64位二进制格式IEEE 754值。只有 | 接口 | 描述 | | -------- | -------- | | napi_get_value_uint32 | 将ArkTS环境中number类型数据转为Node-API模块中的uint32类型数据。 | -| napi_get_value_int32 | 将ArkTS环境中获取的number类型数据转为Node-API模块中的int32类型数据。 | -| napi_get_value_int64 | 将ArkTS环境中获取的number类型数据转为Node-API模块中的int64类型数据。 | -| napi_get_value_double | 将ArkTS环境中获取的number类型数据转为Node-API模块中的double类型数据。 | +| napi_get_value_int32 | 将ArkTS环境中number类型数据转为Node-API模块中的int32类型数据。 | +| napi_get_value_int64 | 将ArkTS环境中number类型数据转为Node-API模块中的int64类型数据。 | +| napi_get_value_double | 将ArkTS环境中number类型数据转为Node-API模块中的double类型数据。 | | napi_create_int32 | 将Node-API模块中的int32_t类型转换为ArkTS环境中number类型。 | | napi_create_uint32 | 将Node-API模块中的uint32_t类型转换为ArkTS环境中number类型。 | | napi_create_int64 | 将Node-API模块中的int64_t类型转换为ArkTS环境中number类型。 | @@ -28,11 +28,11 @@ ArkTS的Number类型是一个双精度64位二进制格式IEEE 754值。只有 ## 使用示例 -Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅对接口对应C++及ArkTS相关代码进行展示。 +Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程](use-napi-process.md)，本文仅展示接口对应的C++及ArkTS相关代码。 ### napi_get_value_uint32 -用于从ArkTS环境中获取32位无符号整数值。 +从ArkTS环境中获取32位无符号整数值。 cpp部分代码 @@ -85,7 +85,7 @@ hilog.info(0x0000, 'Node-API', 'get_value_uint32_number %{public}d', testNapi.ge ### napi_get_value_int32 -将ArkTS value转为Node-API模块中的int32类型数据。 +将ArkTS环境中number类型数据转换为Node-API模块中的int32类型数据。 cpp部分代码 @@ -141,7 +141,7 @@ hilog.info(0x0000, 'Node-API', 'get_value_int32_number_-Infinity %{public}d', te ### napi_get_value_int64 -将ArkTS value转为Node-API模块中的int64类型数据。 +将ArkTS环境中number类型数据转换为Node-API模块中的int64类型数据 cpp部分代码 @@ -195,7 +195,7 @@ hilog.info(0x0000, 'Node-API', 'get_value_int64_number_-Infinity %{public}d', te ### napi_get_value_double -将ArkTS value转为Node-API模块中的double类型数据。 +将ArkTS环境中number类型数据转换为Node-API模块中的double类型数据。 cpp部分代码 @@ -239,7 +239,7 @@ hilog.info(0x0000, 'Node-API', 'get_value_double_not_number %{public}s', testNap ### napi_create_int32 -用于创建一个ArkTS数字（int32类型）的值。 +创建一个ArkTS数字（int32类型）的值。 cpp部分代码 @@ -281,7 +281,7 @@ hilog.info(0x0000, 'testTag','Test Node-API napi_create_int32：' + testNapi.cre ### napi_create_uint32 -用于创建一个ArkTS数字（uint32类型）的值。 +创建一个ArkTS数字（uint32类型）的值。 cpp部分代码 @@ -324,7 +324,7 @@ hilog.info(0x0000, 'testTag','Test Node-API napi_create_uint32: ' + testNapi.cre ### napi_create_int64 -用于创建一个ArkTS数字（int64类型）的值。 +创建一个ArkTS数字（int64类型）的值。 cpp部分代码 @@ -365,7 +365,7 @@ hilog.info(0x0000, 'testTag','Test Node-API napi_create_int64: ' + testNapi.crea ### napi_create_double -用于创建一个ArkTS数字（double类型）的值。 +创建一个ArkTS数字（double类型）的值。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-life-cycle.md b/zh-cn/application-dev/napi/use-napi-life-cycle.md index 5cf65198c17a916534dcac40e997b2c62b0497fb..997f2e042670e0099c14b774d73c6f2a5d52405f 100644 --- a/zh-cn/application-dev/napi/use-napi-life-cycle.md +++ b/zh-cn/application-dev/napi/use-napi-life-cycle.md @@ -4,18 +4,18 @@ 在Node-API中，napi_value是一个表示ArkTS值的抽象类型，它可以表示任何ArkTS值，包括基本类型（如数字、字符串、布尔值）和复杂对象类型（如数组、函数、对象等）。 -napi_value的生命周期与其在ArkTS中的对应值的生命周期紧密相关。当ArkTS值被垃圾回收时，与之关联的napi_value也将不再有效。重要的是不要在ArkTS值不再存在时尝试使用napi_value。 +napi_value的生命周期与其在ArkTS中的对应值的生命周期相关。当ArkTS值被垃圾回收时，与之关联的napi_value不再有效。不要在ArkTS值不再存在时尝试使用napi_value。 -框架层的scope通常用于管理napi_value的生命周期。在Node-API中，可以使用napi_open_handle_scope和napi_close_handle_scope函数来创建和销毁scope。通过在scope内创建napi_value，可以确保在scope结束时自动释放napi_value，避免内存泄漏。 +框架层的scope管理napi_value的生命周期。在Node-API中，使用napi_open_handle_scope和napi_close_handle_scope函数创建和销毁scope。在scope内创建napi_value，确保在scope结束时自动释放napi_value，避免内存泄漏。 -napi_ref是一个Node-API类型，用于管理napi_value的生命周期。napi_ref允许您在napi_value的生命周期内保持对其的引用，即使它已经超出了其原始上下文的范围。这使得您可以在不同的上下文中共享napi_value，并确保在不再需要时正确释放其内存。 +napi_ref是一个Node-API类型，用于管理napi_value的生命周期。napi_ref允许在napi_value的生命周期内保持对其的引用，即使超出了其原始上下文的范围。可以在不同的上下文中共享napi_value，并确保在不再需要时正确释放其内存。 ## 基本概念 -Node-API提供了一组功能，使开发人员能够在Node-API模块中创建和操作ArkTS对象，管理引用和生命周期，并注册垃圾回收回调函数等。下面是一些基本概念： +Node-API提供了一组功能，使开发人员能够在Node-API模块中创建和操作ArkTS对象，管理引用和生命周期，注册垃圾回收回调函数等。下面是一些基本概念： - **作用域**：用于创建一个范围，在范围内声明的引用在范围外部将不再生效。Node-API提供了创建、关闭普通和可逃逸的作用域的函数。 -- **引用管理**：Node-API提供函数来创建、删除和管理对象的引用，以延长对象的生命周期，避免出现对象use-after-free的问题。同时也通过引用管理去避免发生内存泄漏的问题。 +- **引用管理**：Node-API提供函数来创建、删除和管理对象的引用，延长对象的生命周期，避免出现对象use-after-free的问题。引用管理也能避免发生内存泄漏。 - **可逃逸的作用域**：允许在创建的作用域中声明的对象返回到父作用域，通过napi_open_escapable_handle_scope和napi_close_escapable_handle_scope进行管理。 - **垃圾回收回调**：允许注册回调函数，以便在ArkTS对象被垃圾回收时执行特定的清理操作。 @@ -23,16 +23,16 @@ Node-API提供了一组功能，使开发人员能够在Node-API模块中创建 ## 场景和功能介绍 -以下Node-API接口主要用于ArkTS对象的引用管理，并确保在Node-API模块代码中正确地处理ArkTS对象的生命周期。使用场景如下： +以下Node-API接口用于ArkTS对象的引用管理，确保在Node-API模块代码中正确处理ArkTS对象的生命周期。使用场景如下： | 接口 | 描述 | | -------- | -------- | -| napi_open_handle_scope、napi_close_handle_scope | 主要用于管理ArkTS对象的生命周期，确保在Node-API模块代码中使用ArkTS对象时能够正确地进行内存管理。当在Node-API模块中处理ArkTS对象时，需要创建一个临时的作用域来存储对象的引用，以便在执行期间正确访问这些对象，并在执行结束后关闭这个handle scope。 | -| napi_open_escapable_handle_scope、napi_close_escapable_handle_scope | 当在Node-API模块中编写函数实现，需要将函数在ArkTS中返回的对象从函数的作用域正确地返回到函数被调用的外部作用域中。 | -| napi_escape_handle | 需要将ArkTS对象的生命周期提升到父作用域中，避免对象被意外释放。 | -| napi_create_reference、napi_delete_reference | 主要用于在Node-API模块代码中管理ArkTS对象的引用，以确保对象的生命周期符合插件的需求。 | -| napi_reference_ref、napi_reference_unref | 主要用于管理ArkTS对象引用的引用计数，以确保在多个地方共享引用时引用计数能够正确地增加和减少。 | -| napi_get_reference_value | 主要用于在Node-API模块代码中获取与引用相关联的ArkTS对象，以便在Node-API模块中对其进行操作。 | -| napi_add_finalizer | 在需要在ArkTS对象被垃圾回收前执行一些清理或释放资源的情况下，确保资源的正确释放和管理。 | +| napi_open_handle_scope、napi_close_handle_scope | 主要用于管理ArkTS对象的生命周期，确保在Node-API模块代码中使用ArkTS对象时能够正确管理内存。在Node-API模块中处理ArkTS对象时，创建临时handle scope来存储对象的引用，以便在执行期间正确访问这些对象，并在执行结束后关闭handle scope。 | +| napi_open_escapable_handle_scope、napi_close_escapable_handle_scope | 当在Node-API模块中编写函数实现，需要将函数在ArkTS中返回的对象从函数的handle scope正确地返回到函数被调用的外部handle scope中。 | +| napi_escape_handle | 将ArkTS对象的生命周期提升到父作用域，避免对象被意外释放。 | +| napi_create_reference、napi_delete_reference | 用于管理ArkTS对象的引用，以确保对象的生命周期符合插件需求。 | +| napi_reference_ref、napi_reference_unref | 用于管理ArkTS对象引用的引用计数，确保在多个地方共享引用时引用计数正确增加和减少。 | +| napi_get_reference_value | 用于在Node-API模块代码中获取与引用相关联的ArkTS对象，以便在Node-API模块中对其进行操作。 | +| napi_add_finalizer | 在ArkTS对象被垃圾回收前执行清理或释放资源，确保资源的正确释放和管理。 | ## 使用示例 @@ -40,8 +40,8 @@ Node-API接口开发流程参考[使用Node-API实现跨语言交互开发流程 ### napi_open_handle_scope、napi_close_handle_scope -通过接口napi_open_handle_scope创建一个上下文环境使用。需要使用napi_close_handle_scope进行关闭。用于管理ArkTS对象的生命周期确保在Node-API模块代码处理ArkTS对象时能够正确地管理其句柄，以避免出现对象错误回收的问题。 -需要注意的是合理使用napi_open_handle_scope和napi_close_handle_scope管理napi_value的生命周期，做到生命周期最小化，避免发生内存泄漏问题。 +通过接口napi_open_handle_scope创建一个上下文环境，需要使用napi_close_handle_scope进行关闭。以管理ArkTS对象的生命周期，确保在Node-API模块代码处理ArkTS对象时能够正确管理其句柄，避免对象错误回收。 +需要注意的是，合理使用napi_open_handle_scope和napi_close_handle_scope管理napi_value的生命周期，以实现生命周期最小化，避免内存泄漏。 代码部分也可参考下面链接： [生命周期管理](napi-guidelines.md#生命周期管理) @@ -116,8 +116,8 @@ try { ### napi_open_escapable_handle_scope、napi_close_escapable_handle_scope、napi_escape_handle -通过接口napi_open_escapable_handle_scope创建出一个可逃逸的handel scope，可将范围内声明的值返回到父作用域。需要使用napi_close_escapable_handle_scope进行关闭。napi_escape_handle用于提升传入的ArkTS对象的生命周期到其父作用域。 -通过上述接口可以更灵活的使用管理传入的ArkTS对象，特别是在处理跨作用域的值传递时非常有用。 +通过接口napi_open_escapable_handle_scope创建一个可逃逸的handle scope，可将范围内声明的值返回到父作用域。需要使用napi_close_escapable_handle_scope进行关闭。napi_escape_handle用于提升传入的ArkTS对象的生命周期到其父作用域。 +通过上述接口可以更灵活的使用和管理传入的ArkTS对象，特别是在处理跨作用域的值传递时。 cpp部分代码 @@ -170,11 +170,11 @@ try { ### napi_create_reference、napi_delete_reference -为Object创建一个reference，以延长其生命周期。调用者需要自己管理reference生命周期。可以调用napi_delete_reference删除传入的reference。 +为Object创建一个reference，以延长其生命周期。调用者需自行管理reference生命周期。可以调用napi_delete_reference删除传入的reference。 ### napi_reference_ref、napi_reference_unref -增加/减少传入的reference的引用计数，并获取新的计数。 +增加或减少传入的reference的引用计数，并获取新的计数。 ### napi_get_reference_value @@ -182,15 +182,15 @@ try { > **说明** > -> 由于弱引用（引用计数为0的napi_ref）的释放与gc回收js对象并非同时发生。 +> 由于弱引用（引用计数为0的napi_ref）的释放与gc回收js对象不同时发生。 > -> 因此可能在弱引用被释放前，js对象已经被回收。 +> 因此在弱引用被释放前，js对象可能已经被回收。 > -> 这意味着你可能在napi_ref有效的情况下，通过本接口获取到一个空指针。 +> 这意味着在napi_ref有效的情况下，通过本接口可能获取到空指针。 ### napi_add_finalizer -当ArkTS Object中的对象被垃圾回收时调用注册的napi_add_finalizer回调。 +当ArkTS Object中的对象被垃圾回收时，会调用注册的napi_add_finalizer回调。 cpp部分代码 diff --git a/zh-cn/application-dev/napi/use-napi-process.md b/zh-cn/application-dev/napi/use-napi-process.md index a577daa05acd155c6537a3640ea43d914eeef7e8..7f55ebe45a3f8cd972017567d49d3643aae39ddb 100644 --- a/zh-cn/application-dev/napi/use-napi-process.md +++ b/zh-cn/application-dev/napi/use-napi-process.md @@ -1,7 +1,7 @@ # 使用Node-API实现跨语言交互开发流程 -使用Node-API实现跨语言交互，首先需要按照Node-API的机制实现模块的注册和加载等相关动作。 +使用Node-API实现跨语言交互，首先需要按照其机制实现模块的注册和加载等相关动作。 - **ArkTS/JS侧**：实现C++方法的调用。代码比较简单，import一个对应的so库后，即可调用C++方法。 @@ -9,7 +9,7 @@ - **Native侧**：.cpp文件，实现模块的注册。需要提供注册lib库的名称，并在注册回调方法中定义接口的映射关系，即Native方法及对应的JS/ArkTS接口名称等。 -此处以在ArkTS/JS侧实现add()接口、在Native侧实现Add()接口，从而实现跨语言交互为例，呈现使用Node-API进行跨语言交互的流程。 +以在ArkTS/JS侧实现add()接口，在Native侧实现Add()接口为例，展示使用Node-API进行跨语言交互的流程。 ## 创建Native C++工程 @@ -37,16 +37,16 @@ .nm_filename = nullptr, .nm_register_func = Init, .nm_modname = "entry", - .nm_priv = ((void*)0), + .nm_priv = nullptr, .reserved = {0}, }; // 加载so时，该函数会自动被调用，将上述demoModule模块注册到系统中。 extern "C" __attribute__((constructor)) void RegisterDemoModule() { napi_module_register(&demoModule); - } + } ``` -注：以上代码无须复制，创建Native C++工程以后在napi_init.cpp代码中已配置好。 +注：以上代码无须复制，创建Native C++工程后，napi_init.cpp代码中已配置好。 - 模块初始化 @@ -71,7 +71,7 @@ ``` -- 在index.d.ts文件中，提供JS侧的接口方法。 +- 在index.d.ts文件中提供JS侧的接口方法。 ``` // entry/src/main/cpp/types/libentry/index.d.ts @@ -109,7 +109,7 @@ target_link_libraries(entry PUBLIC libace_napi.z.so) ``` -- 实现Native侧的CallNative以及NativeCallArkTS接口。具体代码如下： +- 实现Native侧的CallNative和NativeCallArkTS接口。具体代码如下： ``` // entry/src/main/cpp/napi_init.cpp @@ -202,7 +202,7 @@ struct Index { ### SO命名规则 -导入使用的模块名和注册时的模块名大小写保持一致，如模块名为entry，则so的名字为libentry.so，napi_module中nm_modname字段应为entry，ArkTS侧使用时写作：import xxx from 'libentry.so'。 +导入使用的模块名和注册时的模块名大小写必须一致，例如，如果模块名为entry，则so的名字为libentry.so，napi_module中nm_modname字段应为entry，ArkTS 侧使用时的语句为：import xxx from 'libentry.so'。 ### 注册建议 @@ -216,8 +216,8 @@ struct Index { 每个引擎实例对应一个JS线程，实例上的对象不能跨线程操作，否则会引起应用crash。使用时需要遵循如下原则： -- Node-API接口只能在JS线程使用。 -- Native接口入参env与特定JS线程绑定只能在创建时的线程使用。 -- 使用Node-API接口创建的数据需在env完全销毁前进行释放，避免内存泄漏。此外，在napi_env销毁后访问/使用这些数据，可能会导致进程崩溃。 +- Node-API接口仅限JS线程中使用。 +- Native接口的入参env与特定JS线程绑定，仅在创建时的线程中使用。 +- 使用Node-API接口创建的数据需在env销毁前释放，避免内存泄漏。在napi_env销毁后访问这些数据，可能导致进程崩溃。 部分常见错误用法已增加维测手段覆盖，详见[使用Node-API接口产生的异常日志/崩溃分析](use-napi-about-crash.md)。