Node.js v25.0.0 文档

node-gyp#

node-gyp 是一个基于 Google 的 GYP 工具的 gyp-next 分支的构建系统，并与 npm 捆绑在一起。GYP，因此 node-gyp，要求安装 Python。

历史上，node-gyp 一直是构建原生插件的首选工具。它得到了广泛的采用和文档支持。然而，一些开发人员在使用 node-gyp 时遇到了限制。

CMake.js#

CMake.js 是一个基于 CMake 的替代构建系统。

CMake.js 是已经使用 CMake 的项目或受 node-gyp 限制影响的开发人员的不错选择。build_with_cmake 是一个基于 CMake 的原生插件项目示例。

node-pre-gyp#

node-pre-gyp 是一个基于 node-gyp 的工具，增加了将二进制文件上传到开发人员选择的服务器的能力。node-pre-gyp 对上传二进制文件到 Amazon S3 有特别好的支持。

prebuild#

prebuild 是一个支持使用 node-gyp 或 CMake.js 进行构建的工具。与支持各种服务器的 node-pre-gyp 不同，prebuild 只将二进制文件上传到 GitHub releases。prebuild 是使用 CMake.js 的 GitHub 项目的不错选择。

prebuildify#

prebuildify 是一个基于 node-gyp 的工具。prebuildify 的优点是，当原生插件上传到 npm 时，构建的二进制文件会与原生插件捆绑在一起。二进制文件从 npm 下载，并在安装原生插件时立即可供模块用户使用。

napi_handle_scope#

这是一种抽象，用于控制和修改在特定作用域内创建的对象的生命周期。通常，Node-API 值是在句柄作用域的上下文中创建的。当从 JavaScript 调用原生方法时，将存在一个默认句柄作用域。如果用户未显式创建新的句柄作用域，Node-API 值将在默认句柄作用域中创建。对于原生方法执行之外的任何代码调用（例如，在 libuv 回调调用期间），模块必须在调用任何可能导致创建 JavaScript 值的函数之前创建一个作用域。

句柄作用域使用 napi_open_handle_scope 创建，并使用 napi_close_handle_scope 销毁。关闭作用域可以向垃圾回收器指示，在句柄作用域生命周期内创建的所有 napi_values 不再从当前栈帧中引用。

有关更多详细信息，请查阅对象生命周期管理。

napi_escapable_handle_scope#

可逃逸句柄作用域是一种特殊类型的句柄作用域，用于将特定句柄作用域内创建的值返回到父作用域。

napi_ref#

这是用于引用 napi_value 的抽象。这允许用户管理 JavaScript 值的生命周期，包括显式定义其最短生命周期。

有关更多详细信息，请查阅对象生命周期管理。

napi_type_tag#

一个 128 位的值，存储为两个无符号的 64 位整数。它用作 UUID，可用于“标记”JavaScript 对象或外部对象，以确保它们是特定类型。这比napi_instanceof更强的检查，因为后者如果对象的原型被操作可能会报告误报。类型标记与napi_wrap结合使用最有用，因为它确保从包装对象检索到的指针可以安全地转换为与之前应用于 JavaScript 对象的类型标记相对应的原生类型。

typedef struct {
  uint64_t lower;
  uint64_t upper;
} napi_type_tag; copy

napi_async_cleanup_hook_handle#

由 napi_add_async_cleanup_hook 返回的不透明值。当异步清理事件链完成时，必须将其传递给 napi_remove_async_cleanup_hook。

napi_callback_info#

传递给回调函数的不透明数据类型。它可用于获取有关调用回调的上下文的附加信息。

napi_callback#

函数指针类型，用于通过 Node-API 公开给 JavaScript 的用户提供的原生函数。回调函数应满足以下签名：

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

除非出于对象生命周期管理中讨论的原因，否则在 napi_callback 内部创建句柄和/或回调作用域不是必需的。

node_api_basic_finalize#

插件提供的函数指针类型，允许用户在外部拥有的数据准备好被清理时收到通知，因为与其关联的对象已被垃圾回收。用户必须提供一个满足以下签名的函数，该函数将在对象被回收时调用。目前，node_api_basic_finalize 可用于发现何时回收具有外部数据的对象。

typedef void (*node_api_basic_finalize)(node_api_basic_env env,
                                      void* finalize_data,
                                      void* finalize_hint); copy

除非出于对象生命周期管理中讨论的原因，否则在函数体内部创建句柄和/或回调作用域不是必需的。

由于这些函数可能在 JavaScript 引擎处于无法执行 JavaScript 代码的状态下调用，因此只能调用接受 node_api_basic_env 作为其第一个参数的 Node-API。在当前垃圾回收周期完成后，可以使用 node_api_post_finalizer 来安排需要访问 JavaScript 引擎状态的 Node-API 调用运行。

在node_api_create_external_string_latin1和node_api_create_external_string_utf16的情况下，env参数可能为null，因为外部字符串可以在环境关闭的后期被收集。

变更历史

• 实验性 (NAPI_EXPERIMENTAL)

  只能调用接受 node_api_basic_env 作为其第一个参数的 Node-API，否则应用程序将以适当的错误消息终止。此功能可以通过定义 NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT 来关闭。

napi_finalize#

插件提供的函数指针类型，允许用户在垃圾回收事件响应中，在垃圾回收周期完成后，安排一组对 Node-API 的调用。这些函数指针可以与 node_api_post_finalizer 一起使用。

typedef void (*napi_finalize)(napi_env env,
                              void* finalize_data,
                              void* finalize_hint); copy

变更历史

• 实验性 (已定义 NAPI_EXPERIMENTAL)

  这种类型的函数可能不再用作终结器，除了与 node_api_post_finalizer 一起使用。必须改用 node_api_basic_finalize。此功能可以通过定义 NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT 来关闭。

napi_async_execute_callback#

与支持异步操作的函数一起使用的函数指针。回调函数必须满足以下签名：

typedef void (*napi_async_execute_callback)(napi_env env, void* data); copy

此函数的实现必须避免进行执行 JavaScript 或与 JavaScript 对象交互的 Node-API 调用。Node-API 调用应改在 napi_async_complete_callback 中。请勿使用 napi_env 参数，因为它很可能导致 JavaScript 的执行。

napi_async_complete_callback#

与支持异步操作的函数一起使用的函数指针。回调函数必须满足以下签名：

typedef void (*napi_async_complete_callback)(napi_env env,
                                             napi_status status,
                                             void* data); copy

除非出于对象生命周期管理中讨论的原因，否则在函数体内部创建句柄和/或回调作用域不是必需的。

napi_threadsafe_function_call_js#

与异步线程安全函数调用一起使用的函数指针。回调将在主线程上调用。其目的是使用从辅助线程通过队列到达的数据项来构建调用 JavaScript 所需的参数，通常通过 napi_call_function，然后进行 JavaScript 调用。

通过队列从辅助线程到达的数据在 data 参数中给出，要调用的 JavaScript 函数在 js_callback 参数中给出。

Node-API 在调用此回调之前设置环境，因此通过 napi_call_function 而不是通过 napi_make_callback 调用 JavaScript 函数就足够了。

回调函数必须满足以下签名：

typedef void (*napi_threadsafe_function_call_js)(napi_env env,
                                                 napi_value js_callback,
                                                 void* context,
                                                 void* data); copy

• [in] env: 用于 API 调用的环境，如果线程安全函数正在销毁且 data 可能需要释放，则为 NULL。
• [in] js_callback: 要调用的 JavaScript 函数，如果线程安全函数正在销毁且 data 可能需要释放，则为 NULL。如果创建线程安全函数时没有 js_callback，它也可以是 NULL。
• [in] context: 创建线程安全函数时使用的可选数据。
• [in] data: 由辅助线程创建的数据。回调负责将此原生数据转换为 JavaScript 值（使用 Node-API 函数），这些值可以在调用 js_callback 时作为参数传递。此指针完全由线程和此回调管理。因此，此回调应释放数据。

除非出于对象生命周期管理中讨论的原因，否则在函数体内部创建句柄和/或回调作用域不是必需的。

napi_cleanup_hook#

与 napi_add_env_cleanup_hook 一起使用的函数指针。当环境被销毁时将调用它。

回调函数必须满足以下签名：

typedef void (*napi_cleanup_hook)(void* data); copy

• [in] data: 传递给 napi_add_env_cleanup_hook 的数据。

napi_async_cleanup_hook#

与 napi_add_async_cleanup_hook 一起使用的函数指针。当环境被销毁时将调用它。

回调函数必须满足以下签名：

typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
                                        void* data); copy

• [in] handle: 在异步清理完成后必须传递给 napi_remove_async_cleanup_hook 的句柄。
• [in] data: 传递给 napi_add_async_cleanup_hook 的数据。

函数体应启动异步清理操作，在异步清理完成后，必须将 handle 传递给 napi_remove_async_cleanup_hook。

napi_get_last_error_info#

napi_status
napi_get_last_error_info(node_api_basic_env env,
                         const napi_extended_error_info** result); copy

• [in] env: 调用 API 的环境。
• [out] result: 包含更多错误信息的 napi_extended_error_info 结构。

如果 API 成功，则返回 napi_ok。

此 API 检索包含上次发生错误信息的 napi_extended_error_info 结构。

返回的 napi_extended_error_info 的内容仅在对同一 env 调用 Node-API 函数之前有效。这包括对 napi_is_exception_pending 的调用，因此通常需要复制信息以便以后使用。error_message 中返回的指针指向一个静态定义的字符串，因此如果在调用另一个 Node-API 函数之前已将其从 error_message 字段（将被覆盖）中复制出来，则使用该指针是安全的。

不要依赖任何扩展信息的内容或格式，因为它不受 SemVer 约束，并且可能随时更改。它仅用于日志记录目的。

即使有待处理的 JavaScript 异常，也可以调用此 API。

napi_throw#

NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); copy

• [in] env: 调用 API 的环境。
• [in] error: 要抛出的 JavaScript 值。

如果 API 成功，则返回 napi_ok。

此 API 抛出提供的 JavaScript 值。

napi_throw_error#

NAPI_EXTERN napi_status napi_throw_error(napi_env env,
                                         const char* code,
                                         const char* msg); copy

• [in] env: 调用 API 的环境。
• [in] code: 要在错误上设置的可选错误代码。
• [in] msg: 表示与错误关联文本的 C 字符串。

如果 API 成功，则返回 napi_ok。

此 API 抛出带有提供的文本的 JavaScript Error。

napi_throw_type_error#

NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
                                              const char* code,
                                              const char* msg); copy

• [in] env: 调用 API 的环境。
• [in] code: 要在错误上设置的可选错误代码。
• [in] msg: 表示与错误关联文本的 C 字符串。

如果 API 成功，则返回 napi_ok。

此 API 抛出带有提供的文本的 JavaScript TypeError。

napi_throw_range_error#

NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
                                               const char* code,
                                               const char* msg); copy

• [in] env: 调用 API 的环境。
• [in] code: 要在错误上设置的可选错误代码。
• [in] msg: 表示与错误关联文本的 C 字符串。

如果 API 成功，则返回 napi_ok。

此 API 抛出带有提供的文本的 JavaScript RangeError。

node_api_throw_syntax_error#

NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
                                                    const char* code,
                                                    const char* msg); copy

• [in] env: 调用 API 的环境。
• [in] code: 要在错误上设置的可选错误代码。
• [in] msg: 表示与错误关联文本的 C 字符串。

如果 API 成功，则返回 napi_ok。

此 API 抛出带有提供的文本的 JavaScript SyntaxError。

napi_is_error#

NAPI_EXTERN napi_status napi_is_error(napi_env env,
                                      napi_value value,
                                      bool* result); copy

• [in] env: 调用 API 的环境。
• [in] value: 要检查的 napi_value。
• [out] result: 如果 napi_value 表示错误，则设置为 true 的布尔值，否则为 false。

如果 API 成功，则返回 napi_ok。

此 API 查询 napi_value 以检查它是否表示错误对象。

napi_create_error#

NAPI_EXTERN napi_status napi_create_error(napi_env env,
                                          napi_value code,
                                          napi_value msg,
                                          napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] code: 可选的 napi_value，包含要与错误关联的错误代码字符串。
• [in] msg: 引用 JavaScript string 的 napi_value，用作 Error 的消息。
• [out] result: 表示已创建错误的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回带有提供的文本的 JavaScript Error。

napi_create_type_error#

NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
                                               napi_value code,
                                               napi_value msg,
                                               napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] code: 可选的 napi_value，包含要与错误关联的错误代码字符串。
• [in] msg: 引用 JavaScript string 的 napi_value，用作 Error 的消息。
• [out] result: 表示已创建错误的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回带有提供的文本的 JavaScript TypeError。

napi_create_range_error#

NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
                                                napi_value code,
                                                napi_value msg,
                                                napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] code: 可选的 napi_value，包含要与错误关联的错误代码字符串。
• [in] msg: 引用 JavaScript string 的 napi_value，用作 Error 的消息。
• [out] result: 表示已创建错误的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回带有提供的文本的 JavaScript RangeError。

node_api_create_syntax_error#

NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,
                                                     napi_value code,
                                                     napi_value msg,
                                                     napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] code: 可选的 napi_value，包含要与错误关联的错误代码字符串。
• [in] msg: 引用 JavaScript string 的 napi_value，用作 Error 的消息。
• [out] result: 表示已创建错误的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回带有提供的文本的 JavaScript SyntaxError。

napi_get_and_clear_last_exception#

napi_status napi_get_and_clear_last_exception(napi_env env,
                                              napi_value* result); copy

• [in] env: 调用 API 的环境。
• [out] result: 如果有异常待处理，则为异常，否则为 NULL。

如果 API 成功，则返回 napi_ok。

即使有待处理的 JavaScript 异常，也可以调用此 API。

napi_is_exception_pending#

napi_status napi_is_exception_pending(napi_env env, bool* result); copy

• [in] env: 调用 API 的环境。
• [out] result: 如果有异常待处理，则设置为 true 的布尔值。

如果 API 成功，则返回 napi_ok。

即使有待处理的 JavaScript 异常，也可以调用此 API。

napi_fatal_exception#

napi_status napi_fatal_exception(napi_env env, napi_value err); copy

• [in] env: 调用 API 的环境。
• [in] err: 传递给 'uncaughtException' 的错误。

在 JavaScript 中触发一个 'uncaughtException'。如果异步回调抛出异常且无法恢复，此功能非常有用。

napi_fatal_error#

NAPI_NO_RETURN void napi_fatal_error(const char* location,
                                     size_t location_len,
                                     const char* message,
                                     size_t message_len); copy

• [in] location: 发生错误的可选位置。
• [in] location_len: 位置的字节长度，如果以 null 结尾，则为 NAPI_AUTO_LENGTH。
• [in] message: 与错误关联的消息。
• [in] message_len: 消息的字节长度，如果以 null 结尾，则为 NAPI_AUTO_LENGTH。

函数调用不返回，进程将终止。

即使有待处理的 JavaScript 异常，也可以调用此 API。

napi_open_handle_scope#

NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
                                               napi_handle_scope* result); copy

• [in] env: 调用 API 的环境。
• [out] result: 表示新作用域的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 打开一个新的作用域。

napi_close_handle_scope#

NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
                                                napi_handle_scope scope); copy

• [in] env: 调用 API 的环境。
• [in] scope: 表示要关闭的作用域的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 关闭传入的作用域。作用域必须按照创建的相反顺序关闭。

即使有待处理的 JavaScript 异常，也可以调用此 API。

napi_open_escapable_handle_scope#

NAPI_EXTERN napi_status
    napi_open_escapable_handle_scope(napi_env env,
                                     napi_handle_scope* result); copy

• [in] env: 调用 API 的环境。
• [out] result: 表示新作用域的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 打开一个新作用域，其中一个对象可以被提升到外部作用域。

napi_close_escapable_handle_scope#

NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope); copy

• [in] env: 调用 API 的环境。
• [in] scope: 表示要关闭的作用域的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 关闭传入的作用域。作用域必须按照创建的相反顺序关闭。

即使有待处理的 JavaScript 异常，也可以调用此 API。

napi_escape_handle#

napi_status napi_escape_handle(napi_env env,
                               napi_escapable_handle_scope scope,
                               napi_value escapee,
                               napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] scope: 表示当前作用域的 napi_value。
• [in] escapee: 表示要逃逸的 JavaScript Object 的 napi_value。
• [out] result: 表示外部作用域中逃逸 Object 句柄的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 提升 JavaScript 对象的句柄，使其在外部作用域的生命周期内有效。每个作用域只能调用一次。如果调用多次，将返回错误。

即使有待处理的 JavaScript 异常，也可以调用此 API。

napi_create_reference#

NAPI_EXTERN napi_status napi_create_reference(napi_env env,
                                              napi_value value,
                                              uint32_t initial_refcount,
                                              napi_ref* result); copy

• [in] env: 调用 API 的环境。
• [in] value: 正在为其创建引用的 napi_value。
• [in] initial_refcount: 新引用的初始引用计数。
• [out] result: 指向新引用的 napi_ref。

如果 API 成功，则返回 napi_ok。

此 API 创建一个新引用，其引用计数为指定值，指向传入的值。

napi_delete_reference#

NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); copy

• [in] env: 调用 API 的环境。
• [in] ref: 要删除的 napi_ref。

如果 API 成功，则返回 napi_ok。

此 API 删除传入的引用。

即使有待处理的 JavaScript 异常，也可以调用此 API。

napi_reference_ref#

NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
                                           napi_ref ref,
                                           uint32_t* result); copy

• [in] env: 调用 API 的环境。
• [in] ref: 引用计数将递增的 napi_ref。
• [out] result: 新的引用计数。

如果 API 成功，则返回 napi_ok。

此 API 递增传入引用的引用计数并返回结果引用计数。

napi_reference_unref#

NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
                                             napi_ref ref,
                                             uint32_t* result); copy

• [in] env: 调用 API 的环境。
• [in] ref: 引用计数将递减的 napi_ref。
• [out] result: 新的引用计数。

如果 API 成功，则返回 napi_ok。

此 API 递减传入引用的引用计数并返回结果引用计数。

napi_get_reference_value#

NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
                                                 napi_ref ref,
                                                 napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] ref: 正在请求其对应值的 napi_ref。
• [out] result: 由 napi_ref 引用的 napi_value。

如果 API 成功，则返回 napi_ok。

如果仍然有效，此 API 返回表示与 napi_ref 关联的 JavaScript 值的 napi_value。否则，result 将为 NULL。

napi_add_env_cleanup_hook#

NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
                                                  napi_cleanup_hook fun,
                                                  void* arg); copy

注册 fun 作为当当前 Node.js 环境退出时，使用 arg 参数运行的函数。

可以安全地多次指定具有不同 arg 值的函数。在这种情况下，它也将被多次调用。多次提供相同的 fun 和 arg 值是不允许的，会导致进程中止。

钩子将以相反的顺序调用，即最近添加的钩子将首先调用。

可以使用 napi_remove_env_cleanup_hook 移除此钩子。通常，当添加此钩子的资源被拆除时，就会发生这种情况。

对于异步清理，可以使用 napi_add_async_cleanup_hook。

napi_remove_env_cleanup_hook#

NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
                                                     void (*fun)(void* arg),
                                                     void* arg); copy

注销 fun 作为当当前 Node.js 环境退出时，使用 arg 参数运行的函数。参数和函数值都必须完全匹配。

该函数必须最初通过 napi_add_env_cleanup_hook 注册，否则进程将中止。

napi_add_async_cleanup_hook#

NAPI_EXTERN napi_status napi_add_async_cleanup_hook(
    node_api_basic_env env,
    napi_async_cleanup_hook hook,
    void* arg,
    napi_async_cleanup_hook_handle* remove_handle); copy

• [in] env: 调用 API 的环境。
• [in] hook: 环境拆除时要调用的函数指针。
• [in] arg: 调用 hook 时要传递给它的指针。
• [out] remove_handle: 可选句柄，指向异步清理钩子。

注册 hook（类型为 napi_async_cleanup_hook 的函数），作为当当前 Node.js 环境退出时，使用 remove_handle 和 arg 参数运行的函数。

与 napi_add_env_cleanup_hook 不同，该钩子允许是异步的。

否则，行为通常与 napi_add_env_cleanup_hook 匹配。

如果 remove_handle 不为 NULL，则会存储一个不透明值，以后必须将其传递给 napi_remove_async_cleanup_hook，无论钩子是否已被调用。通常，当添加此钩子的资源被拆除时，就会发生这种情况。

napi_remove_async_cleanup_hook#

NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
    napi_async_cleanup_hook_handle remove_handle); copy

• [in] remove_handle: 使用 napi_add_async_cleanup_hook 创建的异步清理钩子的句柄。

注销与 remove_handle 对应的清理钩子。这将阻止钩子执行，除非它已经开始执行。对于从 napi_add_async_cleanup_hook 获取的任何 napi_async_cleanup_hook_handle 值，都必须调用此函数。

napi_key_collection_mode#

typedef enum {
  napi_key_include_prototypes,
  napi_key_own_only
} napi_key_collection_mode; copy

描述 Keys/Properties 过滤器枚举

napi_key_collection_mode 限制了收集属性的范围。

napi_key_own_only 仅将收集的属性限制为给定对象。napi_key_include_prototypes 也会包含对象原型链中的所有键。

napi_key_filter#

typedef enum {
  napi_key_all_properties = 0,
  napi_key_writable = 1,
  napi_key_enumerable = 1 << 1,
  napi_key_configurable = 1 << 2,
  napi_key_skip_strings = 1 << 3,
  napi_key_skip_symbols = 1 << 4
} napi_key_filter; copy

属性过滤器位标志。这与位运算符一起使用以构建复合过滤器。

napi_key_conversion#

typedef enum {
  napi_key_keep_numbers,
  napi_key_numbers_to_strings
} napi_key_conversion; copy

napi_key_numbers_to_strings 会将整数索引转换为字符串。napi_key_keep_numbers 会为整数索引返回数字。

napi_valuetype#

typedef enum {
  // ES6 types (corresponds to typeof)
  napi_undefined,
  napi_null,
  napi_boolean,
  napi_number,
  napi_string,
  napi_symbol,
  napi_object,
  napi_function,
  napi_external,
  napi_bigint,
} napi_valuetype; copy

描述 napi_value 的类型。这通常对应于 ECMAScript 语言规范 的 第语言类型 一节中描述的类型。除了该节中的类型之外，napi_valuetype 还可以表示带有外部数据的 Function 和 Object。

类型为 napi_external 的 JavaScript 值在 JavaScript 中表现为普通对象，不能在其上设置任何属性，也没有原型。

napi_typedarray_type#

typedef enum {
  napi_int8_array,
  napi_uint8_array,
  napi_uint8_clamped_array,
  napi_int16_array,
  napi_uint16_array,
  napi_int32_array,
  napi_uint32_array,
  napi_float32_array,
  napi_float64_array,
  napi_bigint64_array,
  napi_biguint64_array,
} napi_typedarray_type; copy

这表示 TypedArray 的底层二进制标量数据类型。此枚举的元素对应于 ECMAScript 语言规范 的 第 TypedArray 对象 一节。

napi_create_array#

napi_status napi_create_array(napi_env env, napi_value* result) copy

• [in] env: 调用 Node-API 的环境。
• [out] result: 表示 JavaScript Array 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回对应于 JavaScript Array 类型的 Node-API 值。JavaScript 数组在 ECMAScript 语言规范 的 第 Array 对象 一节中进行了描述。

napi_create_array_with_length#

napi_status napi_create_array_with_length(napi_env env,
                                          size_t length,
                                          napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] length: Array 的初始长度。
• [out] result: 表示 JavaScript Array 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回对应于 JavaScript Array 类型的 Node-API 值。Array 的长度属性设置为传入的 length 参数。但是，不保证在创建数组时 VM 会预分配底层缓冲区。该行为留给底层 VM 实现。如果缓冲区必须是一个可以被 C 直接读写 contiguous block of memory，请考虑使用 napi_create_external_arraybuffer。

JavaScript 数组在 ECMAScript 语言规范 的 第 Array 对象 一节中进行了描述。

napi_create_arraybuffer#

napi_status napi_create_arraybuffer(napi_env env,
                                    size_t byte_length,
                                    void** data,
                                    napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] length: 要创建的数组缓冲区的长度（以字节为单位）。
• [out] data: 指向 ArrayBuffer 底层字节缓冲区的指针。可以通过传递 NULL 来选择忽略 data。
• [out] result: 表示 JavaScript ArrayBuffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回对应于 JavaScript ArrayBuffer 的 Node-API 值。ArrayBuffer 用于表示固定长度的二进制数据缓冲区。它们通常用作 TypedArray 对象的后端缓冲区。分配的 ArrayBuffer 将具有一个底层字节缓冲区，其大小由传入的 length 参数确定。如果调用者希望直接操作缓冲区，则可选地将底层缓冲区返回给调用者。此缓冲区只能从原生代码直接写入。要从 JavaScript 写入此缓冲区，需要创建类型化数组或 DataView 对象。

JavaScript ArrayBuffer 对象在 ECMAScript 语言规范 的 第 ArrayBuffer 对象 一节中进行了描述。

napi_create_buffer#

napi_status napi_create_buffer(napi_env env,
                               size_t size,
                               void** data,
                               napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] size: 底层缓冲区的大小（以字节为单位）。
• [out] data: 指向底层缓冲区的原始指针。可以通过传递 NULL 来选择忽略 data。
• [out] result: 表示 node::Buffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 分配一个 node::Buffer 对象。虽然这仍然是一个完全支持的数据结构，但在大多数情况下，使用 TypedArray 就足够了。

napi_create_buffer_copy#

napi_status napi_create_buffer_copy(napi_env env,
                                    size_t length,
                                    const void* data,
                                    void** result_data,
                                    napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] size: 输入缓冲区的大小（以字节为单位）（应与新缓冲区的大小相同）。
• [in] data: 指向要复制的底层缓冲区的原始指针。
• [out] result_data: 指向新 Buffer 的底层数据缓冲区的指针。可以通过传递 NULL 来选择忽略 result_data。
• [out] result: 表示 node::Buffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 分配一个 node::Buffer 对象，并使用从传入缓冲区复制的数据对其进行初始化。虽然这仍然是一个完全支持的数据结构，但在大多数情况下，使用 TypedArray 就足够了。

napi_create_date#

napi_status napi_create_date(napi_env env,
                             double time,
                             napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] time: ECMAScript 时间值，自 1970 年 1 月 1 日 UTC 起的毫秒数。
• [out] result: 表示 JavaScript Date 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 不观察闰秒；它们被忽略，因为 ECMAScript 与 POSIX 时间规范保持一致。

此 API 分配一个 JavaScript Date 对象。

JavaScript Date 对象在 ECMAScript 语言规范 的 第 Date 对象 一节中进行了描述。

napi_create_external#

napi_status napi_create_external(napi_env env,
                                 void* data,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] data: 指向外部数据的原始指针。
• [in] finalize_cb: 可选回调，当外部值被收集时调用。napi_finalize 提供了更多详细信息。
• [in] finalize_hint: 在收集期间传递给终结回调的可选提示。
• [out] result: 表示外部值的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 分配一个附加了外部数据的 JavaScript 值。这用于通过 JavaScript 代码传递外部数据，以便以后可以通过使用 napi_get_value_external 的原生代码检索。

API 添加了一个 napi_finalize 回调，该回调将在刚刚创建的 JavaScript 对象被垃圾回收时调用。

创建的值不是对象，因此不支持额外的属性。它被认为是一种不同的值类型：使用外部值调用 napi_typeof() 会产生 napi_external。

napi_create_external_arraybuffer#

napi_status
napi_create_external_arraybuffer(napi_env env,
                                 void* external_data,
                                 size_t byte_length,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] external_data: 指向 ArrayBuffer 底层字节缓冲区的指针。
• [in] byte_length: 底层缓冲区的长度（以字节为单位）。
• [in] finalize_cb: 可选回调，当 ArrayBuffer 被收集时调用。napi_finalize 提供了更多详细信息。
• [in] finalize_hint: 在收集期间传递给终结回调的可选提示。
• [out] result: 表示 JavaScript ArrayBuffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

除了 Node.js 之外的一些运行时已放弃对外部缓冲区的支持。在 Node.js 之外的运行时上，此方法可能返回 napi_no_external_buffers_allowed 以指示不支持外部缓冲区。其中一个运行时是 Electron，如 issue electron/issues/35801 中所述。

为了保持与所有运行时的最广泛兼容性，您可以在包含 node-api 头文件之前在您的插件中定义 NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED。这样做将隐藏创建外部缓冲区的两个函数。这将确保如果您不小心使用了这些方法之一，会发生编译错误。

此 API 返回对应于 JavaScript ArrayBuffer 的 Node-API 值。ArrayBuffer 的底层字节缓冲区是外部分配和管理的。调用者必须确保字节缓冲区在终结回调被调用之前保持有效。

API 添加了一个 napi_finalize 回调，该回调将在刚刚创建的 JavaScript 对象被垃圾回收时调用。

JavaScript ArrayBuffer 在 ECMAScript 语言规范 的 第 ArrayBuffer 对象 一节中进行了描述。

napi_create_external_buffer#

napi_status napi_create_external_buffer(napi_env env,
                                        size_t length,
                                        void* data,
                                        napi_finalize finalize_cb,
                                        void* finalize_hint,
                                        napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] length: 输入缓冲区的大小（以字节为单位）（应与新缓冲区的大小相同）。
• [in] data: 指向要暴露给 JavaScript 的底层缓冲区的原始指针。
• [in] finalize_cb: 可选回调，当 ArrayBuffer 被收集时调用。napi_finalize 提供了更多详细信息。
• [in] finalize_hint: 在收集期间传递给终结回调的可选提示。
• [out] result: 表示 node::Buffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

除了 Node.js 之外的一些运行时已放弃对外部缓冲区的支持。在 Node.js 之外的运行时上，此方法可能返回 napi_no_external_buffers_allowed 以指示不支持外部缓冲区。其中一个运行时是 Electron，如 issue electron/issues/35801 中所述。

为了保持与所有运行时的最广泛兼容性，您可以在包含 node-api 头文件之前在您的插件中定义 NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED。这样做将隐藏创建外部缓冲区的两个函数。这将确保如果您不小心使用了这些方法之一，会发生编译错误。

此 API 分配一个 node::Buffer 对象，并使用传入缓冲区支持的数据对其进行初始化。虽然这仍然是一个完全支持的数据结构，但在大多数情况下，使用 TypedArray 就足够了。

API 添加了一个 napi_finalize 回调，该回调将在刚刚创建的 JavaScript 对象被垃圾回收时调用。

对于 Node.js >=4，Buffers 是 Uint8Array。

napi_create_object#

napi_status napi_create_object(napi_env env, napi_value* result) copy

• [in] env: 调用 API 的环境。
• [out] result: 表示 JavaScript Object 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 分配一个默认的 JavaScript Object。它等同于在 JavaScript 中执行 new Object()。

JavaScript Object 类型在 ECMAScript 语言规范 的 第 object 类型 一节中进行了描述。

napi_create_symbol#

napi_status napi_create_symbol(napi_env env,
                               napi_value description,
                               napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] description: 可选的 napi_value，指向一个 JavaScript string，作为符号的描述。
• [out] result: 表示 JavaScript symbol 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 从 UTF8 编码的 C 字符串创建 JavaScript symbol 值。

JavaScript symbol 类型在 ECMAScript 语言规范 的 第 symbol 类型 一节中进行了描述。

node_api_symbol_for#

napi_status node_api_symbol_for(napi_env env,
                                const char* utf8description,
                                size_t length,
                                napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] utf8description: UTF-8 C 字符串，表示用作符号描述的文本。
• [in] length: 描述字符串的长度（以字节为单位），如果为 null 终止，则为 NAPI_AUTO_LENGTH。
• [out] result: 表示 JavaScript symbol 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 在全局注册表中搜索具有给定描述的现有符号。如果符号已存在，则返回该符号，否则将在注册表中创建一个新符号。

JavaScript symbol 类型在 ECMAScript 语言规范 的 第 symbol 类型 一节中进行了描述。

napi_create_typedarray#

napi_status napi_create_typedarray(napi_env env,
                                   napi_typedarray_type type,
                                   size_t length,
                                   napi_value arraybuffer,
                                   size_t byte_offset,
                                   napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] type: TypedArray 中元素的标量数据类型。
• [in] length: TypedArray 中的元素数量。
• [in] arraybuffer: 类型化数组底层的 ArrayBuffer。
• [in] byte_offset: ArrayBuffer 中开始投影 TypedArray 的字节偏移量。
• [out] result: 表示 JavaScript TypedArray 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 在现有 ArrayBuffer 上创建 JavaScript TypedArray 对象。TypedArray 对象提供了一个类似数组的视图，位于底层数据缓冲区之上，其中每个元素都具有相同的底层二进制标量数据类型。

要求 (length * size_of_element) + byte_offset 应该小于或等于传入数组的字节大小。如果不是，则会引发 RangeError 异常。

JavaScript TypedArray 对象在 ECMAScript 语言规范 的 第 TypedArray 对象 一节中进行了描述。

node_api_create_buffer_from_arraybuffer#

napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
                                                              napi_value arraybuffer,
                                                              size_t byte_offset,
                                                              size_t byte_length,
                                                              napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] arraybuffer: 将从中创建缓冲区的 ArrayBuffer。
• [in] byte_offset: ArrayBuffer 中开始创建缓冲区的字节偏移量。
• [in] byte_length: 将从 ArrayBuffer 创建的缓冲区的长度（以字节为单位）。
• [out] result: 表示创建的 JavaScript Buffer 对象的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 从现有 ArrayBuffer 创建 JavaScript Buffer 对象。Buffer 对象是 Node.js 特有的类，它提供了一种直接在 JavaScript 中处理二进制数据的方法。

字节范围 [byte_offset, byte_offset + byte_length) 必须在 ArrayBuffer 的边界内。如果 byte_offset + byte_length 超过 ArrayBuffer 的大小，则会引发 RangeError 异常。

napi_create_dataview#

napi_status napi_create_dataview(napi_env env,
                                 size_t byte_length,
                                 napi_value arraybuffer,
                                 size_t byte_offset,
                                 napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] length: DataView 中的元素数量。
• [in] arraybuffer: DataView 底层的 ArrayBuffer。
• [in] byte_offset: ArrayBuffer 中开始投影 DataView 的字节偏移量。
• [out] result: 表示 JavaScript DataView 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 在现有 ArrayBuffer 上创建 JavaScript DataView 对象。DataView 对象提供了一个类似数组的视图，位于底层数据缓冲区之上，但允许 ArrayBuffer 中具有不同大小和类型的项。

要求 byte_length + byte_offset 小于或等于传入数组的字节大小。如果不是，则会引发 RangeError 异常。

JavaScript DataView 对象在 ECMAScript 语言规范 的 第 DataView 对象 一节中进行了描述。

napi_create_int32#

napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 要在 JavaScript 中表示的整数值。
• [out] result: 表示 JavaScript number 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 用于将 C int32_t 类型转换为 JavaScript number 类型。

JavaScript number 类型在 ECMAScript 语言规范 的 第 number 类型 一节中进行了描述。

napi_create_uint32#

napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 要在 JavaScript 中表示的无符号整数值。
• [out] result: 表示 JavaScript number 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 用于将 C uint32_t 类型转换为 JavaScript number 类型。

JavaScript number 类型在 ECMAScript 语言规范 的 第 number 类型 一节中进行了描述。

napi_create_int64#

napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 要在 JavaScript 中表示的整数值。
• [out] result: 表示 JavaScript number 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 用于将 C int64_t 类型转换为 JavaScript number 类型。

JavaScript number 类型在 ECMAScript 语言规范 的 第 number 类型 一节中进行了描述。请注意，int64_t 的完整范围不能在 JavaScript 中以完全精度表示。超出 Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) 范围的整数值将失去精度。

napi_create_double#

napi_status napi_create_double(napi_env env, double value, napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 要在 JavaScript 中表示的双精度值。
• [out] result: 表示 JavaScript number 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 用于将 C double 类型转换为 JavaScript number 类型。

JavaScript number 类型在 ECMAScript 语言规范 的 第 number 类型 一节中进行了描述。

napi_create_bigint_int64#

napi_status napi_create_bigint_int64(napi_env env,
                                     int64_t value,
                                     napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] value: 要在 JavaScript 中表示的整数值。
• [out] result: 表示 JavaScript BigInt 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 将 C int64_t 类型转换为 JavaScript BigInt 类型。

napi_create_bigint_uint64#

napi_status napi_create_bigint_uint64(napi_env env,
                                      uint64_t value,
                                      napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] value: 要在 JavaScript 中表示的无符号整数值。
• [out] result: 表示 JavaScript BigInt 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 将 C uint64_t 类型转换为 JavaScript BigInt 类型。

napi_create_bigint_words#

napi_status napi_create_bigint_words(napi_env env,
                                     int sign_bit,
                                     size_t word_count,
                                     const uint64_t* words,
                                     napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] sign_bit: 确定结果 BigInt 是正数还是负数。
• [in] word_count: words 数组的长度。
• [in] words: uint64_t 小端 64 位字的数组。
• [out] result: 表示 JavaScript BigInt 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 将无符号 64 位字数组转换为单个 BigInt 值。

结果 BigInt 计算为: (–1)^sign_bit (words[0] × (2⁶⁴)⁰ + words[1] × (2⁶⁴)¹ + …)

napi_create_string_latin1#

napi_status napi_create_string_latin1(napi_env env,
                                      const char* str,
                                      size_t length,
                                      napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] str: 表示 ISO-8859-1 编码字符串的字符缓冲区。
• [in] length: 字符串的长度（以字节为单位），如果为 null 终止，则为 NAPI_AUTO_LENGTH。
• [out] result: 表示 JavaScript string 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 从 ISO-8859-1 编码的 C 字符串创建 JavaScript string 值。原生字符串被复制。

JavaScript string 类型在 ECMAScript 语言规范 的 第 string 类型 一节中进行了描述。

node_api_create_external_string_latin1#

napi_status
node_api_create_external_string_latin1(napi_env env,
                                       char* str,
                                       size_t length,
                                       napi_finalize finalize_callback,
                                       void* finalize_hint,
                                       napi_value* result,
                                       bool* copied); copy

• [in] env: 调用 API 的环境。
• [in] str: 表示 ISO-8859-1 编码字符串的字符缓冲区。
• [in] length: 字符串的长度（以字节为单位），如果为 null 终止，则为 NAPI_AUTO_LENGTH。
• [in] finalize_callback: 当字符串被收集时要调用的函数。该函数将使用以下参数调用
  • [in] env: 插件运行的环境。如果字符串作为 worker 或主 Node.js 实例终止的一部分而被收集，则此值可能为 null。
  • [in] data: 这是 str 的值，作为 void* 指针。
  • [in] finalize_hint: 这是提供给 API 的 finalize_hint 值。napi_finalize 提供了更多详细信息。此参数是可选的。传递空值意味着当相应的 JavaScript 字符串被收集时，插件不需要收到通知。
• [in] finalize_hint: 在收集期间传递给终结回调的可选提示。
• [out] result: 表示 JavaScript string 的 napi_value。
• [out] copied: 字符串是否被复制。如果已复制，则终结器将已调用以销毁 str。

如果 API 成功，则返回 napi_ok。

此 API 从 ISO-8859-1 编码的 C 字符串创建 JavaScript string 值。原生字符串可能未被复制，因此必须在 JavaScript 值的整个生命周期中存在。

JavaScript string 类型在 ECMAScript 语言规范 的 第 string 类型 一节中进行了描述。

napi_create_string_utf16#

napi_status napi_create_string_utf16(napi_env env,
                                     const char16_t* str,
                                     size_t length,
                                     napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] str: 表示 UTF16-LE 编码字符串的字符缓冲区。
• [in] length: 字符串的长度（以双字节代码单元为单位），如果为 null 终止，则为 NAPI_AUTO_LENGTH。
• [out] result: 表示 JavaScript string 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 从 UTF16-LE 编码的 C 字符串创建 JavaScript string 值。原生字符串被复制。

JavaScript string 类型在 ECMAScript 语言规范 的 第 string 类型 一节中进行了描述。

node_api_create_external_string_utf16#

napi_status
node_api_create_external_string_utf16(napi_env env,
                                      char16_t* str,
                                      size_t length,
                                      napi_finalize finalize_callback,
                                      void* finalize_hint,
                                      napi_value* result,
                                      bool* copied); copy

• [in] env: 调用 API 的环境。
• [in] str: 表示 UTF16-LE 编码字符串的字符缓冲区。
• [in] length: 字符串的长度（以双字节代码单元为单位），如果为 null 终止，则为 NAPI_AUTO_LENGTH。
• [in] finalize_callback: 当字符串被收集时要调用的函数。该函数将使用以下参数调用
  • [in] env: 插件运行的环境。如果字符串作为 worker 或主 Node.js 实例终止的一部分而被收集，则此值可能为 null。
  • [in] data: 这是 str 的值，作为 void* 指针。
  • [in] finalize_hint: 这是提供给 API 的 finalize_hint 值。napi_finalize 提供了更多详细信息。此参数是可选的。传递空值意味着当相应的 JavaScript 字符串被收集时，插件不需要收到通知。
• [in] finalize_hint: 在收集期间传递给终结回调的可选提示。
• [out] result: 表示 JavaScript string 的 napi_value。
• [out] copied: 字符串是否被复制。如果已复制，则终结器将已调用以销毁 str。

如果 API 成功，则返回 napi_ok。

此 API 从 UTF16-LE 编码的 C 字符串创建 JavaScript string 值。原生字符串可能未被复制，因此必须在 JavaScript 值的整个生命周期中存在。

JavaScript string 类型在 ECMAScript 语言规范 的 第 string 类型 一节中进行了描述。

napi_create_string_utf8#

napi_status napi_create_string_utf8(napi_env env,
                                    const char* str,
                                    size_t length,
                                    napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] str: 表示 UTF8 编码字符串的字符缓冲区。
• [in] length: 字符串的长度（以字节为单位），如果为 null 终止，则为 NAPI_AUTO_LENGTH。
• [out] result: 表示 JavaScript string 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 从 UTF8 编码的 C 字符串创建 JavaScript string 值。原生字符串被复制。

JavaScript string 类型在 ECMAScript 语言规范 的 第 string 类型 一节中进行了描述。

node_api_create_property_key_latin1#

napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
                                                           const char* str,
                                                           size_t length,
                                                           napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] str: 表示 ISO-8859-1 编码字符串的字符缓冲区。
• [in] length: 字符串的长度（以字节为单位），如果为 null 终止，则为 NAPI_AUTO_LENGTH。
• [out] result: 表示优化 JavaScript string 的 napi_value，用作对象的属性键。

如果 API 成功，则返回 napi_ok。

此 API 从 ISO-8859-1 编码的 C 字符串创建优化 JavaScript string 值，用作对象的属性键。原生字符串被复制。与 napi_create_string_latin1 不同，随后使用相同的 str 指针调用此函数可能会从所请求的 napi_value 的创建中受益于加速，具体取决于引擎。

JavaScript string 类型在 ECMAScript 语言规范 的 第 string 类型 一节中进行了描述。

node_api_create_property_key_utf16#

napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
                                                          const char16_t* str,
                                                          size_t length,
                                                          napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] str: 表示 UTF16-LE 编码字符串的字符缓冲区。
• [in] length: 字符串的长度（以双字节代码单元为单位），如果为 null 终止，则为 NAPI_AUTO_LENGTH。
• [out] result: 表示优化 JavaScript string 的 napi_value，用作对象的属性键。

如果 API 成功，则返回 napi_ok。

此 API 从 UTF16-LE 编码的 C 字符串创建优化 JavaScript string 值，用作对象的属性键。原生字符串被复制。

JavaScript string 类型在 ECMAScript 语言规范 的 第 string 类型 一节中进行了描述。

node_api_create_property_key_utf8#

napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
                                                         const char* str,
                                                         size_t length,
                                                         napi_value* result); copy

• [in] env: 调用 API 的环境。
• [in] str: 表示 UTF8 编码字符串的字符缓冲区。
• [in] length: 字符串的长度（以双字节代码单元为单位），如果为 null 终止，则为 NAPI_AUTO_LENGTH。
• [out] result: 表示优化 JavaScript string 的 napi_value，用作对象的属性键。

如果 API 成功，则返回 napi_ok。

此 API 从 UTF8 编码的 C 字符串创建优化 JavaScript string 值，用作对象的属性键。原生字符串被复制。

JavaScript string 类型在 ECMAScript 语言规范 的 第 string 类型 一节中进行了描述。

napi_get_array_length#

napi_status napi_get_array_length(napi_env env,
                                  napi_value value,
                                  uint32_t* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示正在查询长度的 JavaScript Array 的 napi_value。
• [out] result: 表示数组长度的 uint32。

如果 API 成功，则返回 napi_ok。

此 API 返回数组的长度。

Array 长度在 ECMAScript 语言规范 的 第 Array 实例长度 一节中进行了描述。

napi_get_arraybuffer_info#

napi_status napi_get_arraybuffer_info(napi_env env,
                                      napi_value arraybuffer,
                                      void** data,
                                      size_t* byte_length) copy

• [in] env: 调用 API 的环境。
• [in] arraybuffer: 表示正在查询的 ArrayBuffer 或 SharedArrayBuffer 的 napi_value。
• [out] data: ArrayBuffer 或 SharedArrayBuffer 的底层数据缓冲区为 0，这可以是 NULL 或任何其他指针值。
• [out] byte_length: 底层数据缓冲区的长度（以字节为单位）。

如果 API 成功，则返回 napi_ok。

此 API 用于检索 ArrayBuffer 或 SharedArrayBuffer 的底层数据缓冲区及其长度。

警告: 使用此 API 时请务必小心。底层数据缓冲区的生命周期由 ArrayBuffer 或 SharedArrayBuffer 管理，即使在返回后也是如此。使用此 API 的一种可能的安全方法是结合 napi_create_reference 使用，该方法可用于保证对 ArrayBuffer 或 SharedArrayBuffer 生命周期的控制。只要没有调用可能触发 GC 的其他 API，在同一回调中使用返回的数据缓冲区也是安全的。

napi_get_buffer_info#

napi_status napi_get_buffer_info(napi_env env,
                                 napi_value value,
                                 void** data,
                                 size_t* length) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示正在查询的 node::Buffer 或 Uint8Array 的 napi_value。
• [out] data: node::Buffer 或 Uint8Array 的底层数据缓冲区。如果长度为 0，这可以是 NULL 或任何其他指针值。
• [out] length: 底层数据缓冲区的长度（以字节为单位）。

如果 API 成功，则返回 napi_ok。

此方法返回与 napi_get_typedarray_info 相同的 data 和 byte_length。并且 napi_get_typedarray_info 也接受 node::Buffer (一个 Uint8Array) 作为值。

此 API 用于检索 node::Buffer 的底层数据缓冲区及其长度。

警告: 使用此 API 时请务必小心，因为如果底层数据缓冲区由 VM 管理，则其生命周期无法保证。

napi_get_prototype#

napi_status napi_get_prototype(napi_env env,
                               napi_value object,
                               napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] object: 表示要返回其原型的 JavaScript Object 的 napi_value。这返回与 Object.getPrototypeOf 等效的值（与函数的 prototype 属性不同）。
• [out] result: 表示给定对象原型的 napi_value。

如果 API 成功，则返回 napi_ok。

napi_get_typedarray_info#

napi_status napi_get_typedarray_info(napi_env env,
                                     napi_value typedarray,
                                     napi_typedarray_type* type,
                                     size_t* length,
                                     void** data,
                                     napi_value* arraybuffer,
                                     size_t* byte_offset) copy

• [in] env: 调用 API 的环境。
• [in] typedarray: 表示要查询其属性的 TypedArray 的 napi_value。
• [out] type: TypedArray 中元素的标量数据类型。
• [out] length: TypedArray 中的元素数量。
• [out] data: TypedArray 的底层数据缓冲区，已通过 byte_offset 值调整，使其指向 TypedArray 中的第一个元素。如果数组长度为 0，则此值可能为 NULL 或任何其他指针值。
• [out] arraybuffer: TypedArray 底层的 ArrayBuffer。
• [out] byte_offset: 底层原生数组中第一个元素所在位置的字节偏移量。数据参数的值已经过调整，因此数据指向数组中的第一个元素。因此，原生数组的第一个字节将位于 data - byte_offset。

如果 API 成功，则返回 napi_ok。

此 API 返回类型化数组的各种属性。

如果不需要某个属性，则任何输出参数都可以是 NULL。

警告: 使用此 API 时请务必小心，因为底层数据缓冲区由 VM 管理。

napi_get_dataview_info#

napi_status napi_get_dataview_info(napi_env env,
                                   napi_value dataview,
                                   size_t* byte_length,
                                   void** data,
                                   napi_value* arraybuffer,
                                   size_t* byte_offset) copy

• [in] env: 调用 API 的环境。
• [in] dataview: 表示要查询其属性的 DataView 的 napi_value。
• [out] byte_length: DataView 中的字节数。
• [out] data: DataView 的底层数据缓冲区。如果 byte_length 为 0，则此值可能为 NULL 或任何其他指针值。
• [out] arraybuffer: DataView 底层的 ArrayBuffer。
• [out] byte_offset: 数据缓冲区中开始投影 DataView 的字节偏移量。

如果 API 成功，则返回 napi_ok。

如果不需要某个属性，则任何输出参数都可以是 NULL。

此 API 返回 DataView 的各种属性。

napi_get_date_value#

napi_status napi_get_date_value(napi_env env,
                                napi_value value,
                                double* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript Date 的 napi_value。
• [out] result: 时间值，表示自 1970 年 1 月 1 日 UTC 午夜以来的毫秒数，以 double 表示。

此 API 不观察闰秒；它们被忽略，因为 ECMAScript 与 POSIX 时间规范保持一致。

如果 API 成功，则返回 napi_ok。如果传入非日期 napi_value，则返回 napi_date_expected。

此 API 返回给定 JavaScript Date 的时间值的 C 双精度原始值。

napi_get_value_bool#

napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript Boolean 的 napi_value。
• [out] result: 给定 JavaScript Boolean 的 C 布尔原始等效值。

如果 API 成功，则返回 napi_ok。如果传入非布尔 napi_value，则返回 napi_boolean_expected。

此 API 返回给定 JavaScript Boolean 的 C 布尔原始等效值。

napi_get_value_double#

napi_status napi_get_value_double(napi_env env,
                                  napi_value value,
                                  double* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript number 的 napi_value。
• [out] result: 给定 JavaScript number 的 C 双精度原始等效值。

如果 API 成功，则返回 napi_ok。如果传入非数字 napi_value，则返回 napi_number_expected。

此 API 返回给定 JavaScript number 的 C 双精度原始等效值。

napi_get_value_bigint_int64#

napi_status napi_get_value_bigint_int64(napi_env env,
                                        napi_value value,
                                        int64_t* result,
                                        bool* lossless); copy

• [in] env: 调用 API 的环境
• [in] value: 表示 JavaScript BigInt 的 napi_value。
• [out] result: 给定 JavaScript BigInt 的 C int64_t 原始等效值。
• [out] lossless: 指示 BigInt 值是否无损转换。

如果 API 成功，则返回 napi_ok。如果传入非 BigInt，则返回 napi_bigint_expected。

此 API 返回给定 JavaScript BigInt 的 C int64_t 原始等效值。如果需要，它将截断该值，并将 lossless 设置为 false。

napi_get_value_bigint_uint64#

napi_status napi_get_value_bigint_uint64(napi_env env,
                                        napi_value value,
                                        uint64_t* result,
                                        bool* lossless); copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript BigInt 的 napi_value。
• [out] result: 给定 JavaScript BigInt 的 C uint64_t 原始等效值。
• [out] lossless: 指示 BigInt 值是否无损转换。

如果 API 成功，则返回 napi_ok。如果传入非 BigInt，则返回 napi_bigint_expected。

此 API 返回给定 JavaScript BigInt 的 C uint64_t 原始等效值。如果需要，它将截断该值，并将 lossless 设置为 false。

napi_get_value_bigint_words#

napi_status napi_get_value_bigint_words(napi_env env,
                                        napi_value value,
                                        int* sign_bit,
                                        size_t* word_count,
                                        uint64_t* words); copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript BigInt 的 napi_value。
• [out] sign_bit: 表示 JavaScript BigInt 是正数还是负数的整数。
• [in/out] word_count: 必须初始化为 words 数组的长度。返回时，它将设置为存储此 BigInt 所需的实际字数。
• [out] words: 指向预分配的 64 位字数组的指针。

如果 API 成功，则返回 napi_ok。

此 API 将单个 BigInt 值转换为符号位、64 位小端数组以及数组中的元素数量。sign_bit 和 words 都可以设置为 NULL，以便只获取 word_count。

napi_get_value_external#

napi_status napi_get_value_external(napi_env env,
                                    napi_value value,
                                    void** result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript 外部值的 napi_value。
• [out] result: 指向 JavaScript 外部值包装的数据的指针。

如果 API 成功，则返回 napi_ok。如果传入非外部 napi_value，则返回 napi_invalid_arg。

此 API 检索先前传递给 napi_create_external() 的外部数据指针。

napi_get_value_int32#

napi_status napi_get_value_int32(napi_env env,
                                 napi_value value,
                                 int32_t* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript number 的 napi_value。
• [out] result: 给定 JavaScript number 的 C int32 原始等效值。

如果 API 成功，则返回 napi_ok。如果传入非数字 napi_value，则返回 napi_number_expected。

此 API 返回给定 JavaScript number 的 C int32 原始等效值。

如果数字超出 32 位整数的范围，则结果将被截断为等效的低 32 位。如果值大于 2³¹ - 1，这可能导致较大的正数变为负数。

非有限数字值（NaN、+Infinity 或 -Infinity）将结果设置为零。

napi_get_value_int64#

napi_status napi_get_value_int64(napi_env env,
                                 napi_value value,
                                 int64_t* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript number 的 napi_value。
• [out] result: 给定 JavaScript number 的 C int64 原始等效值。

如果 API 成功，则返回 napi_ok。如果传入非数字 napi_value，则返回 napi_number_expected。

此 API 返回给定 JavaScript number 的 C int64 原始等效值。

超出 Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) 范围的 number 值将失去精度。

非有限数字值（NaN、+Infinity 或 -Infinity）将结果设置为零。

napi_get_value_string_latin1#

napi_status napi_get_value_string_latin1(napi_env env,
                                         napi_value value,
                                         char* buf,
                                         size_t bufsize,
                                         size_t* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript 字符串的 napi_value。
• [in] buf: 写入 ISO-8859-1 编码字符串的缓冲区。如果传入 NULL，则字符串的长度（以字节为单位，不包括空终止符）将在 result 中返回。
• [in] bufsize: 目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以空终止。如果此值为零，则不返回字符串，并且不对缓冲区进行任何更改。
• [out] result: 复制到缓冲区中的字节数，不包括空终止符。

如果 API 成功，则返回 napi_ok。如果传入非 string napi_value，则返回 napi_string_expected。

此 API 返回与传入值对应的 ISO-8859-1 编码字符串。

napi_get_value_string_utf8#

napi_status napi_get_value_string_utf8(napi_env env,
                                       napi_value value,
                                       char* buf,
                                       size_t bufsize,
                                       size_t* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript 字符串的 napi_value。
• [in] buf: 写入 UTF8 编码字符串的缓冲区。如果传入 NULL，则字符串的长度（以字节为单位，不包括空终止符）将在 result 中返回。
• [in] bufsize: 目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以空终止。如果此值为零，则不返回字符串，并且不对缓冲区进行任何更改。
• [out] result: 复制到缓冲区中的字节数，不包括空终止符。

如果 API 成功，则返回 napi_ok。如果传入非 string napi_value，则返回 napi_string_expected。

此 API 返回与传入值对应的 UTF8 编码字符串。

napi_get_value_string_utf16#

napi_status napi_get_value_string_utf16(napi_env env,
                                        napi_value value,
                                        char16_t* buf,
                                        size_t bufsize,
                                        size_t* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript 字符串的 napi_value。
• [in] buf: 写入 UTF16-LE 编码字符串的缓冲区。如果传入 NULL，则字符串的长度（以 2 字节代码单元为单位，不包括空终止符）将返回。
• [in] bufsize: 目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以空终止。如果此值为零，则不返回字符串，并且不对缓冲区进行任何更改。
• [out] result: 复制到缓冲区中的 2 字节代码单元数，不包括空终止符。

如果 API 成功，则返回 napi_ok。如果传入非 string napi_value，则返回 napi_string_expected。

此 API 返回与传入值对应的 UTF16 编码字符串。

napi_get_value_uint32#

napi_status napi_get_value_uint32(napi_env env,
                                  napi_value value,
                                  uint32_t* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 表示 JavaScript number 的 napi_value。
• [out] result: 给定 napi_value 的 C 原始等效值，作为 uint32_t。

如果 API 成功，则返回 napi_ok。如果传入非数字 napi_value，则返回 napi_number_expected。

此 API 返回给定 napi_value 的 C 原始等效值，作为 uint32_t。

napi_get_boolean#

napi_status napi_get_boolean(napi_env env, bool value, napi_value* result) copy

• [in] env: 调用 API 的环境。
• [in] value: 要检索的布尔值。
• [out] result: 表示要检索的 JavaScript Boolean 单例的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 用于返回用于表示给定布尔值的 JavaScript 单例对象。

napi_get_global#

napi_status napi_get_global(napi_env env, napi_value* result) copy

• [in] env: 调用 API 的环境。
• [out] result: 表示 JavaScript global 对象的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回 global 对象。

napi_get_null#

napi_status napi_get_null(napi_env env, napi_value* result) copy

• [in] env: 调用 API 的环境。
• [out] result: 表示 JavaScript null 对象的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回 null 对象。

napi_get_undefined#

napi_status napi_get_undefined(napi_env env, napi_value* result) copy

• [in] env: 调用 API 的环境。
• [out] result: 表示 JavaScript Undefined 值的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回 Undefined 对象。

napi_property_attributes#

typedef enum {
  napi_default = 0,
  napi_writable = 1 << 0,
  napi_enumerable = 1 << 1,
  napi_configurable = 1 << 2,

  // Used with napi_define_class to distinguish static properties
  // from instance properties. Ignored by napi_define_properties.
  napi_static = 1 << 10,

  // Default for class methods.
  napi_default_method = napi_writable | napi_configurable,

  // Default for object properties, like in JS obj[prop].
  napi_default_jsproperty = napi_writable |
                          napi_enumerable |
                          napi_configurable,
} napi_property_attributes; copy

napi_property_attributes 是用于控制 JavaScript 对象上设置属性行为的位标志。除了 napi_static 之外，它们对应于 ECMAScript 语言规范 的 第 property attributes 一节中列出的属性。它们可以是一个或多个以下位标志

• napi_default: 属性上未设置显式属性。默认情况下，属性是只读的，不可枚举且不可配置。
• napi_writable: 属性是可写的。
• napi_enumerable: 属性是可枚举的。
• napi_configurable: 属性是可配置的，如 ECMAScript 语言规范 的 第 property attributes 一节中定义。
• napi_static: 属性将定义为类的静态属性，而不是实例属性（这是默认值）。这仅由 napi_define_class 使用。它被 napi_define_properties 忽略。
• napi_default_method: 类似于 JS 类中的方法，属性是可配置和可写的，但不可枚举。
• napi_default_jsproperty: 类似于通过 JavaScript 中的赋值设置的属性，属性是可写、可枚举和可配置的。

napi_property_descriptor#

typedef struct {
  // One of utf8name or name should be NULL.
  const char* utf8name;
  napi_value name;

  napi_callback method;
  napi_callback getter;
  napi_callback setter;
  napi_value value;

  napi_property_attributes attributes;
  void* data;
} napi_property_descriptor; copy

• utf8name: 描述属性键的可选字符串，以 UTF8 编码。属性必须提供 utf8name 或 name 之一。
• name: 可选的 napi_value，指向用作属性键的 JavaScript 字符串或符号。属性必须提供 utf8name 或 name 之一。
• value: 如果属性是数据属性，则通过 get 访问属性检索到的值。如果传入此值，则将 getter、setter、method 和 data 设置为 NULL（因为这些成员不会被使用）。
• getter: 执行属性的 get 访问时调用的函数。如果传入此值，则将 value 和 method 设置为 NULL（因为这些成员不会被使用）。当从 JavaScript 代码访问属性（或使用 Node-API 调用对属性执行 get 操作）时，运行时会隐式调用给定函数。napi_callback 提供了更多详细信息。
• setter: 执行属性的 set 访问时调用的函数。如果传入此值，则将 value 和 method 设置为 NULL（因为这些成员不会被使用）。当从 JavaScript 代码设置属性（或使用 Node-API 调用对属性执行 set 操作）时，运行时会隐式调用给定函数。napi_callback 提供了更多详细信息。
• method: 设置此项以使属性描述符对象的 value 属性成为由 method 表示的 JavaScript 函数。如果传入此值，则将 value、getter 和 setter 设置为 NULL（因为这些成员不会被使用）。napi_callback 提供了更多详细信息。
• attributes: 与特定属性关联的属性。请参阅 napi_property_attributes。
• data: 如果此函数被调用，则传入 method、getter 和 setter 的回调数据。

napi_get_property_names#

napi_status napi_get_property_names(napi_env env,
                                    napi_value object,
                                    napi_value* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object: 从中检索属性的对象。
• [out] result: 表示 JavaScript 值数组的 napi_value，这些值表示对象的属性名称。API 可以使用 napi_get_array_length 和 napi_get_element 遍历 result。

如果 API 成功，则返回 napi_ok。

此 API 返回 object 的可枚举属性的名称作为字符串数组。键为符号的 object 属性将不包含在内。

napi_get_all_property_names#

napi_get_all_property_names(napi_env env,
                            napi_value object,
                            napi_key_collection_mode key_mode,
                            napi_key_filter key_filter,
                            napi_key_conversion key_conversion,
                            napi_value* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object: 从中检索属性的对象。
• [in] key_mode: 是否也检索原型属性。
• [in] key_filter: 要检索哪些属性（可枚举/可读/可写）。
• [in] key_conversion: 是否将编号属性键转换为字符串。
• [out] result：一个 napi_value，表示一个 JavaScript 值数组，这些值表示对象的属性名。napi_get_array_length 和 napi_get_element 可用于迭代 result。

如果 API 成功，则返回 napi_ok。

此 API 返回一个数组，其中包含此对象的可用属性的名称。

napi_set_property#

napi_status napi_set_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value value); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要设置属性的对象。
• [in] key：要设置的属性的名称。
• [in] value：属性值。

如果 API 成功，则返回 napi_ok。

此 API 在传入的 Object 上设置一个属性。

napi_get_property#

napi_status napi_get_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：从中检索属性的对象。
• [in] key：要检索的属性的名称。
• [out] result：属性的值。

如果 API 成功，则返回 napi_ok。

此 API 从传入的 Object 中获取请求的属性。

napi_has_property#

napi_status napi_has_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] key：要检查其是否存在属性的名称。
• [out] result：属性是否存在于对象上。

如果 API 成功，则返回 napi_ok。

此 API 检查传入的 Object 是否具有指定名称的属性。

napi_delete_property#

napi_status napi_delete_property(napi_env env,
                                 napi_value object,
                                 napi_value key,
                                 bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] key：要删除的属性的名称。
• [out] result：属性删除是否成功。可以通过传入 NULL 来选择性地忽略 result。

如果 API 成功，则返回 napi_ok。

此 API 尝试从 object 中删除 key 自己的属性。

napi_has_own_property#

napi_status napi_has_own_property(napi_env env,
                                  napi_value object,
                                  napi_value key,
                                  bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] key：要检查其是否存在自身属性的名称。
• [out] result：自身属性是否存在于对象上。

如果 API 成功，则返回 napi_ok。

此 API 检查传入的 Object 是否具有指定名称的自身属性。key 必须是 string 或 symbol，否则将抛出错误。Node-API 不会执行任何数据类型之间的转换。

napi_set_named_property#

napi_status napi_set_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value value); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要设置属性的对象。
• [in] utf8Name：要设置的属性的名称。
• [in] value：属性值。

如果 API 成功，则返回 napi_ok。

此方法等同于调用 napi_set_property，其中 napi_value 是由作为 utf8Name 传入的字符串创建的。

napi_get_named_property#

napi_status napi_get_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：从中检索属性的对象。
• [in] utf8Name：要获取的属性的名称。
• [out] result：属性的值。

如果 API 成功，则返回 napi_ok。

此方法等同于调用 napi_get_property，其中 napi_value 是由作为 utf8Name 传入的字符串创建的。

napi_has_named_property#

napi_status napi_has_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] utf8Name：要检查其是否存在属性的名称。
• [out] result：属性是否存在于对象上。

如果 API 成功，则返回 napi_ok。

此方法等同于调用 napi_has_property，其中 napi_value 是由作为 utf8Name 传入的字符串创建的。

napi_set_element#

napi_status napi_set_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value value); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要设置属性的对象。
• [in] index：要设置的属性的索引。
• [in] value：属性值。

如果 API 成功，则返回 napi_ok。

此 API 在传入的 Object 上设置一个元素。

napi_get_element#

napi_status napi_get_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：从中检索属性的对象。
• [in] index：要获取的属性的索引。
• [out] result：属性的值。

如果 API 成功，则返回 napi_ok。

此 API 获取请求索引处的元素。

napi_has_element#

napi_status napi_has_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] index：要检查其是否存在属性的索引。
• [out] result：属性是否存在于对象上。

如果 API 成功，则返回 napi_ok。

此 API 返回传入的 Object 是否在请求的索引处有一个元素。

napi_delete_element#

napi_status napi_delete_element(napi_env env,
                                napi_value object,
                                uint32_t index,
                                bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] index：要删除的属性的索引。
• [out] result：元素删除是否成功。可以通过传入 NULL 来选择性地忽略 result。

如果 API 成功，则返回 napi_ok。

此 API 尝试从 object 中删除指定的 index。

napi_define_properties#

napi_status napi_define_properties(napi_env env,
                                   napi_value object,
                                   size_t property_count,
                                   const napi_property_descriptor* properties); copy

• [in] env: 调用 Node-API 的环境。
• [in] object: 从中检索属性的对象。
• [in] property_count：properties 数组中的元素数量。
• [in] properties：属性描述符数组。

如果 API 成功，则返回 napi_ok。

此方法允许在给定对象上高效定义多个属性。属性使用属性描述符定义（请参阅 napi_property_descriptor）。给定此类属性描述符数组，此 API 将根据 DefineOwnProperty()（在 ECMA-262 规范的 DefineOwnProperty 部分 中描述）定义，一次设置对象上的属性。

napi_object_freeze#

napi_status napi_object_freeze(napi_env env,
                               napi_value object); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要冻结的对象。

如果 API 成功，则返回 napi_ok。

此方法冻结给定对象。这会阻止向其添加新属性、删除现有属性、更改现有属性的可枚举性、可配置性或可写性，以及更改现有属性的值。它还会阻止更改对象的原型。这在 ECMA-262 规范的 第 19.1.2.6 节 中有所描述。

napi_object_seal#

napi_status napi_object_seal(napi_env env,
                             napi_value object); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要密封的对象。

如果 API 成功，则返回 napi_ok。

此方法密封给定对象。这会阻止向其添加新属性，并将其所有现有属性标记为不可配置。这在 ECMA-262 规范的 第 19.1.2.20 节 中有所描述。

node_api_post_finalizer#

napi_status node_api_post_finalizer(node_api_basic_env env,
                                    napi_finalize finalize_cb,
                                    void* finalize_data,
                                    void* finalize_hint); copy

• [in] env: 调用 API 的环境。
• [in] finalize_cb：原生回调，当 JavaScript 对象被垃圾回收时将用于释放原生数据。napi_finalize 提供了更多详细信息。
• [in] finalize_data：可选数据，将传递给 finalize_cb。
• [in] finalize_hint：传递给终结器回调的可选上下文提示。

如果 API 成功，则返回 napi_ok。

安排在事件循环中异步调用 napi_finalize 回调。

通常，终结器在 GC（垃圾回收器）收集对象时被调用。此时，任何可能导致 GC 状态更改的 Node-API 调用都将被禁用，并将导致 Node.js 崩溃。

node_api_post_finalizer 通过允许插件将此类 Node-API 的调用推迟到 GC 终结之外的时间点，从而帮助解决此限制。