鸿蒙（API 12 Beta2版）NDK开发【Node-API支持的数据类型和接口】

Node-API支持的数据类型和接口

Node-API的数据类型

napi_status

是一个枚举数据类型，表示Node-API接口返回的状态信息。

每当调用一个Node-API函数，都会返回该值，表示操作成功与否的相关信息。

typedef enum {
    napi_ok,
    napi_invalid_arg,
    napi_object_expected,
    napi_string_expected,
    napi_name_expected,
    napi_function_expected,
    napi_number_expected,
    napi_boolean_expected,
    napi_array_expected,
    napi_generic_failure,
    napi_pending_exception,
    napi_cancelled,
    napi_escape_called_twice,
    napi_handle_scope_mismatch,
    napi_callback_scope_mismatch,
    napi_queue_full,
    napi_closing,
    napi_bigint_expected,
    napi_date_expected,
    napi_arraybuffer_expected,
    napi_detachable_arraybuffer_expected,
    napi_would_deadlock, /* unused */
    napi_no_external_buffers_allowed,
    napi_cannot_run_js
} napi_status;
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

napi_extended_error_info

一个结构体，在调用函数不成功时存储了较为详细的错误信息。

typedef struct {
    const char *error_message;
    void *engine_reserved;
    uint32_t engine_error_code;
    napi_status error_code;
} napi_extended_error_info;
1
2
3
4
5
6

napi_value

在C++代码中，表示一个JavaScript值。

napi_env

• 用于表示Node-API执行时的上下文，Native侧函数入参，并传递给函数中的Node-API接口。
• napi_env与JS线程绑定，JS线程退出后，napi_env将失效。
• 禁止缓存napi_env，禁止在不同Worker中传递napi_env。

napi_threadsafe_function

napi_threadsafe_function用来创建一个线程安全的JavaScript函数，可以在不同的线程中调用。可以用于将异步操作的结果传递给JavaScript环境，例如从另一个线程中读取数据或执行计算密集型操作。此外，它还可以用于从JavaScript环境中调用C++代码中的函数，以便在另一个线程中执行。通过使用napi_threadsafe_function，可以实现JavaScript和C++之间的高效通信，同时保持线程安全性。

napi_threadsafe_function_release_mode

该枚举类型定义了两个常量，用于指定在何时释放线程安全函数的回调函数。

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode;
1
2
3
4

该值会传给napi_release_threadsafe_function。

napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode);
1
2

• mode值为napi_tsfn_release时：表示当前线程不再调用此tsfn。

• mode值为napi_tsfn_abort时：表示除了当前线程，其他线程不能再调用此tsfn。

  如果设置为napi_tsfn_abort，利用napi_call_threadsafe_function接口调用此tsfn时将返回napi_closing，tsfn函数并不会被放入queue中。

napi_threadsafe_function_call_mode

该枚举类型定义了两个常量，用于指定线程安全函数的调用模式。

数据结构如下所示：

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode;
1
2
3
4

• napi_tsfn_nonblocking：napi_call_threadsafe_function是非阻塞的，如果队列已满，则返回napi_queue_full，从而阻止数据添加到队列中。
• napi_tsfn_blocking：napi_call_threadsafe_function是阻塞的，直至队列中有空间可用。

内存管理类型

Node-API包含以下内存管理类型：

napi_handle_scope

napi_handle_scope数据类型是用来管理JavaScript对象的生命周期的。它允许JavaScript对象在一定范围内保持活动状态，以便在JavaScript代码中使用。在创建napi_handle_scope时，所有在该范围内创建的JavaScript对象都会保持活动状态，直到结束。这样可以避免在JavaScript代码中使用已经被释放的对象，从而提高代码的可靠性和性能。

napi_escapable_handle_scope

• 由napi_open_escapable_handle_scope接口创建，由napi_close_escapable_handle_scope接口关闭。
• 表示一种特殊类型的句柄范围，用于将在escapable_handle_scope范围内创建的值返回给父scope。
• 用于napi_escape_handle接口，将escape_handle_scope提升到JS对象，以便在外部作用域使用。

napi_ref

指向napi_value，允许用户管理JavaScript值的生命周期。

napi_type_tag

该结构体定义了一个包含两个无符号64位整数的类型标签，用于标识一个Node-API值的类型信息。

typedef struct {
  uint64_t lower;
  uint64_t upper;
} napi_type_tag;
1
2
3
4

• 存储了两个无符号64位整数的128位值，用它来标记JavaScript对象，确保它们属于某种类型。
• 比napi_instanceof更强的类型检查，如果对象的原型被操纵，napi_instanceof可能会报告误报。
• type_tag与napi_wrap结合非常有用，因为它确保从包装对象检索的指针可以安全地转换为与先前应用于JavaScript对象的类型标记相对应的Native类型。

napi_async_cleanup_hook_handle

napi_async_cleanup_hook_handle用于注册异步操作的回调函数。它主要用于在异步操作完成或被取消时执行清理操作，例如释放资源或撤销操作。使用napi_async_cleanup_hook_handle可以确保在异步操作完成或被取消时，相关资源得到正确的释放和清理，从而避免内存泄漏等问题。

回调类型

Node-API包含以下回调类型：

napi_callback_info

Native侧获取JS侧参数信息，传递给napi_get_cb_info，用于获取JS侧入参信息。

napi_callback

表示用户定义的Native函数，暴露给JavaScript，即JS侧调用的接口；一般不在此callback中创建handle或者callback scope。

基本用法如下：

typedef napi_value (*napi_callback)(napi_env, napi_callback_info);
1

napi_finalize

函数指针，用于传入napi_create_threadsafe_function和napi_set_instance_data接口。napi_finalize在对象被回收时会被调用。

napi_async_execute_callback

函数指针，用于napi_create_async_work接口。

• 异步执行的Native函数，从工作池线程调用，可与主事件循环线程并行执行。
• 函数实现中必须避免执行JavaScript或与JavaScript对象交互的Node-API调用。
• Node-API调用可以在napi_async_complete_callback中执行。

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,…)接口。

napi_cleanup_hook

函数指针，用于napi_add_env_cleanup_hook接口，当环境销毁时会被执行。

napi_async_cleanup_hook

函数指针，用于napi_add_async_cleanup_hook接口，当环境销毁时会被执行。

调度优先级

QoS决定了线程调度的优先级，等级定义如下：

typedef enum {
  napi_qos_background = 0,
  napi_qos_utility = 1,
  napi_qos_default = 2,
  napi_qos_user_initiated = 3,
} napi_qos_t;
1
2
3
4
5
6

事件循环模式

napi提供了运行底层事件循环的两种模式, 其定义如下：

typedef enum {
    napi_event_mode_default = 0,
    napi_event_mode_nowait = 1,
} napi_event_mode;
1
2
3
4

线程安全任务优先级

napi提供了线程安全任务的优先级, 底层任务队列中的任务会根据其优先级被依次执行, 优先级的定义如下：

typedef enum {
    napi_priority_immediate = 0,
    napi_priority_high = 1,
    napi_priority_low = 2,
    napi_priority_idle = 3,
} napi_task_priority;
1
2
3
4
5
6

支持的Node-API接口

Node-API接口在Node.js提供的原生模块基础上扩展，目前支持部分接口，具体可见下文。

异步安全线程相关

buffer相关

string相关

date相关

arraybuffer相关

module相关

生命周期相关

promise相关

array相关

primitive相关

class相关

object相关

bigint相关

异常和错误相关

属性相关

异步任务相关

自定义异步操作

判断给定的两个JS value是否严格相等

uv相关

函数调用

扩展能力

[组件扩展的符号列表]

napi_queue_async_work_with_qos

napi_status napi_queue_async_work_with_qos(napi_env env,
                                           napi_async_work work,
                                           napi_qos_t qos);
1
2
3

用法同napi_queue_async_work，但可以指定QoS等级。

napi_run_script_path

napi_status napi_run_script_path(napi_env env,
                                 const char* abcPath,
                                 napi_value* result);
1
2
3

napi_load_module

napi_status napi_load_module(napi_env env,
                             const char* path,
                             napi_value* result);
1
2
3

napi_create_object_with_properties

napi_status napi_create_object_with_properties(napi_env env,
                                               napi_value* result,
                                               size_t property_count,
                                               const napi_property_descriptor* properties);
1
2
3
4

napi_create_object_with_named_properties

napi_status napi_create_object_with_named_properties(napi_env env,
                                                     napi_value* result,
                                                     size_t property_count,
                                                     const char** keys,
                                                     const napi_value* values);
1
2
3
4
5

napi_coerce_to_native_binding_object

napi_status napi_coerce_to_native_binding_object(napi_env env,
                                                 napi_value js_object,
                                                 napi_native_binding_detach_callback detach_cb,
                                                 napi_native_binding_attach_callback attach_cb,
                                                 void* native_object,
                                                 void* hint);  
1
2
3
4
5
6

napi_run_event_loop

napi_status napi_run_event_loop(napi_env env, napi_event_mode mode);
1

napi_stop_event_loop

napi_status napi_stop_event_loop(napi_env env);
1

napi_serialize

napi_status napi_serialize(napi_env env,
                           napi_value object,
                           napi_value transfer_list,
                           napi_value clone_list,
                           void** result);
1
2
3
4
5

napi_deserialize

napi_status napi_deserialize(napi_env env, void* buffer, napi_value* object);
1

napi_delete_serialization_data

napi_status napi_delete_serialization_data(napi_env env, void* buffer);
1

napi_call_threadsafe_function_with_priority

napi_status napi_call_threadsafe_function_with_priority(napi_threadsafe_function func,
                                                        void *data,
                                                        napi_task_priority priority,
                                                        bool isTail);
1
2
3
4

napi_is_sendable

napi_status napi_is_sendable(napi_env env, napi_value value, bool* result);
1

napi_define_sendable_class

napi_status napi_define_sendable_class(napi_env env,
                                       const char* utf8name,
                                       size_t length,
                                       napi_callback constructor,
                                       void* data,
                                       size_t property_count,
                                       const napi_property_descriptor* properties,
                                       napi_value parent,
                                       napi_value* result);
1
2
3
4
5
6
7
8
9

napi_create_sendable_object_with_properties

napi_status napi_create_sendable_object_with_properties(napi_env env,
                                                        size_t property_count,
                                                        const napi_property_descriptor* properties,
                                                        napi_value* result);
1
2
3
4

napi_create_sendable_array

napi_status napi_create_sendable_array(napi_env env, napi_value* result);
1

napi_create_sendable_array_with_length

napi_status napi_create_sendable_array_with_length(napi_env env, size_t length, napi_value* result);
1

napi_create_sendable_arraybuffer

napi_status napi_create_sendable_arraybuffer(napi_env env, size_t byte_length, void** data, napi_value* result);
1

napi_create_sendable_typedarray

napi_status napi_create_sendable_typedarray(napi_env env,
                                            napi_typedarray_type type,
                                            size_t length,
                                            napi_value arraybuffer,
                                            size_t byte_offset,
                                            napi_value* result);
1
2
3
4
5
6

napi_wrap_sendable

napi_status napi_wrap_sendable(napi_env env,
                               napi_value js_object,
                               void* native_object,
                               napi_finalize finalize_cb,
                               void* finalize_hint);
1
2
3
4
5

napi_wrap_sendable_with_size

napi_status napi_wrap_sendable_with_size(napi_env env,
                                         napi_value js_object,
                                         void* native_object,
                                         napi_finalize finalize_cb,
                                         void* finalize_hint,
                                         size_t native_binding_size);
1
2
3
4
5
6

napi_unwrap_sendable

napi_status napi_unwrap_sendable(napi_env env, napi_value js_object, void** result);
1

napi_remove_wrap_sendable

napi_status napi_remove_wrap_sendable(napi_env env, napi_value js_object, void** result);
1

环境生命周期

对象生命周期管理

ArkTs基础运行时环境

其他实用工具

最后呢

很多开发朋友不知道需要学习那些鸿蒙技术？鸿蒙开发岗位需要掌握那些核心技术点？为此鸿蒙的开发学习必须要系统性的进行。

而网上有关鸿蒙的开发资料非常的少，假如你想学好鸿蒙的应用开发与系统底层开发。你可以参考这份资料，少走很多弯路，节省没必要的麻烦。由两位前阿里高级研发工程师联合打造的《鸿蒙NEXT星河版OpenHarmony开发文档》里面内容包含了（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、Harmony南向开发、鸿蒙项目实战等等）鸿蒙（Harmony NEXT）技术知识点

如果你是一名Android、Java、前端等等开发人员，想要转入鸿蒙方向发展。可以直接领取这份资料辅助你的学习。下面是鸿蒙开发的学习路线图。

针对鸿蒙成长路线打造的鸿蒙学习文档。话不多说，我们直接看详细鸿蒙（OpenHarmony ）手册（共计1236页）与鸿蒙（OpenHarmony ）开发入门视频，帮助大家在技术的道路上更进一步。

• 《鸿蒙 (OpenHarmony)开发学习视频》
• 《鸿蒙生态应用开发V2.0白皮书》
• 《鸿蒙 (OpenHarmony)开发基础到实战手册》
• OpenHarmony北向、南向开发环境搭建
• 《鸿蒙开发基础》
• 《鸿蒙开发进阶》
• 《鸿蒙开发实战》

总结

鸿蒙—作为国家主力推送的国产操作系统。部分的高校已经取消了安卓课程，从而开设鸿蒙课程；企业纷纷跟进启动了鸿蒙研发。

并且鸿蒙是完全具备无与伦比的机遇和潜力的；预计到年底将有 5,000 款的应用完成原生鸿蒙开发，未来将会支持 50 万款的应用。那么这么多的应用需要开发，也就意味着需要有更多的鸿蒙人才。鸿蒙开发工程师也将会迎来爆发式的增长，学习鸿蒙势在必行！ 自↓↓↓拿