Node.js v21.7.2 文档

ABI 稳定性的影响#

虽然 Node-API 提供了 ABI 稳定性保证，但 Node.js 的其他部分没有，并且从加载项中使用的任何外部库可能也没有。特别是，以下 API 都不提供跨主要版本之间的 ABI 稳定性保证

• 可通过以下任何方式获得的 Node.js C++ API

  #include <node.h>
  #include <node_buffer.h>
  #include <node_version.h>
  #include <node_object_wrap.h> copy

• libuv API，它也包含在 Node.js 中，可通过以下方式获得

  #include <uv.h> copy

• 可通过以下方式获得的 V8 API

  #include <v8.h> copy

因此，为了让加载项在 Node.js 主要版本之间保持 ABI 兼容性，它必须通过限制自身仅使用以下内容来专门使用 Node-API

#include <node_api.h> copy

并检查它使用的所有外部库，以确保外部库做出类似于 Node-API 的 ABI 稳定性保证。

构建#

与使用 JavaScript 编写的模块不同，使用 Node-API 开发和部署 Node.js 本机加载项需要额外的工具集。除了为 Node.js 开发所需的各种基本工具之外，本机加载项开发人员还需要一个可以将 C 和 C++ 代码编译成二进制文件的工具链。此外，根据本机加载项的部署方式，本机加载项的用户还需要安装 C/C++ 工具链。

对于 Linux 开发人员来说，必要的 C/C++ 工具链包很容易获得。GCC 在 Node.js 社区中被广泛用于在各种平台上构建和测试。对于许多开发人员来说，LLVM 编译器基础设施也是一个不错的选择。

对于 Mac 开发人员来说，Xcode 提供了所有必需的编译器工具。但是，没有必要安装整个 Xcode IDE。以下命令安装了必要的工具链

xcode-select --install copy

对于 Windows 开发人员，Visual Studio 提供了所有必需的编译器工具。但是，不必安装整个 Visual Studio IDE。以下命令安装了必要的工具链

npm install --global windows-build-tools copy

以下部分描述了用于开发和部署 Node.js 原生插件的其他工具。

构建工具#

此处列出的两个工具要求原生插件的用户安装 C/C++ 工具链，以便成功安装原生插件。

node-gyp#

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

从历史上看，node-gyp 一直是构建原生插件的首选工具。它被广泛采用并有文档记录。但是，一些开发人员在 node-gyp 中遇到了限制。

CMake.js#

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

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

上传预编译二进制文件#

此处列出的三个工具允许原生插件开发人员和维护人员创建二进制文件并将其上传到公共或私有服务器。这些工具通常与 CI/CD 构建系统（如 Travis CI 和 AppVeyor）集成，以构建和上传各种平台和架构的二进制文件。然后，不需要安装 C/C++ 工具链的用户可以下载这些二进制文件。

node-pre-gyp#

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

prebuild#

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

prebuildify#

prebuildify 是一款基于 node-gyp 的工具。prebuildify 的优点是，在将构建的二进制文件上传到 npm 时，这些文件会与本机插件捆绑在一起。这些二进制文件会从 npm 下载，并在安装本机插件时立即提供给模块用户。

用法#

为了使用 Node-API 函数，请包含文件 node_api.h，该文件位于 node 开发树中的 src 目录中

#include <node_api.h> copy

这会选择给定 Node.js 版本的默认 NAPI_VERSION。为了确保与特定版本的 Node-API 兼容，可以在包含头文件时明确指定版本

#define NAPI_VERSION 3
#include <node_api.h> copy

这会将 Node-API 表面限制为仅在指定版本（及更早版本）中可用的功能。

Node-API 表面中的一些内容是实验性的，需要明确选择加入

#define NAPI_EXPERIMENTAL
#include <node_api.h> copy

在这种情况下，包括任何实验性 API 在内的整个 API 表面都将对模块代码可用。

有时，会引入影响已发布和稳定 API 的实验性功能。可以通过选择退出功能来禁用这些功能

#define NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT
#include <node_api.h> copy

其中 <FEATURE_NAME> 是影响实验性和稳定 API 的实验性功能的名称。

Node-API 版本矩阵#

在版本 9 之前，Node-API 版本是累加的，并且独立于 Node.js 进行版本控制。这意味着任何版本都是前一版本的扩展，因为它具有前一版本的所有 API 以及一些新增内容。每个 Node.js 版本仅支持一个 Node-API 版本。例如，v18.15.0 仅支持 Node-API 版本 8。ABI 稳定性得以实现，因为 8 是所有先前版本的严格超集。

从版本 9 开始，虽然 Node-API 版本继续独立进行版本控制，但使用 Node-API 版本 9 运行的加载项可能需要代码更新才能使用 Node-API 版本 10。但是，ABI 稳定性得以保持，因为支持高于 8 的 Node-API 版本的 Node.js 版本将支持 8 与它们支持的最高版本之间的所有版本，并且在加载项未选择加入更高 Node-API 版本时，默认提供版本 8 API。这种方法提供了更好地优化现有 Node-API 函数的灵活性，同时保持 ABI 稳定性。现有加载项可以继续使用早期版本的 Node-API 运行，而无需重新编译。如果加载项需要较新 Node-API 版本中的功能，则需要对现有代码进行更改并重新编译才能使用这些新函数。

在支持 Node-API 版本 9 及更高版本的 Node.js 版本中，定义 NAPI_VERSION=X 并使用现有的加载项初始化宏将在运行时使用的请求的 Node-API 版本烘焙到加载项中。如果未设置 NAPI_VERSION，它将默认为 8。

此表在较旧的流中可能不是最新的，最新信息位于以下最新 API 文档中：Node-API 版本矩阵

* Node-API 处于实验阶段。

** Node.js 8.0.0 将 Node-API 作为实验功能纳入其中。它以 Node-API 版本 1 发布，但持续发展，直到 Node.js 8.6.0。在 Node.js 8.6.0 之前的版本中，API 不同。我们建议使用 Node-API 版本 3 或更高版本。

为 Node-API 记录的每个 API 都将有一个名为 added in: 的标题，而稳定的 API 将具有附加标题 Node-API version:。在使用支持 Node-API version: 中所示的 Node-API 版本或更高版本的 Node.js 版本时，可以直接使用 API。在使用不支持所列的 Node-API version: 的 Node.js 版本时，或者如果没有列出 Node-API version: 时，只有在 #define NAPI_EXPERIMENTAL 位于 node_api.h 或 js_native_api.h 的包含内容之前时，API 才可用。如果某个 API 在 added in: 中所示的版本之后的 Node.js 版本上似乎不可用，那么这很可能是明显缺失的原因。

与从原生代码访问 ECMAScript 特性严格相关的 Node-API 可以分别在 js_native_api.h 和 js_native_api_types.h 中找到。在这些标题中定义的 API 包含在 node_api.h 和 node_api_types.h 中。这些标题以这种方式进行结构化，以便允许在 Node.js 之外实现 Node-API。对于那些实现，Node.js 特定的 API 可能不适用。

加载项的 Node.js 特定部分可以与向 JavaScript 环境公开实际功能的代码分开，以便后者可以与 Node-API 的多个实现一起使用。在下面的示例中，addon.c 和 addon.h 仅引用 js_native_api.h。这确保了 addon.c 可以重复使用，以便针对 Node-API 的 Node.js 实现或 Node.js 之外的 Node-API 的任何实现进行编译。

addon_node.c 是一个单独的文件，其中包含加载项的 Node.js 特定入口点，并且在将加载项加载到 Node.js 环境中时，通过调用 addon.c 来实例化加载项。

// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif  // _ADDON_H_ copy

// addon.c
#include "addon.h"

#define NODE_API_CALL(env, call)                                  \
  do {                                                            \
    napi_status status = (call);                                  \
    if (status != napi_ok) {                                      \
      const napi_extended_error_info* error_info = NULL;          \
      napi_get_last_error_info((env), &error_info);               \
      const char* err_message = error_info->error_message;        \
      bool is_pending;                                            \
      napi_is_exception_pending((env), &is_pending);              \
      /* If an exception is already pending, don't rethrow it */  \
      if (!is_pending) {                                          \
        const char* message = (err_message == NULL)               \
            ? "empty error message"                               \
            : err_message;                                        \
        napi_throw_error((env), NULL, message);                   \
      }                                                           \
      return NULL;                                                \
    }                                                             \
  } while(0)

static napi_value
DoSomethingUseful(napi_env env, napi_callback_info info) {
  // Do something useful.
  return NULL;
}

napi_value create_addon(napi_env env) {
  napi_value result;
  NODE_API_CALL(env, napi_create_object(env, &result));

  napi_value exported_function;
  NODE_API_CALL(env, napi_create_function(env,
                                          "doSomethingUseful",
                                          NAPI_AUTO_LENGTH,
                                          DoSomethingUseful,
                                          NULL,
                                          &exported_function));

  NODE_API_CALL(env, napi_set_named_property(env,
                                             result,
                                             "doSomethingUseful",
                                             exported_function));

  return result;
} copy

// addon_node.c
#include <node_api.h>
#include "addon.h"

NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
  // This function body is expected to return a `napi_value`.
  // The variables `napi_env env` and `napi_value exports` may be used within
  // the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.
  return create_addon(env);
} copy

环境生命周期 API#

第 8.7 节 的 ECMAScript 语言规范 将“代理”概念定义为 JavaScript 代码运行的独立环境。进程可以同时或按顺序启动和终止多个此类代理。

Node.js 环境对应于 ECMAScript 代理。在主进程中，在启动时创建环境，并且可以在单独的线程上创建其他环境以用作 工作线程。当 Node.js 嵌入到另一个应用程序中时，应用程序的主线程也可能在应用程序进程的生命周期内多次构造和销毁 Node.js 环境，以便应用程序创建的每个 Node.js 环境又可以在其生命周期内创建和销毁其他环境作为工作线程。

从本机加载项的角度来看，这意味着它提供的绑定可能会从多个上下文多次调用，甚至可能从多个线程同时调用。

本机加载项可能需要分配全局状态，以便在其 Node.js 环境的生命周期中使用，以便该状态可以对加载项的每个实例都是唯一的。

为此，Node-API 提供了一种关联数据的方式，以便其生命周期与 Node.js 环境的生命周期相关联。

napi_set_instance_data#

napi_status napi_set_instance_data(node_api_nogc_env env,
                                   void* data,
                                   napi_finalize finalize_cb,
                                   void* finalize_hint); copy

• [in] env：调用 Node-API 的环境。
• [in] data：要向此实例的绑定提供的 data 项。
• [in] finalize_cb：在环境被销毁时调用的函数。该函数接收 data，以便可以释放它。napi_finalize 提供了更多详细信息。
• [in] finalize_hint：在收集期间传递给 finalize 回调的可选提示。

如果 API 成功，则返回 napi_ok。

此 API 将 data 与当前运行的 Node.js 环境相关联。稍后可以使用 napi_get_instance_data() 检索 data。与当前运行的 Node.js 环境关联的任何现有数据（通过先前调用 napi_set_instance_data() 设置）都将被覆盖。如果先前调用提供了 finalize_cb，则不会调用它。

napi_get_instance_data#

napi_status napi_get_instance_data(node_api_nogc_env env,
                                   void** data); copy

• [in] env：调用 Node-API 的环境。
• [out] data：先前通过调用 napi_set_instance_data() 与当前运行的 Node.js 环境关联的数据项。

如果 API 成功，则返回 napi_ok。

此 API 检索先前通过 napi_set_instance_data() 与当前运行的 Node.js 环境关联的数据。如果未设置数据，则调用会成功，并且 data 将设置为 NULL。

基本 Node-API 数据类型#

Node-API 将以下基本数据类型公开为各种 API 使用的抽象。这些 API 应视为不透明的，只能通过其他 Node-API 调用进行内省。

napi_status#

表示 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; copy

如果 API 返回失败状态需要其他信息，可以通过调用 napi_get_last_error_info 获取。

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; copy

• error_message：包含错误的 VM 中立描述的 UTF8 编码字符串。
• engine_reserved：为 VM 特定的错误详细信息保留。目前尚未针对任何 VM 实现此功能。
• engine_error_code：VM 特定的错误代码。目前尚未针对任何 VM 实现此功能。
• error_code：源自上一个错误的 Node-API 状态代码。

有关其他信息，请参阅 错误处理 部分。

napi_env#

napi_env 用于表示底层 Node-API 实现可用于保留 VM 特定状态的上下文。当调用本机函数时，此结构会传递给本机函数，并且在进行 Node-API 调用时必须将其传回。具体来说，在调用初始本机函数时传入的 napi_env 必须传递给任何后续嵌套的 Node-API 调用。缓存 napi_env 以便一般重用，以及在运行于不同 Worker 线程的同一加载项的实例之间传递 napi_env 是不允许的。当本机加载项的实例卸载时，napi_env 将变为无效。此事件的通知通过回调传递给 napi_add_env_cleanup_hook 和 napi_set_instance_data。

node_api_nogc_env#

napi_env 的此变体传递给同步终结器 (node_api_nogc_finalize)。有一部分 Node-API 接受类型为 node_api_nogc_env 的参数作为其第一个参数。这些 API 不访问 JavaScript 引擎的状态，因此可以安全地从同步终结器中调用。允许将类型为 napi_env 的参数传递给这些 API，但是不允许将类型为 node_api_nogc_env 的参数传递给访问 JavaScript 引擎状态的 API。在没有强制转换的情况下尝试这样做，当使用导致在向函数传递不正确的指针类型时发出警告和/或错误的标志编译加载项时，将产生编译器警告或错误。从同步终结器调用此类 API 最终会导致应用程序终止。

napi_value#

这是一个不透明的指针，用于表示 JavaScript 值。

napi_threadsafe_function#

这是一个不透明的指针，它表示一个 JavaScript 函数，该函数可以通过 napi_call_threadsafe_function() 从多个线程异步调用。

napi_threadsafe_function_release_mode#

要提供给 napi_release_threadsafe_function() 的值，以指示是否立即关闭线程安全函数（napi_tsfn_abort）或仅仅释放（napi_tsfn_release），从而可以通过 napi_acquire_threadsafe_function() 和 napi_call_threadsafe_function() 进行后续使用。

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode; copy

napi_threadsafe_function_call_mode#

要提供给 napi_call_threadsafe_function() 的值，以指示当与线程安全函数关联的队列已满时调用是否应阻塞。

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode; copy

Node-API 内存管理类型#

napi_handle_scope#

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

句柄范围使用 napi_open_handle_scope 创建，并使用 napi_close_handle_scope 销毁。关闭范围可以向 GC 指示在句柄范围的生命期内创建的所有 napi_value 不再从当前堆栈帧中引用。

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

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。

Node-API 回调类型#

napi_callback_info#

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

napi_callback#

用户提供的本机函数的函数指针类型，这些函数将通过 Node-API 公开给 JavaScript。回调函数应满足以下签名

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

除非出于 对象生命周期管理 中讨论的原因，否则在 napi_callback 中创建句柄和/或回调范围是没有必要的。

node_api_nogc_finalize#

附加组件提供函数的函数指针类型，允许用户在外部所有权的数据准备清理时收到通知，因为与之关联的对象已被垃圾回收。用户必须提供一个满足以下签名的函数，该函数将在对象收集时被调用。目前，node_api_nogc_finalize 可用于找出具有外部数据的对象被收集的时间。

typedef void (*node_api_nogc_finalize)(node_api_nogc_env env,
                                      void* finalize_data,
                                      void* finalize_hint); copy

除非出于 对象生命周期管理 中讨论的原因，否则在函数体中创建句柄和/或回调范围是没有必要的。

由于这些函数可能在 JavaScript 引擎无法执行 JavaScript 代码的状态下被调用，因此只能调用接受 node_api_nogc_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_nogc_env 作为其第一个参数的 Node-API 调用，否则应用程序将终止并显示适当的错误消息。可以通过定义 NODE_API_EXPERIMENTAL_NOGC_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_nogc_finalize。可以通过定义 NODE_API_EXPERIMENTAL_NOGC_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 的数据。

函数的主体应在函数的末尾启动异步清理操作，在函数的末尾，必须在调用 napi_remove_async_cleanup_hook 时传递 handle。

错误处理#

Node-API 同时使用返回值和 JavaScript 异常进行错误处理。以下部分解释了每种情况的方法。

返回值#

所有 Node-API 函数都共享相同的错误处理模式。所有 API 函数的返回类型为 napi_status。

如果请求成功并且没有抛出未捕获的 JavaScript 异常，则返回值将为 napi_ok。如果发生错误并且抛出异常，则将返回错误的 napi_status 值。如果抛出异常，但没有发生错误，则将返回 napi_pending_exception。

如果返回的值不是 napi_ok 或 napi_pending_exception，则必须调用 napi_is_exception_pending 来检查是否有异常挂起。有关详细信息，请参阅异常部分。

napi_status 值的完整可能集合在 napi_api_types.h 中定义。

napi_status 返回值提供发生错误的与 VM 无关的表示形式。在某些情况下，能够获取更详细的信息（包括表示错误的字符串以及特定于 VM（引擎）的信息）很有用。

为了检索此信息，提供了 napi_get_last_error_info，它返回一个 napi_extended_error_info 结构。napi_extended_error_info 结构的格式如下

typedef struct napi_extended_error_info {
  const char* error_message;
  void* engine_reserved;
  uint32_t engine_error_code;
  napi_status error_code;
}; copy

• error_message：发生的错误的文本表示形式。
• engine_reserved：仅供引擎使用的模糊句柄。
• engine_error_code：特定于 VM 的错误代码。
• error_code：上一个错误的 Node-API 状态代码。

napi_get_last_error_info 返回上一个 Node-API 调用的信息。

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

napi_get_last_error_info#

napi_status
napi_get_last_error_info(node_api_nogc_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。

异常#

任何 Node-API 函数调用都可能导致挂起的 JavaScript 异常。对于任何 API 函数都是如此，即使那些可能不会导致 JavaScript 执行的函数也是如此。

如果函数返回的 napi_status 为 napi_ok，则没有异常挂起，并且不需要采取其他操作。如果返回的 napi_status 不是 napi_ok 或 napi_pending_exception，为了尝试恢复并继续，而不是立即返回，必须调用 napi_is_exception_pending 来确定是否存在挂起的异常。

在许多情况下，当调用 Node-API 函数并且异常已经挂起时，该函数将立即返回，其 napi_status 为 napi_pending_exception。但是，并非所有函数都是这种情况。Node-API 允许调用函数的子集，以便在返回到 JavaScript 之前进行一些最小的清理。在这种情况下，napi_status 将反映函数的状态。它不会反映以前的挂起异常。为避免混淆，请在每次函数调用后检查错误状态。

当异常挂起时，可以采用以下两种方法之一。

第一种方法是进行任何适当的清理，然后返回，以便执行将返回到 JavaScript。作为返回到 JavaScript 的一部分，异常将在调用本机方法的 JavaScript 代码中的点处抛出。当异常挂起时，大多数 Node-API 调用的行为是未指定的，许多调用只会返回 napi_pending_exception，因此尽可能少地执行操作，然后返回到 JavaScript，以便可以处理异常。

第二种方法是尝试处理异常。在某些情况下，本机代码可以捕获异常，采取适当的操作，然后继续。仅在已知可以安全处理异常的特定情况下才建议使用此方法。在这些情况下，可以使用 napi_get_and_clear_last_exception 来获取并清除异常。如果成功，result 将包含对上一个抛出的 JavaScript Object 的句柄。如果在检索异常后确定无法处理异常，则可以使用 napi_throw 重新抛出异常，其中 error 是要抛出的 JavaScript 值。

如果本机代码需要抛出异常或确定 napi_value 是否是 JavaScript Error 对象的实例，还可以使用以下实用函数：napi_throw_error、napi_throw_type_error、napi_throw_range_error、node_api_throw_syntax_error 和 napi_is_error。

如果本机代码需要创建 Error 对象，还可以使用以下实用函数：napi_create_error、napi_create_type_error、napi_create_range_error 和 node_api_create_syntax_error，其中 result 是引用新创建的 JavaScript Error 对象的 napi_value。

Node.js 项目正在向所有内部生成的错误添加错误代码。目标是让应用程序对所有错误检查使用这些错误代码。关联的错误消息将保留，但仅用于日志记录和显示，并预期消息可以在不应用 SemVer 的情况下更改。为了使用 Node-API 支持此模型（在内部功能和模块特定功能中，因为这是良好做法），throw_ 和 create_ 函数采用一个可选代码参数，该参数是添加到错误对象的代码的字符串。如果可选参数为 NULL，则不会将任何代码与错误关联。如果提供了代码，则与错误关联的名称也会更新为

originalName [code] copy

其中 originalName 是与错误关联的原始名称，code 是提供的代码。例如，如果代码是 'ERR_ERROR_1' 并且正在创建 TypeError，则名称将为

TypeError [ERR_ERROR_1] copy

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。

对象生命周期管理#

在进行 Node-API 调用时，底层 VM 中堆中对象的句柄可能会作为 napi_values 返回。这些句柄必须将对象保持“活动”状态，直到本机代码不再需要它们，否则这些对象可能会在本地代码完成使用之前被收集。

在返回对象句柄时，它们将与“作用域”关联。默认作用域的寿命与本机方法调用的寿命相关联。结果是，默认情况下，句柄保持有效，并且与这些句柄关联的对象将在本机方法调用的寿命期内保持活动状态。

然而，在许多情况下，句柄保持有效的时间必须比本机方法的时间短或长。以下部分描述了可用于更改句柄寿命（使其不同于默认值）的 Node-API 函数。

使句柄寿命短于本机方法#

通常需要使句柄的生命周期短于原生方法的生命周期。例如，考虑一个原生方法，它有一个循环，该循环遍历大数组中的元素

for (int i = 0; i < 1000000; i++) {
  napi_value result;
  napi_status status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // do something with element
} copy

这将导致创建大量句柄，消耗大量资源。此外，即使原生代码只能使用最新的句柄，所有关联的对象也将保持活动状态，因为它们都共享相同的范围。

为了处理此情况，Node-API 提供了建立一个新“范围”的能力，新创建的句柄将与该范围关联。一旦不再需要这些句柄，就可以“关闭”范围，并且与该范围关联的所有句柄都将失效。可用于打开/关闭范围的方法是 napi_open_handle_scope 和 napi_close_handle_scope。

Node-API 仅支持范围的单个嵌套层次结构。任何时候只有一个活动范围，并且所有新句柄都将在其活动期间与该范围关联。范围必须按打开它们的相反顺序关闭。此外，在原生方法中创建的所有范围都必须在从该方法返回之前关闭。

以较早的示例为例，添加对 napi_open_handle_scope 和 napi_close_handle_scope 的调用将确保在循环执行期间最多只有一个句柄有效

for (int i = 0; i < 1000000; i++) {
  napi_handle_scope scope;
  napi_status status = napi_open_handle_scope(env, &scope);
  if (status != napi_ok) {
    break;
  }
  napi_value result;
  status = napi_get_element(env, object, i, &result);
  if (status != napi_ok) {
    break;
  }
  // do something with element
  status = napi_close_handle_scope(env, scope);
  if (status != napi_ok) {
    break;
  }
} copy

在嵌套范围时，有时需要来自内部范围的句柄超出该范围的生命周期。Node-API 支持“可转义范围”以支持这种情况。可转义范围允许提升一个句柄，以便它“转义”当前范围，并且句柄的生命周期从当前范围变为外部范围。

可用于打开/关闭可转义范围的方法是 napi_open_escapable_handle_scope 和 napi_close_escapable_handle_scope。

提升句柄的请求是通过 napi_escape_handle 发出的，它只能调用一次。

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_value 返回的普通句柄是不可能的。普通句柄的寿命由作用域管理，并且所有作用域都必须在本机方法结束之前关闭。

Node-API 提供了创建对值进行持久引用方法。目前，Node-API 仅允许为有限的值类型（包括对象、外部、函数和符号）创建引用。

每个引用都有一个关联的计数，其值为 0 或更高，它决定了引用是否将使相应的值保持活动状态。计数为 0 的引用不会阻止值被收集。对象（对象、函数、外部）和符号类型的值正在变成“弱”引用，并且在它们未被收集时仍然可以访问它们。任何大于 0 的计数都将阻止值被收集。

符号值具有不同的类型。真正的弱引用行为仅受使用 napi_create_symbol 函数或 JavaScript Symbol() 构造函数调用创建的本地符号支持。使用 node_api_symbol_for 函数或 JavaScript Symbol.for() 函数调用创建的全局注册符号始终保持强引用，因为垃圾回收器不会回收它们。对于众所周知的符号（例如 Symbol.iterator）也是如此。它们也永远不会被垃圾回收器回收。

引用可以创建为具有初始引用计数。然后可以通过 napi_reference_ref 和 napi_reference_unref 修改计数。如果在引用的计数为 0 时回收对象，则对获取与引用关联的对象的所有后续调用 napi_get_reference_value 将为返回的 napi_value 返回 NULL。尝试对对象已回收的引用的 napi_reference_ref 进行调用会导致错误。

一旦不再需要引用，就必须删除引用。删除引用后，它将不再阻止回收相应对象。如果未能删除持久引用，则会导致“内存泄漏”，持久引用的本机内存和堆上的相应对象将永远保留。

可以创建多个持久引用来引用同一对象，每个引用都会根据其各自的计数使对象保持活动状态或不保持活动状态。对同一对象的多个持久引用可能会意外地使本机内存保持活动状态。持久引用的本机结构必须保持活动状态，直到执行引用的对象的析构函数为止。如果为同一对象创建了新的持久引用，则不会运行该对象的析构函数，并且由较早的持久引用指向的本机内存不会被释放。如果可能，可以通过调用 napi_delete_reference 和 napi_reference_unref 来避免这种情况。

更改历史

• 实验性（定义了 NAPI_EXPERIMENTAL）

  可以为所有值类型创建引用。新支持的值类型不支持弱引用语义，并且当引用计数变为 0 时，这些类型的值将被释放，并且无法再从引用中访问它们。

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。

在当前 Node.js 环境退出时进行清理#

虽然 Node.js 进程通常会在退出时释放其所有资源，但 Node.js 的嵌入者或未来的 Worker 支持可能要求附加组件注册清理挂钩，该挂钩将在当前 Node.js 环境退出后运行。

Node-API 提供了用于注册和取消注册此类回调的函数。当运行这些回调时，附加组件持有的所有资源都应释放。

napi_add_env_cleanup_hook#

NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_nogc_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_nogc_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_nogc_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 值上调用。

Node.js 环境退出时的最终化#

Node.js 环境可能会在不允许执行 JavaScript 的情况下尽快在任意时间被销毁，就像在 worker.terminate() 的请求中一样。当环境被销毁时，JavaScript 对象、线程安全函数和环境实例数据的已注册 napi_finalize 回调将立即且独立地被调用。

napi_finalize 回调的调用在手动注册的清理钩子之后安排。为了确保在环境关闭期间加载项最终化的正确顺序，以避免在 napi_finalize 回调中使用后释放，加载项应使用 napi_add_env_cleanup_hook 和 napi_add_async_cleanup_hook 注册一个清理钩子，以正确顺序手动释放已分配的资源。

模块注册#

Node-API 模块的注册方式与其他模块类似，只是不使用 NODE_MODULE 宏，而是使用以下内容

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init) copy

下一个不同之处是 Init 方法的签名。对于 Node-API 模块，它如下所示

napi_value Init(napi_env env, napi_value exports); copy

Init 的返回值被视为模块的 exports 对象。Init 方法通过 exports 参数传递一个空对象作为一种便利。如果 Init 返回 NULL，则作为 exports 传递的参数由模块导出。Node-API 模块不能修改 module 对象，但可以将任何内容指定为模块的 exports 属性。

将方法 hello 作为函数添加，以便可以将其作为附加组件提供的函数进行调用

napi_value Init(napi_env env, napi_value exports) {
  napi_status status;
  napi_property_descriptor desc = {
    "hello",
    NULL,
    Method,
    NULL,
    NULL,
    NULL,
    napi_writable | napi_enumerable | napi_configurable,
    NULL
  };
  status = napi_define_properties(env, exports, 1, &desc);
  if (status != napi_ok) return NULL;
  return exports;
} copy

设置一个函数，以便由附加组件的 require() 返回

napi_value Init(napi_env env, napi_value exports) {
  napi_value method;
  napi_status status;
  status = napi_create_function(env, "exports", NAPI_AUTO_LENGTH, Method, NULL, &method);
  if (status != napi_ok) return NULL;
  return method;
} copy

定义一个类，以便可以创建新实例（通常与 Object wrap 一起使用）

// NOTE: partial example, not all referenced code is included
napi_value Init(napi_env env, napi_value exports) {
  napi_status status;
  napi_property_descriptor properties[] = {
    { "value", NULL, NULL, GetValue, SetValue, NULL, napi_writable | napi_configurable, NULL },
    DECLARE_NAPI_METHOD("plusOne", PlusOne),
    DECLARE_NAPI_METHOD("multiply", Multiply),
  };

  napi_value cons;
  status =
      napi_define_class(env, "MyObject", New, NULL, 3, properties, &cons);
  if (status != napi_ok) return NULL;

  status = napi_create_reference(env, cons, 1, &constructor);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "MyObject", cons);
  if (status != napi_ok) return NULL;

  return exports;
} copy

你还可以使用 NAPI_MODULE_INIT 宏，它充当 NAPI_MODULE 的简写并定义一个 Init 函数

NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {
  napi_value answer;
  napi_status result;

  status = napi_create_int64(env, 42, &answer);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "answer", answer);
  if (status != napi_ok) return NULL;

  return exports;
} copy

参数 env 和 exports 提供给 NAPI_MODULE_INIT 宏的主体。

所有 Node-API 附加组件都是上下文感知的，这意味着它们可以被加载多次。在声明此类模块时有一些设计注意事项。上下文感知附加组件 的文档提供了更多详细信息。

变量 env 和 exports 将在宏调用后的函数主体中可用。

有关在对象上设置属性的更多详细信息，请参阅 使用 JavaScript 属性 一节。

有关一般构建附加组件模块的更多详细信息，请参阅现有的 API。

使用 JavaScript 值#

Node-API 公开了一组 API，用于创建所有类型的 JavaScript 值。其中一些类型记录在 第 6 节 中ECMAScript 语言规范。

从根本上讲，这些 API 用于执行以下操作之一

1. 创建一个新的 JavaScript 对象
2. 从原始 C 类型转换为 Node-API 值
3. 从 Node-API 值转换为原始 C 类型
4. 获取包括 undefined 和 null 在内的全局实例

Node-API 值由类型 napi_value 表示。任何需要 JavaScript 值的 Node-API 调用都会采用 napi_value。在某些情况下，API 会预先检查 napi_value 的类型。但是，为了获得更好的性能，最好由调用者确保有问题的 napi_value 是 API 预期的 JavaScript 类型。

枚举类型#

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 语言规范的 第 6.1 节 中描述的类型。除了该节中的类型外，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 语言规范 的 第 22.2 节 中的枚举元素对应于此。

对象创建函数#

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 语言规范的 第 22.1 节 中进行了描述。

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 的长度属性设置为传入的长度参数。但是，在创建数组时，VM 并不保证预先分配底层缓冲区。这种行为留给底层 VM 实现。如果缓冲区必须是可通过 C 直接读取和/或写入的连续内存块，请考虑使用 napi_create_external_arraybuffer。

JavaScript 数组在 ECMAScript 语言规范的 第 22.1 节 中进行了描述。

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 语言规范的 第 24.1 节 中进行了描述。

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的底层数据缓冲区的指针。result_data可以通过传递NULL来选择性地忽略。
• [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：自 1970 年 1 月 1 日 UTC 以来以毫秒为单位的 ECMAScript 时间值。
• [out] result：表示 JavaScript Date的napi_value。

如果 API 成功，则返回 napi_ok。

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

此 API 分配一个 JavaScript Date对象。

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

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：在收集期间传递给 finalize 回调的可选提示。
• [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：在收集期间传递给 finalize 回调的可选提示。
• [out] result：表示 JavaScript ArrayBuffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

除了 Node.js 以外的其他一些运行时已不再支持外部缓冲区。在 Node.js 以外的运行时，此方法可能会返回 napi_no_external_buffers_allowed 以指示不支持外部缓冲区。其中一个运行时是 Electron，如本问题中所述 electron/issues/35801。

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

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

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

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

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：在收集期间传递给 finalize 回调的可选提示。
• [out] result：表示 node::Buffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

除了 Node.js 以外的其他一些运行时已不再支持外部缓冲区。在 Node.js 以外的运行时，此方法可能会返回 napi_no_external_buffers_allowed 以指示不支持外部缓冲区。其中一个运行时是 Electron，如本问题中所述 electron/issues/35801。

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

此 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 语言规范的 第 6.1.7 节 中进行了描述。

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 语言规范的 第 19.4 节 中进行了描述。

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 语言规范的 第 19.4 节 中进行了描述。

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 语言规范的 第 22.2 节 中进行了描述。

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 语言规范的 第 24.3 节 中进行了描述。

从 C 类型转换为 Node-API 的函数#

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 语言规范的 第 6.1.6 节 中进行了描述。

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 语言规范的 第 6.1.6 节 中进行了描述。

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 语言规范的 第 6.1.6 节 中进行了描述。请注意，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 语言规范的 第 6.1.6 节 中进行了描述。

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 语言规范的 第 6.1.4 节 中进行了描述。

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：加载项正在运行的环境。如果字符串作为工作程序或主 Node.js 实例终止的一部分被收集，则此值可能为 null。
  • [in] data：这是作为 void* 指针的 str 值。
  • [in] finalize_hint：这是提供给 API 的 finalize_hint 值。 napi_finalize 提供了更多详细信息。此参数是可选的。传递 null 值表示加载项不需要在收集相应的 JavaScript 字符串时收到通知。
• [in] finalize_hint：在收集期间传递给 finalize 回调的可选提示。
• [out] result：表示 JavaScript string 的 napi_value。
• [out] copied：字符串是否已复制。如果是，则最终确定程序已调用以销毁 str。

如果 API 成功，则返回 napi_ok。

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

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

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：字符串的长度（以双字节代码单元为单位），如果以空字符结尾，则为 NAPI_AUTO_LENGTH。
• [out] result：表示 JavaScript string 的 napi_value。

如果 API 成功，则返回 napi_ok。

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

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

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：字符串的长度（以双字节代码单元为单位），如果以空字符结尾，则为 NAPI_AUTO_LENGTH。
• [in] finalize_callback：在收集字符串时调用的函数。该函数将使用以下参数调用
  • [in] env：加载项正在运行的环境。如果字符串作为工作程序或主 Node.js 实例终止的一部分被收集，则此值可能为 null。
  • [in] data：这是作为 void* 指针的 str 值。
  • [in] finalize_hint：这是提供给 API 的 finalize_hint 值。 napi_finalize 提供了更多详细信息。此参数是可选的。传递 null 值表示加载项不需要在收集相应的 JavaScript 字符串时收到通知。
• [in] finalize_hint：在收集期间传递给 finalize 回调的可选提示。
• [out] result：表示 JavaScript string 的 napi_value。
• [out] copied：字符串是否已复制。如果是，则最终确定程序已调用以销毁 str。

如果 API 成功，则返回 napi_ok。

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

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

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 语言规范的 第 6.1.4 节 中进行了描述。

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：字符串的长度（以双字节代码单元为单位），如果以空字符结尾，则为 NAPI_AUTO_LENGTH。
• [out] result：一个 napi_value，表示一个经过优化的 JavaScript string，用作对象的属性键。

如果 API 成功，则返回 napi_ok。

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

包括 V8 在内的许多 JavaScript 引擎使用内部字符串作为键来设置和获取属性值。它们通常使用哈希表来创建和查找此类字符串。虽然它增加了每个键创建的成本，但通过启用字符串指针的比较而不是整个字符串的比较，它提高了之后的性能。

如果新的 JavaScript 字符串打算用作属性键，那么对于某些 JavaScript 引擎，使用 node_api_create_property_key_utf16 函数将更有效。否则，请使用 napi_create_string_utf16 或 node_api_create_external_string_utf16 函数，因为使用此方法创建/存储字符串可能会产生额外的开销。

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

从 Node-API 转换为 C 类型的函数#

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 语言规范的 第 22.1.4.1 节 中进行了描述。

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 的 napi_value。
• [out] data：ArrayBuffer 的底层数据缓冲区。如果 byte_length 为 0，则它可能是 NULL 或任何其他指针值。
• [out] byte_length：底层数据缓冲区的字节长度。

如果 API 成功，则返回 napi_ok。

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

警告：使用此 API 时请小心。底层数据缓冲区的生命周期由 ArrayBuffer 管理，即使在返回后也是如此。使用此 API 的一种可能安全的方法是结合使用 napi_create_reference，它可用于保证对 ArrayBuffer 的生命周期进行控制。只要没有调用可能触发 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 的底层数据缓冲区。如果 length 为 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 下层的 data 缓冲区，已根据 byte_offset 值调整，以便指向 TypedArray 中的第一个元素。如果数组的长度为 0，则这可能是 NULL 或任何其他指针值。
• [out] arraybuffer: TypedArray 下层的 ArrayBuffer。
• [out] byte_offset: 数组的第一个元素所在的底层本机数组中的字节偏移量。data 参数的值已调整，以便 data 指向数组中的第一个元素。因此，本机数组的第一个字节将位于 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 下层的 data 缓冲区。如果 byte_length 为 0，则这可能是 NULL 或任何其他指针值。
• [out] arraybuffer: DataView 下层的 ArrayBuffer。
• [out] byte_offset: 从其开始投影 DataView 的 data 缓冲区中的字节偏移量。

如果 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 double 基本类型。

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 double 原语等效项。

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

此 API 返回给定 JavaScript number 的 C double 原语等效项。

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 字节代码单元为单位，不包括空终止符）将返回到 result 中。
• [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 作为 uint32_t 的 C 原始等效项。

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

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

获取全局实例的函数#

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 对象。

处理 JavaScript 值和抽象操作#

Node-API 公开了一组 API，用于对 JavaScript 值执行一些抽象操作。其中一些操作在 第 7 节 中进行了说明，该节来自 ECMAScript 语言规范。

这些 API 支持执行以下操作之一

1. 将 JavaScript 值强制转换为特定的 JavaScript 类型（例如 number 或 string）。
2. 检查 JavaScript 值的类型。
3. 检查两个 JavaScript 值是否相等。

napi_coerce_to_bool#

napi_status napi_coerce_to_bool(napi_env env,
                                napi_value value,
                                napi_value* result) copy

• [in] env：调用 API 所处的环境。
• [in] value：要强制转换的 JavaScript 值。
• [out] result：表示强制转换的 JavaScript Boolean 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 实现抽象操作 ToBoolean()，如 ECMAScript 语言规范的 第 7.1.2 节 中所定义。

napi_coerce_to_number#

napi_status napi_coerce_to_number(napi_env env,
                                  napi_value value,
                                  napi_value* result) copy

• [in] env：调用 API 所处的环境。
• [in] value：要强制转换的 JavaScript 值。
• [out] result：表示强制转换的 JavaScript number 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 实现抽象操作 ToNumber()，如 ECMAScript 语言规范的 第 7.1.3 节 中所定义。如果传入的值是一个对象，则此函数可能会运行 JS 代码。

napi_coerce_to_object#

napi_status napi_coerce_to_object(napi_env env,
                                  napi_value value,
                                  napi_value* result) copy

• [in] env：调用 API 所处的环境。
• [in] value：要强制转换的 JavaScript 值。
• [out] result：表示强制转换的 JavaScript Object 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 实现抽象操作 ToObject()，如 ECMAScript 语言规范的 第 7.1.13 节 中所定义。

napi_coerce_to_string#

napi_status napi_coerce_to_string(napi_env env,
                                  napi_value value,
                                  napi_value* result) copy

• [in] env：调用 API 所处的环境。
• [in] value：要强制转换的 JavaScript 值。
• [out] result：表示强制转换的 JavaScript string 的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 实现了抽象操作 ToString()，如 ECMAScript 语言规范的 第 7.1.13 节 中所定义。如果传入的值是一个对象，此函数可能会运行 JS 代码。

napi_typeof#

napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result) copy

• [in] env：调用 API 所处的环境。
• [in] value：要查询其类型的 JavaScript 值。
• [out] result：JavaScript 值的类型。

如果 API 成功，则返回 napi_ok。

• 如果 value 的类型不是已知的 ECMAScript 类型，并且 value 不是外部值，则返回 napi_invalid_arg。

此 API 表示类似于在对象上调用 typeof 运算符的行为，如 ECMAScript 语言规范的 第 12.5.5 节 中所定义。但是，有一些区别

1. 它支持检测外部值。
2. 它将 null 检测为一个单独的类型，而 ECMAScript typeof 会检测为 object。

如果 value 具有无效的类型，则会返回一个错误。

napi_instanceof#

napi_status napi_instanceof(napi_env env,
                            napi_value object,
                            napi_value constructor,
                            bool* result) copy

• [in] env：调用 API 所处的环境。
• [in] object：要检查的 JavaScript 值。
• [in] constructor：要针对其进行检查的构造函数的 JavaScript 函数对象。
• [out] result：如果 object instanceof constructor 为真，则设置为真的布尔值。

如果 API 成功，则返回 napi_ok。

此 API 表示在对象上调用 instanceof 运算符，如 ECMAScript 语言规范的 第 12.10.4 节 中所定义。

napi_is_array#

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

• [in] env：调用 API 所处的环境。
• [in] value：要检查的 JavaScript 值。
• [out] result：给定的对象是否是一个数组。

如果 API 成功，则返回 napi_ok。

此 API 表示在对象上调用 IsArray 操作，如 ECMAScript 语言规范的 第 7.2.2 节 中所定义。

napi_is_arraybuffer#

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

• [in] env：调用 API 所处的环境。
• [in] value：要检查的 JavaScript 值。
• [out] result：给定的对象是否是一个 ArrayBuffer。

如果 API 成功，则返回 napi_ok。

此 API 检查传入的 Object 是否是一个数组缓冲区。

napi_is_buffer#

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

• [in] env：调用 API 所处的环境。
• [in] value：要检查的 JavaScript 值。
• [out] result：给定的 napi_value 是否表示一个 node::Buffer 或 Uint8Array 对象。

如果 API 成功，则返回 napi_ok。

此 API 检查传入的 Object 是否是一个缓冲区或 Uint8Array。如果调用者需要检查该值是否是一个 Uint8Array，则应优先使用 napi_is_typedarray。

napi_is_date#

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

• [in] env：调用 API 所处的环境。
• [in] value：要检查的 JavaScript 值。
• [out] result：给定的 napi_value 是否表示 JavaScript Date 对象。

如果 API 成功，则返回 napi_ok。

此 API 检查传入的 Object 是否为日期。

napi_is_error#

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

• [in] env：调用 API 所处的环境。
• [in] value：要检查的 JavaScript 值。
• [out] result：给定的 napi_value 是否表示 Error 对象。

如果 API 成功，则返回 napi_ok。

此 API 检查传入的 Object 是否为 Error。

napi_is_typedarray#

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

• [in] env：调用 API 所处的环境。
• [in] value：要检查的 JavaScript 值。
• [out] result：给定的 napi_value 是否表示 TypedArray。

如果 API 成功，则返回 napi_ok。

此 API 检查传入的 Object 是否为类型化数组。

napi_is_dataview#

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

• [in] env：调用 API 所处的环境。
• [in] value：要检查的 JavaScript 值。
• [out] result：给定的 napi_value 是否表示 DataView。

如果 API 成功，则返回 napi_ok。

此 API 检查传入的 Object 是否为 DataView。

napi_strict_equals#

napi_status napi_strict_equals(napi_env env,
                               napi_value lhs,
                               napi_value rhs,
                               bool* result) copy

• [in] env：调用 API 所处的环境。
• [in] lhs：要检查的 JavaScript 值。
• [in] rhs：要检查的 JavaScript 值。
• [out] result：两个 napi_value 对象是否相等。

如果 API 成功，则返回 napi_ok。

此 API 表示在 ECMAScript 语言规范的 第 7.2.14 节 中定义的严格相等算法的调用。

napi_detach_arraybuffer#

napi_status napi_detach_arraybuffer(napi_env env,
                                    napi_value arraybuffer) copy

• [in] env：调用 API 所处的环境。
• [in] arraybuffer：要分离的 JavaScript ArrayBuffer。

如果 API 成功，则返回 napi_ok。如果传入不可分离的 ArrayBuffer，则返回 napi_detachable_arraybuffer_expected。

通常，如果 ArrayBuffer 之前已分离，则它不可分离。引擎可能会对 ArrayBuffer 是否可分离施加其他条件。例如，V8 要求 ArrayBuffer 是外部的，即使用 napi_create_external_arraybuffer 创建的。

此 API 表示在 ECMAScript 语言规范的 第 24.1.1.3 节 中定义的 ArrayBuffer 分离操作的调用。

napi_is_detached_arraybuffer#

napi_status napi_is_detached_arraybuffer(napi_env env,
                                         napi_value arraybuffer,
                                         bool* result) copy

• [in] env：调用 API 所处的环境。
• [in] arraybuffer：要检查的 JavaScript ArrayBuffer。
• [out] result：arraybuffer 是否已分离。

如果 API 成功，则返回 napi_ok。

如果 ArrayBuffer 的内部数据为 null，则认为该 ArrayBuffer 已分离。

此 API 表示对 ArrayBuffer IsDetachedBuffer 操作的调用，如 ECMAScript 语言规范的 第 24.1.1.2 节 中所定义。

使用 JavaScript 属性#

Node-API 公开了一组 API，用于获取和设置 JavaScript 对象上的属性。其中一些类型在 第 7 节 中记录在案，该节属于 ECMAScript 语言规范。

JavaScript 中的属性表示为键和值的元组。从根本上讲，Node-API 中的所有属性键都可以表示为以下形式之一

• 命名：一个简单的 UTF8 编码字符串
• 整数索引：由 uint32_t 表示的索引值
• JavaScript 值：这些值在 Node-API 中由 napi_value 表示。这可以是表示 string、number 或 symbol 的 napi_value。

Node-API 值由类型 napi_value 表示。任何需要 JavaScript 值的 Node-API 调用都会采用 napi_value。但是，调用方有责任确保有问题的 napi_value 是 API 预期的 JavaScript 类型。

本节记录的 API 提供了一个简单的界面，用于获取和设置由 napi_value 表示的任意 JavaScript 对象上的属性。

例如，考虑以下 JavaScript 代码片段

const obj = {};
obj.myProp = 123; copy

可以使用以下代码片段使用 Node-API 值完成等效操作

napi_status status = napi_generic_failure;

// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;

// Create a napi_value for 123
status = napi_create_int32(env, 123, &value);
if (status != napi_ok) return status;

// obj.myProp = 123
status = napi_set_named_property(env, obj, "myProp", value);
if (status != napi_ok) return status; copy

可以类似地设置索引属性。考虑以下 JavaScript 代码片段

const arr = [];
arr[123] = 'hello'; copy

可以使用以下代码片段使用 Node-API 值完成等效操作

napi_status status = napi_generic_failure;

// const arr = [];
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;

// Create a napi_value for 'hello'
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &value);
if (status != napi_ok) return status;

// arr[123] = 'hello';
status = napi_set_element(env, arr, 123, value);
if (status != napi_ok) return status; copy

可以使用本节中描述的 API 检索属性。考虑以下 JavaScript 代码片段

const arr = [];
const value = arr[123]; copy

以下是 Node-API 对应项的近似等效项

napi_status status = napi_generic_failure;

// const arr = []
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;

// const value = arr[123]
status = napi_get_element(env, arr, 123, &value);
if (status != napi_ok) return status; copy

最后，出于性能原因，也可以在对象上定义多个属性。考虑以下 JavaScript

const obj = {};
Object.defineProperties(obj, {
  'foo': { value: 123, writable: true, configurable: true, enumerable: true },
  'bar': { value: 456, writable: true, configurable: true, enumerable: true },
}); copy

以下是 Node-API 对应项的近似等效项

napi_status status = napi_status_generic_failure;

// const obj = {};
napi_value obj;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;

// Create napi_values for 123 and 456
napi_value fooValue, barValue;
status = napi_create_int32(env, 123, &fooValue);
if (status != napi_ok) return status;
status = napi_create_int32(env, 456, &barValue);
if (status != napi_ok) return status;

// Set the properties
napi_property_descriptor descriptors[] = {
  { "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },
  { "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }
}
status = napi_define_properties(env,
                                obj,
                                sizeof(descriptors) / sizeof(descriptors[0]),
                                descriptors);
if (status != napi_ok) return status; copy

结构#

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 之外，它们对应于 第 6.1.7.1 节 中列出的属性ECMAScript 语言规范。它们可以是以下一个或多个位标志

• napi_default：未在属性上设置显式属性。默认情况下，属性是只读的、不可枚举的且不可配置的。
• napi_writable：属性是可写的。
• napi_enumerable：属性是可枚举的。
• napi_configurable：属性是可配置的，如 第 6.1.7.1 节 中定义的ECMAScript 语言规范。
• 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：如果属性是数据属性，则通过获取属性访问检索的值。如果传入此值，请将 getter、setter、method 和 data 设置为 NULL（因为这些成员不会被使用）。
• getter：在执行属性的获取访问时要调用的函数。如果传入此值，请将 value 和 method 设置为 NULL（因为这些成员不会被使用）。当从 JavaScript 代码访问属性（或使用 Node-API 调用对属性执行获取）时，运行时会隐式调用给定函数。napi_callback 提供了更多详细信息。
• setter：在对属性执行设置访问时调用的函数。如果传入此函数，则将 value 和 method 设置为 NULL（因为不会使用这些成员）。当从 JavaScript 代码设置属性（或使用 Node-API 调用对属性执行设置）时，运行时会隐式调用给定的函数。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。可以使用 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：表示对象属性名称的 JavaScript 值数组的 napi_value。可以使用 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：元素删除是否成功。result 可以通过传递 NULL 来选择性地忽略。

如果 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 规范的 第 9.1.6 节 中所述）所定义。

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 节 中有描述。

使用 JavaScript 函数#

Node-API 提供了一组 API，允许 JavaScript 代码回调到本机代码。支持回调到本机代码的 Node-API 采用由 napi_callback 类型表示的回调函数。当 JavaScript VM 回调到本机代码时，将调用提供的 napi_callback 函数。本节中记录的 API 允许回调函数执行以下操作

• 获取有关调用回调的上下文的信息。
• 获取传递给回调函数的参数。
• 从回调函数返回一个 napi_value。

此外，Node-API 提供了一组函数，允许从本机代码调用 JavaScript 函数。可以像调用常规 JavaScript 函数调用一样调用函数，也可以作为构造函数调用。

通过 napi_property_descriptor 项的 data 字段传递给此 API 的任何非 NULL 数据都可以与 object 关联，并且只要 object 通过将 object 和数据传递给 napi_add_finalizer 进行垃圾回收，就可以释放 object。

napi_call_function#

NAPI_EXTERN napi_status napi_call_function(napi_env env,
                                           napi_value recv,
                                           napi_value func,
                                           size_t argc,
                                           const napi_value* argv,
                                           napi_value* result); copy

• [in] env：调用 API 所处的环境。
• [in] recv：传递给被调用函数的 this 值。
• [in] func：表示要调用的 JavaScript 函数的 napi_value。
• [in] argc：argv 数组中元素的数量。
• [in] argv：表示作为函数参数传递的 JavaScript 值的 napi_values 数组。
• [out] result：表示返回的 JavaScript 对象的 napi_value。

如果 API 成功，则返回 napi_ok。

此方法允许从本机加载项调用 JavaScript 函数对象。这是从加载项的本机代码返回到 JavaScript 的主要机制。对于在异步操作后调用 JavaScript 的特殊情况，请参阅 napi_make_callback。

示例用例可能如下所示。考虑以下 JavaScript 代码段

function AddTwo(num) {
  return num + 2;
}
global.AddTwo = AddTwo; copy

然后，可以使用以下代码从本机加载项调用上述函数

// Get the function named "AddTwo" on the global object
napi_value global, add_two, arg;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;

status = napi_get_named_property(env, global, "AddTwo", &add_two);
if (status != napi_ok) return;

// const arg = 1337
status = napi_create_int32(env, 1337, &arg);
if (status != napi_ok) return;

napi_value* argv = &arg;
size_t argc = 1;

// AddTwo(arg);
napi_value return_val;
status = napi_call_function(env, global, add_two, argc, argv, &return_val);
if (status != napi_ok) return;

// Convert the result back to a native type
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return; copy

napi_create_function#

napi_status napi_create_function(napi_env env,
                                 const char* utf8name,
                                 size_t length,
                                 napi_callback cb,
                                 void* data,
                                 napi_value* result); copy

• [in] env：调用 API 所处的环境。
• [in] utf8Name：以 UTF8 编码的函数的可选名称。这在 JavaScript 中可见，作为新函数对象的 name 属性。
• [in] length：utf8name 的字节长度，如果以 null 结尾，则为 NAPI_AUTO_LENGTH。
• [in] cb：调用此函数对象时应调用的本机函数。 napi_callback 提供了更多详细信息。
• [in] data：用户提供的上下文数据。稍后调用函数时，此数据将传回函数。
• [out] result：表示新创建函数的 JavaScript 函数对象的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 允许加载项作者在本地代码中创建函数对象。这是允许从 JavaScript 调用加载项的本机代码的主要机制。

此调用后，新创建的函数不会自动在脚本中可见。相反，必须在任何对 JavaScript 可见的任何对象上明确设置一个属性，以便从脚本访问该函数。

为了将函数公开为加载项模块导出的部分，请在 exports 对象上设置新创建的函数。示例模块可能如下所示

napi_value SayHello(napi_env env, napi_callback_info info) {
  printf("Hello\n");
  return NULL;
}

napi_value Init(napi_env env, napi_value exports) {
  napi_status status;

  napi_value fn;
  status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "sayHello", fn);
  if (status != napi_ok) return NULL;

  return exports;
}

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init) copy

根据上述代码，加载项可以从 JavaScript 中使用，如下所示

const myaddon = require('./addon');
myaddon.sayHello(); copy

传递给 require() 的字符串是 binding.gyp 中负责创建 .node 文件的目标的名称。

通过 data 参数传递给此 API 的任何非 NULL 数据都可以与结果 JavaScript 函数（在 result 参数中返回）关联，并在通过 JavaScript 函数和数据传递给 napi_add_finalizer 时释放该函数的垃圾。

JavaScript Function 在 ECMAScript 语言规范的 第 19.2 节 中进行了描述。

napi_get_cb_info#

napi_status napi_get_cb_info(napi_env env,
                             napi_callback_info cbinfo,
                             size_t* argc,
                             napi_value* argv,
                             napi_value* thisArg,
                             void** data) copy

• [in] env：调用 API 所处的环境。
• [in] cbinfo：传递到回调函数的回调信息。
• [in-out] argc：指定提供的 argv 数组的长度并接收实际参数计数。argc 可以通过传递 NULL 来选择性地忽略。
• [out] argv：napi_value 的 C 数组，参数将复制到其中。如果参数多于提供的计数，则仅复制请求的参数数。如果提供的参数少于声明的参数，则 argv 的其余部分将填充为表示 undefined 的 napi_value 值。argv 可以通过传递 NULL 来选择性地忽略。
• [out] thisArg：接收调用的 JavaScript this 参数。thisArg 可以通过传递 NULL 来选择性地忽略。
• [out] data：接收回调的数据指针。data 可以通过传递 NULL 来选择性地忽略。

如果 API 成功，则返回 napi_ok。

此方法在回调函数中使用，以检索有关调用的详细信息，例如参数和来自给定回调信息的 this 指针。

napi_get_new_target#

napi_status napi_get_new_target(napi_env env,
                                napi_callback_info cbinfo,
                                napi_value* result) copy

• [in] env：调用 API 所处的环境。
• [in] cbinfo：传递到回调函数的回调信息。
• [out] result：构造函数调用的 new.target。

如果 API 成功，则返回 napi_ok。

此 API 返回构造函数调用的 new.target。如果当前回调不是构造函数调用，则结果为 NULL。

napi_new_instance#

napi_status napi_new_instance(napi_env env,
                              napi_value cons,
                              size_t argc,
                              napi_value* argv,
                              napi_value* result) copy

• [in] env：调用 API 所处的环境。
• [in] cons：表示要作为构造函数调用的 JavaScript 函数的 napi_value。
• [in] argc：argv 数组中元素的数量。
• [in] argv：表示构造函数参数的 JavaScript 值数组，形式为 napi_value。如果 argc 为零，则可以通过传入 NULL 来省略此参数。
• [out] result：表示返回的 JavaScript 对象的 napi_value，在此情况下为构造的对象。

此方法用于使用表示对象构造函数的给定 napi_value 实例化新的 JavaScript 值。例如，考虑以下代码段

function MyObject(param) {
  this.param = param;
}

const arg = 'hello';
const value = new MyObject(arg); copy

以下内容可以使用以下代码段在 Node-API 中近似

// Get the constructor function MyObject
napi_value global, constructor, arg, value;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;

status = napi_get_named_property(env, global, "MyObject", &constructor);
if (status != napi_ok) return;

// const arg = "hello"
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &arg);
if (status != napi_ok) return;

napi_value* argv = &arg;
size_t argc = 1;

// const value = new MyObject(arg)
status = napi_new_instance(env, constructor, argc, argv, &value); copy

如果 API 成功，则返回 napi_ok。

对象包装#

Node-API 提供了一种“包装”C++ 类和实例的方法，以便可以从 JavaScript 调用类构造函数和方法。

1. napi_define_class API 定义了一个 JavaScript 类，其中包含构造函数、静态属性和方法，以及与 C++ 类对应的实例属性和方法。
2. 当 JavaScript 代码调用构造函数时，构造函数回调使用 napi_wrap 将新的 C++ 实例包装在 JavaScript 对象中，然后返回包装对象。
3. 当 JavaScript 代码在类上调用方法或属性访问器时，将调用相应的 napi_callback C++ 函数。对于实例回调，napi_unwrap 获取作为调用目标的 C++ 实例。

对于包装对象，可能很难区分在类原型上调用的函数和在类实例上调用的函数。解决此问题的一种常见模式是保存对类构造函数的持久引用，以便以后进行 instanceof 检查。

napi_value MyClass_constructor = NULL;
status = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor);
assert(napi_ok == status);
bool is_instance = false;
status = napi_instanceof(env, es_this, MyClass_constructor, &is_instance);
assert(napi_ok == status);
if (is_instance) {
  // napi_unwrap() ...
} else {
  // otherwise...
} copy

一旦不再需要引用，就必须释放它。

在某些情况下，napi_instanceof() 不足以确保 JavaScript 对象是特定本机类型的包装器。尤其是在通过静态方法将包装的 JavaScript 对象传回附加组件而不是作为原型方法的 this 值时，会出现这种情况。在这种情况下，有可能错误地解包它们。

const myAddon = require('./build/Release/my_addon.node');

// `openDatabase()` returns a JavaScript object that wraps a native database
// handle.
const dbHandle = myAddon.openDatabase();

// `query()` returns a JavaScript object that wraps a native query handle.
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!');

// There is an accidental error in the line below. The first parameter to
// `myAddon.queryHasRecords()` should be the database handle (`dbHandle`), not
// the query handle (`query`), so the correct condition for the while-loop
// should be
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
  // retrieve records
} copy

在上述示例中，myAddon.queryHasRecords() 是一个接受两个参数的方法。第一个是数据库句柄，第二个是查询句柄。在内部，它解包第一个参数并将结果指针强制转换为本机数据库句柄。然后，它解包第二个参数并将结果指针强制转换为查询句柄。如果参数按错误的顺序传入，强制转换将起作用，但是底层数据库操作很可能会失败，甚至会导致无效的内存访问。

为了确保从第一个参数检索的指针实际上是数据库句柄的指针，同样，从第二个参数检索的指针实际上是查询句柄的指针，queryHasRecords() 的实现必须执行类型验证。在 napi_ref 中保留实例化数据库句柄的 JavaScript 类构造函数和实例化查询句柄的构造函数可以提供帮助，因为然后可以使用 napi_instanceof() 来确保传递给 queryHashRecords() 的实例实际上是正确类型的。

不幸的是，napi_instanceof() 无法防止原型操作。例如，可以将数据库句柄实例的原型设置为查询句柄实例的构造函数的原型。在这种情况下，数据库句柄实例可以显示为查询句柄实例，并且它将通过查询句柄实例的 napi_instanceof() 测试，同时仍然包含对数据库句柄的指针。

为此，Node-API 提供了类型标记功能。

类型标记是一个 128 位整数，对附加组件来说是唯一的。Node-API 提供了 napi_type_tag 结构来存储类型标记。当此类值与 JavaScript 对象或存储在 napi_value 中的 外部 一起传递给 napi_type_tag_object() 时，JavaScript 对象将被“标记”为类型标记。“标记”在 JavaScript 侧不可见。当 JavaScript 对象到达本机绑定时，napi_check_object_type_tag() 可以与原始类型标记一起使用，以确定 JavaScript 对象是否先前使用类型标记“标记”。这创建了一种比 napi_instanceof() 提供的类型检查功能更高的保真度，因为此类类型标记在原型操作和附加组件卸载/重新加载后仍能保留。

继续上述示例，以下框架附加组件实现说明了 napi_type_tag_object() 和 napi_check_object_type_tag() 的用法。

// This value is the type tag for a database handle. The command
//
//   uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// can be used to obtain the two values with which to initialize the structure.
static const napi_type_tag DatabaseHandleTypeTag = {
  0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};

// This value is the type tag for a query handle.
static const napi_type_tag QueryHandleTypeTag = {
  0x9c73317f9fad44a3, 0x93c3920bf3b0ad6a
};

static napi_value
openDatabase(napi_env env, napi_callback_info info) {
  napi_status status;
  napi_value result;

  // Perform the underlying action which results in a database handle.
  DatabaseHandle* dbHandle = open_database();

  // Create a new, empty JS object.
  status = napi_create_object(env, &result);
  if (status != napi_ok) return NULL;

  // Tag the object to indicate that it holds a pointer to a `DatabaseHandle`.
  status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
  if (status != napi_ok) return NULL;

  // Store the pointer to the `DatabaseHandle` structure inside the JS object.
  status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
  if (status != napi_ok) return NULL;

  return result;
}

// Later when we receive a JavaScript object purporting to be a database handle
// we can use `napi_check_object_type_tag()` to ensure that it is indeed such a
// handle.

static napi_value
query(napi_env env, napi_callback_info info) {
  napi_status status;
  size_t argc = 2;
  napi_value argv[2];
  bool is_db_handle;

  status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
  if (status != napi_ok) return NULL;

  // Check that the object passed as the first parameter has the previously
  // applied tag.
  status = napi_check_object_type_tag(env,
                                      argv[0],
                                      &DatabaseHandleTypeTag,
                                      &is_db_handle);
  if (status != napi_ok) return NULL;

  // Throw a `TypeError` if it doesn't.
  if (!is_db_handle) {
    // Throw a TypeError.
    return NULL;
  }
} copy

napi_define_class#

napi_status napi_define_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* result); copy

• [in] env：调用 API 所处的环境。
• [in] utf8name：JavaScript 构造函数的名称。为了清晰起见，建议在包装 C++ 类时使用 C++ 类名。
• [in] length：utf8name 的字节长度，如果以 null 结尾，则为 NAPI_AUTO_LENGTH。
• [in] constructor：处理类实例构造的回调函数。在包装 C++ 类时，此方法必须是具有 napi_callback 签名的静态成员。不能使用 C++ 类构造函数。 napi_callback 提供了更多详细信息。
• [in] data：可选数据，作为回调信息的 data 属性传递给构造函数回调。
• [in] property_count：properties 数组参数中的项数。
• [in] properties：描述类上的静态和实例数据属性、访问器和方法的属性描述符数组。请参阅 napi_property_descriptor。
• [out] result：表示类构造函数的 napi_value。

如果 API 成功，则返回 napi_ok。

定义 JavaScript 类，包括

• 具有类名的 JavaScript 构造函数。在包装相应的 C++ 类时，可以通过 constructor 传递的回调来实例化新的 C++ 类实例，然后将其放置在使用 napi_wrap 构造的 JavaScript 对象实例中。
• 构造函数上的属性，其实现可以调用 C++ 类的相应静态数据属性、访问器和方法（由具有 napi_static 属性的属性描述符定义）。
• 构造函数的 prototype 对象上的属性。在封装 C++ 类时，可以通过属性描述符中给出的静态函数调用 C++ 类的非静态数据属性、访问器和方法，而无需在使用 napi_unwrap 将 C++ 类实例放置在 JavaScript 对象实例中后使用 napi_static 属性。

在封装 C++ 类时，通过 constructor 传递的 C++ 构造函数回调应该是类上的静态方法，该方法调用实际的类构造函数，然后将新的 C++ 实例封装在 JavaScript 对象中，并返回封装对象。有关详细信息，请参阅 napi_wrap。

从 napi_define_class 返回的 JavaScript 构造函数通常会被保存并稍后用于从本机代码构造类的实例，和/或检查提供的值是否为类的实例。在这种情况下，为了防止函数值被垃圾回收，可以使用 napi_create_reference 创建对它的强持久引用，确保引用计数保持 >= 1。

通过 data 参数或 napi_property_descriptor 数组项的 data 字段传递给此 API 的任何非 NULL 数据都可以与结果 JavaScript 构造函数（在 result 参数中返回）相关联，并在类被垃圾回收时通过将 JavaScript 函数和数据传递给 napi_add_finalizer 进行释放。

napi_wrap#

napi_status napi_wrap(napi_env env,
                      napi_value js_object,
                      void* native_object,
                      napi_finalize finalize_cb,
                      void* finalize_hint,
                      napi_ref* result); copy

• [in] env：调用 API 所处的环境。
• [in] js_object：将成为本机对象的封装器的 JavaScript 对象。
• [in] native_object：将封装在 JavaScript 对象中的本机实例。
• [in] finalize_cb：可选的本机回调，当 JavaScript 对象被垃圾回收时，可以使用该回调释放本机实例。 napi_finalize 提供了更多详细信息。
• [in] finalize_hint：可选的上下文提示，传递给 finalize 回调。
• [out] result：封装对象的可选引用。

如果 API 成功，则返回 napi_ok。

将原生实例包装到 JavaScript 对象中。稍后可以使用 napi_unwrap() 检索原生实例。

当 JavaScript 代码调用使用 napi_define_class() 定义的类的构造函数时，将调用构造函数的 napi_callback。在构造原生类的实例后，回调必须调用 napi_wrap()，以将新构造的实例包装到已创建的 JavaScript 对象中，该对象是构造函数回调的 this 参数。（该 this 对象是从构造函数的 prototype 创建的，因此它已定义所有实例属性和方法。）

通常在包装类实例时，应提供一个 finalize 回调，该回调仅删除作为 finalize 回调的 data 参数接收的原生实例。

可选的返回引用最初是弱引用，这意味着它的引用计数为 0。通常，在需要实例保持有效的异步操作期间，此引用计数会暂时递增。

注意：仅在 finalize 回调调用时，才应通过 napi_delete_reference 删除可选的返回引用（如果已获取）。如果在此之前将其删除，则可能永远不会调用 finalize 回调。因此，在获取引用时，还需要 finalize 回调才能正确处置引用。

Finalizer 回调可能会被延迟，从而留下一个对象已被垃圾回收（并且弱引用无效）但尚未调用 finalizer 的窗口。在对 napi_wrap() 返回的弱引用使用 napi_get_reference_value() 时，你仍应处理空结果。

第二次对对象调用 napi_wrap() 将返回错误。要将另一个原生实例与对象关联，请首先使用 napi_remove_wrap()。

napi_unwrap#

napi_status napi_unwrap(napi_env env,
                        napi_value js_object,
                        void** result); copy

• [in] env：调用 API 所处的环境。
• [in] js_object：与原生实例关联的对象。
• [out] result：指向包装的原生实例的指针。

如果 API 成功，则返回 napi_ok。

检索先前使用 napi_wrap() 包装在 JavaScript 对象中的原生实例。

当 JavaScript 代码调用类上的方法或属性访问器时，将调用相应的 napi_callback。如果回调是针对实例方法或访问器，则回调的 this 参数是包装器对象；可以通过对包装器对象调用 napi_unwrap() 来获取作为调用的目标的包装的 C++ 实例。

napi_remove_wrap#

napi_status napi_remove_wrap(napi_env env,
                             napi_value js_object,
                             void** result); copy

• [in] env：调用 API 所处的环境。
• [in] js_object：与原生实例关联的对象。
• [out] result：指向包装的原生实例的指针。

如果 API 成功，则返回 napi_ok。

检索先前使用 napi_wrap() 在 JavaScript 对象 js_object 中包装的本机实例，并移除包装。如果与包装关联了完成回调，则当 JavaScript 对象成为垃圾回收时，将不再调用该回调。

napi_type_tag_object#

napi_status napi_type_tag_object(napi_env env,
                                 napi_value js_object,
                                 const napi_type_tag* type_tag); copy

• [in] env：调用 API 所处的环境。
• [in] js_object：要标记的 JavaScript 对象或 外部 对象。
• [in] type_tag：要标记对象的标记。

如果 API 成功，则返回 napi_ok。

将 type_tag 指针的值与 JavaScript 对象或 外部 对象关联。然后可以使用 napi_check_object_type_tag() 将附加到对象上的标记与插件拥有的标记进行比较，以确保对象具有正确的类型。

如果对象已关联类型标记，则此 API 将返回 napi_invalid_arg。

napi_check_object_type_tag#

napi_status napi_check_object_type_tag(napi_env env,
                                       napi_value js_object,
                                       const napi_type_tag* type_tag,
                                       bool* result); copy

• [in] env：调用 API 所处的环境。
• [in] js_object：要检查其类型标记的 JavaScript 对象或 外部 对象。
• [in] type_tag：要与在对象上找到的任何标记进行比较的标记。
• [out] result：给定的类型标记是否与对象上的类型标记匹配。如果在对象上未找到类型标记，则也会返回 false。

如果 API 成功，则返回 napi_ok。

将作为 type_tag 给出的指针与可以在 js_object 上找到的任何指针进行比较。如果在 js_object 上未找到标记，或者如果找到了标记但它与 type_tag 不匹配，则 result 设置为 false。如果找到了标记并且它与 type_tag 匹配，则 result 设置为 true。

napi_add_finalizer#

napi_status napi_add_finalizer(napi_env env,
                               napi_value js_object,
                               void* finalize_data,
                               node_api_nogc_finalize finalize_cb,
                               void* finalize_hint,
                               napi_ref* result); copy

• [in] env：调用 API 所处的环境。
• [in] js_object：将附加本机数据的 JavaScript 对象。
• [in] finalize_data：可选数据，将传递给 finalize_cb。
• [in] finalize_cb：本机回调，当 JavaScript 对象已被垃圾回收时，将用于释放本机数据。 napi_finalize 提供更多详细信息。
• [in] finalize_hint：可选的上下文提示，传递给 finalize 回调。
• [out] result：JavaScript 对象的可选引用。

如果 API 成功，则返回 napi_ok。

添加 napi_finalize 回调，当 js_object 中的 JavaScript 对象已被垃圾回收时，将调用该回调。

此 API 可在单个 JavaScript 对象上多次调用。

注意：仅在 finalize 回调调用时，才应通过 napi_delete_reference 删除可选的返回引用（如果已获取）。如果在此之前将其删除，则可能永远不会调用 finalize 回调。因此，在获取引用时，还需要 finalize 回调才能正确处置引用。

node_api_post_finalizer#

napi_status node_api_post_finalizer(node_api_nogc_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：可选的上下文提示，传递给 finalize 回调。

如果 API 成功，则返回 napi_ok。

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

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

node_api_post_finalizer 允许加载项将对这些 Node-API 的调用推迟到 GC 终结之外的时间点，从而帮助解决此限制。

简单的异步操作#

加载项模块通常需要利用 libuv 中的异步帮助器作为其实现的一部分。这允许它们安排异步执行的工作，以便其方法可以在工作完成之前返回。这允许它们避免阻塞 Node.js 应用程序的整体执行。

Node-API 为这些支持函数提供了一个 ABI 稳定的接口，涵盖最常见的异步用例。

Node-API 定义了 napi_async_work 结构，用于管理异步工作线程。使用 napi_create_async_work 和 napi_delete_async_work 创建/删除实例。

execute 和 complete 回调是当执行器准备好执行及其完成任务时分别调用的函数。

execute 函数应避免进行任何可能导致执行 JavaScript 或与 JavaScript 对象进行交互的 Node-API 调用。通常，任何需要进行 Node-API 调用的代码都应在 complete 回调中进行。避免在 execute 回调中使用 napi_env 参数，因为它可能会执行 JavaScript。

这些函数实现以下接口

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

调用这些方法时，传递的 data 参数将是传递给 napi_create_async_work 调用的附加提供的 void* 数据。

创建后，可以使用 napi_queue_async_work 函数将异步工作程序排队以执行。

napi_status napi_queue_async_work(node_api_nogc_env env,
                                  napi_async_work work); copy

如果需要在工作程序开始执行之前取消工作，可以使用 napi_cancel_async_work。

调用 napi_cancel_async_work 后，complete 回调将使用状态值 napi_cancelled 调用。即使已取消，也不应在调用 complete 回调之前删除工作。

napi_create_async_work#

napi_status napi_create_async_work(napi_env env,
                                   napi_value async_resource,
                                   napi_value async_resource_name,
                                   napi_async_execute_callback execute,
                                   napi_async_complete_callback complete,
                                   void* data,
                                   napi_async_work* result); copy

• [in] env：调用 API 所处的环境。
• [in] async_resource：与异步工作关联的可选对象，该对象将传递给可能的 async_hooks init 钩子。
• [in] async_resource_name：为 async_hooks API 暴露的诊断信息提供的资源类型的标识符。
• [in] execute：应调用以异步执行逻辑的本机函数。给定的函数是从工作程序池线程调用的，并且可以与主事件循环线程并行执行。
• [in] complete：异步逻辑完成或取消时将调用的本机函数。给定的函数是从主事件循环线程调用的。 napi_async_complete_callback 提供了更多详细信息。
• [in] data：用户提供的数据上下文。这将传回 execute 和 complete 函数。
• [out] result：napi_async_work*，它是对新创建的异步工作的句柄。

如果 API 成功，则返回 napi_ok。

此 API 分配一个工作对象，用于异步执行逻辑。一旦不再需要这项工作，就应该使用 napi_delete_async_work 释放它。

async_resource_name 应为以 null 结尾的 UTF-8 编码字符串。

async_resource_name 标识符由用户提供，应代表正在执行的异步工作的类型。还建议对标识符应用命名空间，例如通过包含模块名称。有关更多信息，请参阅 async_hooks 文档。

napi_delete_async_work#

napi_status napi_delete_async_work(napi_env env,
                                   napi_async_work work); copy

• [in] env：调用 API 所处的环境。
• [in] work：由 napi_create_async_work 调用返回的句柄。

如果 API 成功，则返回 napi_ok。

此 API 会释放先前分配的工作对象。

即使存在挂起的 JavaScript 异常，也可以调用此 API。

napi_queue_async_work#

napi_status napi_queue_async_work(node_api_nogc_env env,
                                  napi_async_work work); copy

• [in] env：调用 API 所处的环境。
• [in] work：由 napi_create_async_work 调用返回的句柄。

如果 API 成功，则返回 napi_ok。

此 API 请求将先前分配的工作安排为执行。一旦成功返回，此 API 不得再使用相同的 napi_async_work 项调用，否则结果将不确定。

napi_cancel_async_work#

napi_status napi_cancel_async_work(node_api_nogc_env env,
                                   napi_async_work work); copy

• [in] env：调用 API 所处的环境。
• [in] work：由 napi_create_async_work 调用返回的句柄。

如果 API 成功，则返回 napi_ok。

如果队列中的工作尚未开始，此 API 会取消该工作。如果工作已经开始执行，则无法取消，并且会返回 napi_generic_failure。如果成功，complete 回调将以 napi_cancelled 状态值调用。即使工作已成功取消，也不应在调用 complete 回调之前删除该工作。

即使存在挂起的 JavaScript 异常，也可以调用此 API。

自定义异步操作#

上述简单的异步工作 API 可能不适用于每种情况。在使用任何其他异步机制时，需要以下 API 来确保异步操作被运行时正确跟踪。

napi_async_init#

napi_status napi_async_init(napi_env env,
                            napi_value async_resource,
                            napi_value async_resource_name,
                            napi_async_context* result) copy

• [in] env：调用 API 所处的环境。
• [in] async_resource：与异步工作关联的对象，该对象将传递给可能的 async_hooks init 挂钩，并且可以通过 async_hooks.executionAsyncResource() 访问。
• [in] async_resource_name：为 async_hooks API 暴露的诊断信息提供的资源类型的标识符。
• [out] result：已初始化的异步上下文。

如果 API 成功，则返回 napi_ok。

async_resource 对象需要保持活动状态，直到 napi_async_destroy 使 async_hooks 相关的 API 正确运行。为了与旧版本保持 ABI 兼容性，napi_async_contexts 不会维护对 async_resource 对象的强引用，以避免引入导致内存泄漏的原因。但是，如果在 napi_async_context 被 napi_async_destroy 销毁之前，async_resource 被 JavaScript 引擎垃圾回收，则调用 napi_async_context 相关的 API（如 napi_open_callback_scope 和 napi_make_callback）可能会导致问题，例如使用 AsyncLocalStorage API 时丢失异步上下文。

为了与旧版本保持 ABI 兼容性，为 async_resource 传递 NULL 不会导致错误。但是，不建议这样做，因为这会导致 async_hooks init 钩子 和 async_hooks.executionAsyncResource() 出现不良行为，因为底层 async_hooks 实现现在需要该资源来提供异步回调之间的链接。

napi_async_destroy#

napi_status napi_async_destroy(napi_env env,
                               napi_async_context async_context); copy

• [in] env：调用 API 所处的环境。
• [in] async_context：要销毁的异步上下文。

如果 API 成功，则返回 napi_ok。

即使存在挂起的 JavaScript 异常，也可以调用此 API。

napi_make_callback#

NAPI_EXTERN napi_status napi_make_callback(napi_env env,
                                           napi_async_context async_context,
                                           napi_value recv,
                                           napi_value func,
                                           size_t argc,
                                           const napi_value* argv,
                                           napi_value* result); copy

• [in] env：调用 API 所处的环境。
• [in] async_context：调用回调的异步操作的上下文。这通常应该是先前从 napi_async_init 获取的值。为了与旧版本保持 ABI 兼容性，为 async_context 传递 NULL 不会导致错误。但是，会导致 async 钩子操作不正确。潜在问题包括在使用 AsyncLocalStorage API 时丢失异步上下文。
• [in] recv：传递给被调用函数的 this 值。
• [in] func：表示要调用的 JavaScript 函数的 napi_value。
• [in] argc：argv 数组中元素的数量。
• [in] argv：作为 napi_value 的 JavaScript 值数组，表示函数的参数。如果 argc 为零，可以通过传入 NULL 来省略此参数。
• [out] result：表示返回的 JavaScript 对象的 napi_value。

如果 API 成功，则返回 napi_ok。

此方法允许从本机加载项调用 JavaScript 函数对象。此 API 类似于 napi_call_function。但是，它用于在从异步操作返回后（当堆栈中没有其他脚本时）从本机代码调用 JavaScript。它是 node::MakeCallback 的一个相当简单的包装器。

请注意，在 napi_async_complete_callback 中使用 napi_make_callback 不是必需的；在那种情况下，回调的异步上下文已经设置，因此直接调用 napi_call_function 就足够且合适。在实现不使用 napi_create_async_work 的自定义异步行为时，可能需要使用 napi_make_callback 函数。

在回调期间 JavaScript 在微任务队列上调度的任何 process.nextTick 或 Promise 都将在返回到 C/C++ 之前运行。

napi_open_callback_scope#

NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
                                                 napi_value resource_object,
                                                 napi_async_context context,
                                                 napi_callback_scope* result) copy

• [in] env：调用 API 所处的环境。
• [in] resource_object：与异步工作关联的对象，该对象将传递给可能的 async_hooks init 钩子。此参数已弃用，并在运行时被忽略。改用 napi_async_init 中的 async_resource 参数。
• [in] context：调用回调的异步操作的上下文。这应该是一个先前从 napi_async_init 获得的值。
• [out] result：新创建的范围。

在某些情况下（例如，解析 Promise），需要在进行某些 Node-API 调用时具有与回调关联的范围的等效项。如果堆栈中没有其他脚本，则可以使用 napi_open_callback_scope 和 napi_close_callback_scope 函数打开/关闭所需的范围。

napi_close_callback_scope#

NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
                                                  napi_callback_scope scope) copy

• [in] env：调用 API 所处的环境。
• [in] scope：要关闭的范围。

即使存在挂起的 JavaScript 异常，也可以调用此 API。

版本管理#

napi_get_node_version#

typedef struct {
  uint32_t major;
  uint32_t minor;
  uint32_t patch;
  const char* release;
} napi_node_version;

napi_status napi_get_node_version(node_api_nogc_env env,
                                  const napi_node_version** version); copy

• [in] env：调用 API 所处的环境。
• [out] version：指向 Node.js 自身版本信息的指针。

如果 API 成功，则返回 napi_ok。

此函数用当前正在运行的 Node.js 的主版本、次版本和补丁版本填充 version 结构，并用 process.release.name 的值填充 release 字段。

返回的缓冲区是静态分配的，不需要释放。

napi_get_version#

napi_status napi_get_version(node_api_nogc_env env,
                             uint32_t* result); copy

• [in] env：调用 API 所处的环境。
• [out] result：支持的最高 Node-API 版本。

如果 API 成功，则返回 napi_ok。

此 API 返回 Node.js 运行时支持的最高 Node-API 版本。Node-API 计划为累加式，以便较新版本的 Node.js 可能会支持其他 API 函数。为了允许加载项在与支持它的 Node.js 版本一起运行时使用较新的函数，同时在与不支持它的 Node.js 版本一起运行时提供后备行为

• 调用 napi_get_version() 以确定 API 是否可用。
• 如果可用，请使用 uv_dlsym() 动态加载指向函数的指针。
• 使用动态加载的指针调用函数。
• 如果函数不可用，请提供不使用该函数的备用实现。

内存管理#

napi_adjust_external_memory#

NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_nogc_env env,
                                                    int64_t change_in_bytes,
                                                    int64_t* result); copy

• [in] env：调用 API 所处的环境。
• [in] change_in_bytes：由 JavaScript 对象保持活动状态的外部分配内存的变化。
• [out] result：调整后的值

如果 API 成功，则返回 napi_ok。

此函数向 V8 提供由 JavaScript 对象保持活动状态的外部分配内存量（即指向其自身由本机加载项分配的内存的 JavaScript 对象）的指示。注册外部分配的内存将比平时更频繁地触发全局垃圾回收。

Promise#

Node-API 提供了创建 Promise 对象的工具，如 ECMA 规范的 第 25.4 节 中所述。它将 promise 实现为一对对象。当通过 napi_create_promise() 创建 promise 时，会创建一个“延迟”对象并与 Promise 一起返回。延迟对象绑定到创建的 Promise，并且是使用 napi_resolve_deferred() 或 napi_reject_deferred() 解析或拒绝 Promise 的唯一方法。由 napi_create_promise() 创建的延迟对象由 napi_resolve_deferred() 或 napi_reject_deferred() 释放。Promise 对象可以返回给 JavaScript，在 JavaScript 中可以按常规方式使用它。

例如，要创建一个 promise 并将其传递给异步工作线程

napi_deferred deferred;
napi_value promise;
napi_status status;

// Create the promise.
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;

// Pass the deferred to a function that performs an asynchronous action.
do_something_asynchronous(deferred);

// Return the promise to JS
return promise; copy

上述函数 do_something_asynchronous() 将执行其异步操作，然后解析或拒绝延迟，从而结束 promise 并释放延迟

napi_deferred deferred;
napi_value undefined;
napi_status status;

// Create a value with which to conclude the deferred.
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;

// Resolve or reject the promise associated with the deferred depending on
// whether the asynchronous action succeeded.
if (asynchronous_action_succeeded) {
  status = napi_resolve_deferred(env, deferred, undefined);
} else {
  status = napi_reject_deferred(env, deferred, undefined);
}
if (status != napi_ok) return NULL;

// At this point the deferred has been freed, so we should assign NULL to it.
deferred = NULL; copy

napi_create_promise#

napi_status napi_create_promise(napi_env env,
                                napi_deferred* deferred,
                                napi_value* promise); copy

• [in] env：调用 API 所处的环境。
• [out] deferred：一个新创建的延迟对象，稍后可以将其传递给 napi_resolve_deferred() 或 napi_reject_deferred() 以分别解析或拒绝关联的 promise。
• [out] promise：与延迟对象关联的 JavaScript promise。

如果 API 成功，则返回 napi_ok。

此 API 创建一个延迟对象和一个 JavaScript 承诺。

napi_resolve_deferred#

napi_status napi_resolve_deferred(napi_env env,
                                  napi_deferred deferred,
                                  napi_value resolution); copy

• [in] env：调用 API 所处的环境。
• [in] deferred：要解决其关联承诺的延迟对象。
• [in] resolution：用于解决承诺的值。

此 API 通过与其关联的延迟对象来解决 JavaScript 承诺。因此，它只能用于解决具有相应延迟对象的 JavaScript 承诺。这实际上意味着必须使用 napi_create_promise() 创建承诺，并且必须保留从该调用返回的延迟对象才能传递给此 API。

成功完成后将释放延迟对象。

napi_reject_deferred#

napi_status napi_reject_deferred(napi_env env,
                                 napi_deferred deferred,
                                 napi_value rejection); copy

• [in] env：调用 API 所处的环境。
• [in] deferred：要解决其关联承诺的延迟对象。
• [in] rejection：用于拒绝承诺的值。

此 API 通过与其关联的延迟对象来拒绝 JavaScript 承诺。因此，它只能用于拒绝具有相应延迟对象的 JavaScript 承诺。这实际上意味着必须使用 napi_create_promise() 创建承诺，并且必须保留从该调用返回的延迟对象才能传递给此 API。

成功完成后将释放延迟对象。

napi_is_promise#

napi_status napi_is_promise(napi_env env,
                            napi_value value,
                            bool* is_promise); copy

• [in] env：调用 API 所处的环境。
• [in] value：要检查的值
• [out] is_promise：指示 promise 是否是本机承诺对象（即，由底层引擎创建的承诺对象）的标志。

脚本执行#

Node-API 提供了一个 API，用于使用底层 JavaScript 引擎执行包含 JavaScript 的字符串。

napi_run_script#

NAPI_EXTERN napi_status napi_run_script(napi_env env,
                                        napi_value script,
                                        napi_value* result); copy

• [in] env：调用 API 所处的环境。
• [in] script：包含要执行的脚本的 JavaScript 字符串。
• [out] result：执行脚本产生的值。

此函数执行一段 JavaScript 代码并返回其结果，但有以下警告

• 与 eval 不同，此函数不允许脚本访问当前词法作用域，因此也不允许访问 模块作用域，这意味着伪全局变量（如 require）将不可用。
• 脚本可以访问全局作用域。脚本中的函数和 var 声明将添加到 global 对象中。使用 let 和 const 进行的变量声明将全局可见，但不会添加到 global 对象中。
• 脚本中的 this 的值为 global。

libuv 事件循环#

Node-API 提供了一个函数，用于获取与特定 napi_env 关联的当前事件循环。

napi_get_uv_event_loop#

NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_nogc_env env,
                                               struct uv_loop_s** loop); copy

• [in] env：调用 API 所处的环境。
• [out] loop：当前 libuv 循环实例。

异步线程安全函数调用#

JavaScript 函数通常只能从本机加载项的主线程调用。如果加载项创建其他线程，则需要 napi_env、napi_value 或 napi_ref 的 Node-API 函数不能从这些线程调用。

当加载项具有其他线程并且需要根据这些线程完成的处理调用 JavaScript 函数时，这些线程必须与加载项的主线程通信，以便主线程可以代表它们调用 JavaScript 函数。线程安全函数 API 提供了一种简单的方法来实现此目的。

这些 API 提供了类型 napi_threadsafe_function，以及用于创建、销毁和调用此类型的对象。napi_create_threadsafe_function() 会创建对 napi_value 的持久引用，该引用包含一个可以从多个线程调用的 JavaScript 函数。调用是异步进行的。这意味着将 JavaScript 回调调用的值将被放入队列中，并且对于队列中的每个值，最终都会调用 JavaScript 函数。

在创建 napi_threadsafe_function 时，可以提供 napi_finalize 回调。当线程安全函数即将被销毁时，将在主线程上调用此回调。它接收构造期间给出的上下文和最终化数据，并提供了一个机会来清理线程，例如通过调用 uv_thread_join()。除了主循环线程之外，在最终化回调完成之后，任何线程都不应使用线程安全函数。

在调用 napi_create_threadsafe_function() 时给出的 context 可以使用对 napi_get_threadsafe_function_context() 的调用从任何线程中检索。

调用线程安全函数#

napi_call_threadsafe_function() 可用于启动对 JavaScript 的调用。napi_call_threadsafe_function() 接受一个参数，该参数控制 API 的行为是否阻塞。如果设置为 napi_tsfn_nonblocking，则 API 以非阻塞方式运行，如果队列已满，则返回 napi_queue_full，从而阻止数据成功添加到队列中。如果设置为 napi_tsfn_blocking，则 API 将阻塞，直到队列中有可用空间。如果线程安全函数创建的最大队列大小为 0，则 napi_call_threadsafe_function() 永远不会阻塞。

napi_call_threadsafe_function() 不应在 JavaScript 线程中使用 napi_tsfn_blocking 调用，因为如果队列已满，可能会导致 JavaScript 线程死锁。

对 JavaScript 的实际调用由通过 call_js_cb 参数给出的回调控制。对于通过对 napi_call_threadsafe_function() 的成功调用放入队列的每个值，call_js_cb 在主线程上调用一次。如果未给出此类回调，将使用默认回调，并且生成的 JavaScript 调用将没有参数。call_js_cb 回调在其参数中接收要调用的 JavaScript 函数（作为 napi_value），以及创建 napi_threadsafe_function 时使用的 void* 上下文指针，以及由其中一个辅助线程创建的下一个数据指针。然后，回调可以使用 napi_call_function() 等 API 调用 JavaScript。

当 env 和 call_js_cb 都设置为 NULL 时，也可以调用回调，以指示不再可以调用 JavaScript，而队列中可能仍有需要释放的项目。这通常发生在 Node.js 进程退出时，而线程安全函数仍处于活动状态时。

无需通过 napi_make_callback() 调用 JavaScript，因为 Node-API 在适合回调的上下文中运行 call_js_cb。

在事件循环的每次滴答中，可能会调用零个或多个排队项。应用程序不应依赖于特定行为，而应依赖于调用回调的进度，并且随着时间的推移，事件将被调用。

线程安全函数的引用计数#

在 napi_threadsafe_function 对象存在期间，可以向其添加或从中移除线程。因此，除了在创建时指定一个初始线程数之外，还可以调用 napi_acquire_threadsafe_function 来指示一个新线程将开始使用线程安全函数。同样，可以调用 napi_release_threadsafe_function 来指示一个现有线程将停止使用线程安全函数。

当使用该对象的每个线程都已调用 napi_release_threadsafe_function() 或在响应 napi_call_threadsafe_function 调用时收到 napi_closing 返回状态时，将销毁 napi_threadsafe_function 对象。在销毁 napi_threadsafe_function 之前，将清空队列。napi_release_threadsafe_function() 应该是与给定的 napi_threadsafe_function 结合使用的最后一个 API 调用，因为在调用完成后，无法保证 napi_threadsafe_function 仍然已分配。出于相同原因，在响应 napi_call_threadsafe_function 调用时收到 napi_closing 返回值后，请勿使用线程安全函数。与 napi_threadsafe_function 关联的数据可以在传递给 napi_create_threadsafe_function() 的 napi_finalize 回调中释放。napi_create_threadsafe_function 的 initial_thread_count 参数标记线程安全函数的初始获取次数，而不是在创建时多次调用 napi_acquire_threadsafe_function。

一旦使用 napi_threadsafe_function 的线程数达到零，则没有其他线程可以通过调用 napi_acquire_threadsafe_function() 开始使用它。事实上，除了 napi_release_threadsafe_function() 之外，与之关联的所有后续 API 调用都将返回 napi_closing 错误值。

可以通过向 napi_release_threadsafe_function() 提供 napi_tsfn_abort 值来“中止”线程安全函数。这将导致与线程安全函数关联的所有后续 API（除了 napi_release_threadsafe_function()）在引用计数达到零之前返回 napi_closing。特别是，napi_call_threadsafe_function() 将返回 napi_closing，从而通知线程无法再对线程安全函数进行异步调用。这可以用作终止线程的标准。在从 napi_call_threadsafe_function() 接收 napi_closing 返回值后，线程不得再使用线程安全函数，因为它不再保证已分配。

决定是否保持进程运行#

类似于 libuv 句柄，线程安全函数可以“引用”和“取消引用”。“引用的”线程安全函数将导致创建它的线程上的事件循环保持活动状态，直到线程安全函数被销毁。相反，“取消引用的”线程安全函数不会阻止事件循环退出。API napi_ref_threadsafe_function 和 napi_unref_threadsafe_function 存在于此目的。

napi_unref_threadsafe_function 既不将线程安全函数标记为可销毁，也不阻止 napi_ref_threadsafe_function 销毁它。

napi_create_threadsafe_function#

NAPI_EXTERN napi_status
napi_create_threadsafe_function(napi_env env,
                                napi_value func,
                                napi_value async_resource,
                                napi_value async_resource_name,
                                size_t max_queue_size,
                                size_t initial_thread_count,
                                void* thread_finalize_data,
                                napi_finalize thread_finalize_cb,
                                void* context,
                                napi_threadsafe_function_call_js call_js_cb,
                                napi_threadsafe_function* result); copy

• [in] env：调用 API 所处的环境。
• [in] func：一个可选的 JavaScript 函数，用于从另一个线程调用。如果将 NULL 传递给 call_js_cb，则必须提供它。
• [in] async_resource：与异步工作关联的可选对象，该对象将传递给可能的 async_hooks init 钩子。
• [in] async_resource_name：一个 JavaScript 字符串，用于提供对 async_hooks API 公开的诊断信息的资源类型的标识符。
• [in] max_queue_size：队列的最大大小。0 表示没有限制。
• [in] initial_thread_count：初始获取数，即初始线程数，包括主线程，它将使用此函数。
• [in] thread_finalize_data：要传递给 thread_finalize_cb 的可选数据。
• [in] thread_finalize_cb：当 napi_threadsafe_function 被销毁时调用的可选函数。
• [in] context：要附加到结果 napi_threadsafe_function 的可选数据。
• [in] call_js_cb：可选回调，它在不同线程上的调用响应中调用 JavaScript 函数。此回调将在主线程上调用。如果没有给出，则 JavaScript 函数将不带任何参数调用，并且将 undefined 作为其 this 值。 napi_threadsafe_function_call_js 提供了更多详细信息。
• [out] result：异步线程安全 JavaScript 函数。

更改历史

• 实验性（定义了 NAPI_EXPERIMENTAL）

  call_js_cb 中引发的未捕获异常将使用 'uncaughtException' 事件处理，而不是被忽略。

napi_get_threadsafe_function_context#

NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
                                     void** result); copy

• [in] func：要检索其上下文的线程安全函数。
• [out] result：存储上下文的位置。

可以使用 func 的任何线程调用此 API。

napi_call_threadsafe_function#

NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
                              void* data,
                              napi_threadsafe_function_call_mode is_blocking); copy

• [in] func：要调用的异步线程安全 JavaScript 函数。
• [in] data：在创建线程安全 JavaScript 函数期间通过回调 call_js_cb 发送到 JavaScript 的数据。
• [in] is_blocking：其值可以是 napi_tsfn_blocking（表示如果队列已满，调用应阻塞）或 napi_tsfn_nonblocking（表示无论何时队列已满，调用都应立即返回 napi_queue_full 状态）。

不应使用 napi_tsfn_blocking 从 JavaScript 线程调用此 API，因为如果队列已满，可能会导致 JavaScript 线程死锁。

如果从任何线程使用 abort 设置为 napi_tsfn_abort 调用 napi_release_threadsafe_function()，此 API 将返回 napi_closing。仅当 API 返回 napi_ok 时，该值才会添加到队列中。

可以使用 func 的任何线程调用此 API。

napi_acquire_threadsafe_function#

NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func); copy

• [in] func：要开始使用的异步线程安全 JavaScript 函数。

线程在将 func 传递给任何其他线程安全函数 API 之前应调用此 API，以表明它将使用 func。这可防止在所有其他线程停止使用 func 时销毁 func。

此 API 可从任何将开始使用 func 的线程调用。

napi_release_threadsafe_function#

NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
                                 napi_threadsafe_function_release_mode mode); copy

• [in] func：要递减其引用计数的异步线程安全 JavaScript 函数。
• [in] mode：标志，其值可以是 napi_tsfn_release（表示当前线程将不再调用线程安全函数），也可以是 napi_tsfn_abort（表示除当前线程外，没有其他线程应再调用线程安全函数）。如果设置为 napi_tsfn_abort，则对 napi_call_threadsafe_function() 的进一步调用将返回 napi_closing，并且不会再将任何值放入队列中。

当线程停止使用 func 时，应调用此 API。在调用此 API 后将 func 传递给任何线程安全 API 会产生未定义的结果，因为 func 可能已被销毁。

此 API 可从任何将停止使用 func 的线程调用。

napi_ref_threadsafe_function#

NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_nogc_env env, napi_threadsafe_function func); copy

• [in] env：调用 API 所处的环境。
• [in] func：要引用的线程安全函数。

此 API 用于指示在主线程上运行的事件循环不应退出，直到 func 被销毁。类似于 uv_ref，它也是幂等的。

napi_unref_threadsafe_function 既不会将线程安全函数标记为可以销毁，也不会阻止 napi_ref_threadsafe_function 将其销毁。napi_acquire_threadsafe_function 和 napi_release_threadsafe_function 可用于此目的。

此 API 只能从主线程调用。

napi_unref_threadsafe_function#

NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_nogc_env env, napi_threadsafe_function func); copy

• [in] env：调用 API 所处的环境。
• [in] func：要取消引用的线程安全函数。

此 API 用于指示在主线程上运行的事件循环可以在 func 被销毁之前退出。类似于 uv_unref，它也是幂等的。

此 API 只能从主线程调用。

杂项实用程序#

node_api_get_module_file_name#

NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_nogc_env env, const char** result);
 copy

• [in] env：调用 API 所处的环境。
• [out] result：包含加载加载项的绝对路径的 URL。对于本地文件系统上的文件，它将以 file:// 开头。该字符串以 null 结尾，归 env 所有，因此不得修改或释放。

如果加载项加载过程在加载期间无法确定加载项的文件名，则 result 可能为空字符串。