Node.js v22.11.0 文档

ABI 稳定性的影响#

¥Implications of ABI stability

尽管 Node-API 提供了 ABI 稳定性保证，但 Node.js 的其他部分却没有，插件中使用的任何外部库也可能没有。特别是，以下 API 均未提供跨主要版本的 ABI 稳定性保证：

¥Although Node-API provides an ABI stability guarantee, other parts of Node.js do not, and any external libraries used from the addon may not. In particular, none of the following APIs provide an ABI stability guarantee across major versions:

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

  ¥the Node.js C++ APIs available via any of

  #include <node.h>
  #include <node_buffer.h>
  #include <node_version.h>
  #include <node_object_wrap.h> 拷贝

• libuv API，它也包含在 Node.js 中，可通过

  ¥the libuv APIs which are also included with Node.js and available via

  #include <uv.h> 拷贝

• V8 API 可通过

  ¥the V8 API available via

  #include <v8.h> 拷贝

因此，为了使插件在 Node.js 主要版本之间保持 ABI 兼容，它必须通过限制自己使用来独占使用 Node-API

¥Thus, for an addon to remain ABI-compatible across Node.js major versions, it must use Node-API exclusively by restricting itself to using

#include <node_api.h> 拷贝

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

¥and by checking, for all external libraries that it uses, that the external library makes ABI stability guarantees similar to Node-API.

构建#

¥Building

与用 JavaScript 编写的模块不同，使用 Node-API 开发和部署 Node.js 原生插件需要一组额外的工具。除了为 Node.js 开发所需的基本工具外，原生插件开发者还需要一个可以将 C 和 C++ 代码编译为二进制文件的工具链。此外，根据原生插件的部署方式，原生插件的用户还需要安装 C/C++ 工具链。

¥Unlike modules written in JavaScript, developing and deploying Node.js native addons using Node-API requires an additional set of tools. Besides the basic tools required to develop for Node.js, the native addon developer requires a toolchain that can compile C and C++ code into a binary. In addition, depending upon how the native addon is deployed, the user of the native addon will also need to have a C/C++ toolchain installed.

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

¥For Linux developers, the necessary C/C++ toolchain packages are readily available. GCC is widely used in the Node.js community to build and test across a variety of platforms. For many developers, the LLVM compiler infrastructure is also a good choice.

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

¥For Mac developers, Xcode offers all the required compiler tools. However, it is not necessary to install the entire Xcode IDE. The following command installs the necessary toolchain:

xcode-select --install 拷贝

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

¥For Windows developers, Visual Studio offers all the required compiler tools. However, it is not necessary to install the entire Visual Studio IDE. The following command installs the necessary toolchain:

npm install --global windows-build-tools 拷贝

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

¥The sections below describe the additional tools available for developing and deploying Node.js native addons.

构建工具#

¥Build tools

此处列出的两种工具都要求原生插件的用户安装 C/C++ 工具链才能成功安装原生插件。

¥Both the tools listed here require that users of the native addon have a C/C++ toolchain installed in order to successfully install the native addon.

node-gyp#

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

¥node-gyp is a build system based on the gyp-next fork of Google's GYP tool and comes bundled with npm. GYP, and therefore node-gyp, requires that Python be installed.

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

¥Historically, node-gyp has been the tool of choice for building native addons. It has widespread adoption and documentation. However, some developers have run into limitations in node-gyp.

CMake.js#

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

¥CMake.js is an alternative build system based on CMake.

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

¥CMake.js is a good choice for projects that already use CMake or for developers affected by limitations in node-gyp. build_with_cmake is an example of a CMake-based native addon project.

上传预编译的二进制文件#

¥Uploading precompiled binaries

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

¥The three tools listed here permit native addon developers and maintainers to create and upload binaries to public or private servers. These tools are typically integrated with CI/CD build systems like Travis CI and AppVeyor to build and upload binaries for a variety of platforms and architectures. These binaries are then available for download by users who do not need to have a C/C++ toolchain installed.

node-pre-gyp#

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

¥node-pre-gyp is a tool based on node-gyp that adds the ability to upload binaries to a server of the developer's choice. node-pre-gyp has particularly good support for uploading binaries to Amazon S3.

prebuild#

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

¥prebuild is a tool that supports builds using either node-gyp or CMake.js. Unlike node-pre-gyp which supports a variety of servers, prebuild uploads binaries only to GitHub releases. prebuild is a good choice for GitHub projects using CMake.js.

prebuildify#

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

¥prebuildify is a tool based on node-gyp. The advantage of prebuildify is that the built binaries are bundled with the native addon when it's uploaded to npm. The binaries are downloaded from npm and are immediately available to the module user when the native addon is installed.

使用方法#

¥Usage

为了使用 Node-API 函数，在节点开发树中包含位于 src 目录中的文件 node_api.h：

¥In order to use the Node-API functions, include the file node_api.h which is located in the src directory in the node development tree:

#include <node_api.h> 拷贝

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

¥This will opt into the default NAPI_VERSION for the given release of Node.js. In order to ensure compatibility with specific versions of Node-API, the version can be specified explicitly when including the header:

#define NAPI_VERSION 3
#include <node_api.h> 拷贝

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

¥This restricts the Node-API surface to just the functionality that was available in the specified (and earlier) versions.

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

¥Some of the Node-API surface is experimental and requires explicit opt-in:

#define NAPI_EXPERIMENTAL
#include <node_api.h> 拷贝

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

¥In this case the entire API surface, including any experimental APIs, will be available to the module code.

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

¥Occasionally, experimental features are introduced that affect already-released and stable APIs. These features can be disabled by an opt-out:

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

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

¥where <FEATURE_NAME> is the name of an experimental feature that affects both experimental and stable APIs.

Node-API 版本矩阵#

¥Node-API version matrix

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

¥Up until version 9, Node-API versions were additive and versioned independently from Node.js. This meant that any version was an extension to the previous version in that it had all of the APIs from the previous version with some additions. Each Node.js version only supported a single Node-API version. For example v18.15.0 supports only Node-API version 8. ABI stability was achieved because 8 was a strict superset of all previous versions.

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

¥As of version 9, while Node-API versions continue to be versioned independently an add-on that ran with Node-API version 9 may need code updates to run with Node-API version 10. ABI stability is maintained, however, because Node.js versions that support Node-API versions higher than 8 will support all versions between 8 and the highest version they support and will default to providing the version 8 APIs unless an add-on opts into a higher Node-API version. This approach provides the flexibility of better optimizing existing Node-API functions while maintaining ABI stability. Existing add-ons can continue to run without recompilation using an earlier version of Node-API. If an add-on needs functionality from a newer Node-API version, changes to existing code and recompilation will be needed to use those new functions anyway.

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

¥In versions of Node.js that support Node-API version 9 and later, defining NAPI_VERSION=X and using the existing add-on initialization macros will bake in the requested Node-API version that will be used at runtime into the add-on. If NAPI_VERSION is not set it will default to 8.

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

¥This table may not be up to date in older streams, the most up to date information is in the latest API documentation in: Node-API version matrix

• Node-API 是实验性的。

¥* Node-API was experimental.

** Node.js 8.0.0 包含 Node-API 作为实验性的。它作为 Node-API 版本 1 发布，但继续改进直到 Node.js 8.6.0。API 在 Node.js 8.6.0 之前的版本中有所不同。我们推荐 Node-API 版本 3 或更高版本。

¥** Node.js 8.0.0 included Node-API as experimental. It was released as Node-API version 1 but continued to evolve until Node.js 8.6.0. The API is different in versions prior to Node.js 8.6.0. We recommend Node-API version 3 or later.

为 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:，则只有在包含 node_api.h 或 js_native_api.h 之前包含 #define NAPI_EXPERIMENTAL 时，API 才可用。如果某个 API 在晚于 added in: 中所示版本的 Node.js 版本上似乎不可用，那么这很可能是明显缺失的原因。

¥Each API documented for Node-API will have a header named added in:, and APIs which are stable will have the additional header Node-API version:. APIs are directly usable when using a Node.js version which supports the Node-API version shown in Node-API version: or higher. When using a Node.js version that does not support the Node-API version: listed or if there is no Node-API version: listed, then the API will only be available if #define NAPI_EXPERIMENTAL precedes the inclusion of node_api.h or js_native_api.h. If an API appears not to be available on a version of Node.js which is later than the one shown in added in: then this is most likely the reason for the apparent absence.

与从原生代码访问 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 可能不适用。

¥The Node-APIs associated strictly with accessing ECMAScript features from native code can be found separately in js_native_api.h and js_native_api_types.h. The APIs defined in these headers are included in node_api.h and node_api_types.h. The headers are structured in this way in order to allow implementations of Node-API outside of Node.js. For those implementations the Node.js specific APIs may not be applicable.

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

¥The Node.js-specific parts of an addon can be separated from the code that exposes the actual functionality to the JavaScript environment so that the latter may be used with multiple implementations of Node-API. In the example below, addon.c and addon.h refer only to js_native_api.h. This ensures that addon.c can be reused to compile against either the Node.js implementation of Node-API or any implementation of Node-API outside of Node.js.

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

¥addon_node.c is a separate file that contains the Node.js specific entry point to the addon and which instantiates the addon by calling into addon.c when the addon is loaded into a Node.js environment.

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

// 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;
} 拷贝

// 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);
} 拷贝

环境生命周期 API#

¥Environment life cycle APIs

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

¥Section 8.7 of the ECMAScript Language Specification defines the concept of an "Agent" as a self-contained environment in which JavaScript code runs. Multiple such Agents may be started and terminated either concurrently or in sequence by the process.

一个 Node.js 环境对应一个 ECMAScript Agent。在主进程中，启动时创建一个环境，可以在单独的线程上创建额外的环境作为 工作线程。当 Node.js 嵌入到另一个应用中时，应用的主线程也可能在应用的生命周期中多次构造和销毁 Node.js 环境，使得应用创建的每个 Node.js 环境可能，在 反过来，在其生命周期中创建和销毁额外的环境作为工作线程。

¥A Node.js environment corresponds to an ECMAScript Agent. In the main process, an environment is created at startup, and additional environments can be created on separate threads to serve as worker threads. When Node.js is embedded in another application, the main thread of the application may also construct and destroy a Node.js environment multiple times during the life cycle of the application process such that each Node.js environment created by the application may, in turn, during its life cycle create and destroy additional environments as worker threads.

从原生插件的角度来看，这意味着它提供的绑定可以从多个上下文中多次调用，甚至可以同时从多个线程中调用。

¥From the perspective of a native addon this means that the bindings it provides may be called multiple times, from multiple contexts, and even concurrently from multiple threads.

原生插件可能需要分配它们在 Node.js 环境的生命周期中使用的全局状态，以便该状态对于插件的每个实例都是唯一的。

¥Native addons may need to allocate global state which they use during their life cycle of an Node.js environment such that the state can be unique to each instance of the addon.

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

¥To this end, Node-API provides a way to associate data such that its life cycle is tied to the life cycle of a Node.js environment.

napi_set_instance_data#

napi_status napi_set_instance_data(node_api_basic_env env,
                                   void* data,
                                   napi_finalize finalize_cb,
                                   void* finalize_hint); 拷贝

• [in] env：调用 Node-API 调用的环境。

  ¥[in] env: The environment that the Node-API call is invoked under.

• [in] data：可用于此实例的绑定的数据项。

  ¥[in] data: The data item to make available to bindings of this instance.

• [in] finalize_cb：拆除环境时调用的函数。该函数接收 data 以便释放它。napi_finalize 提供了更多详细信息。

  ¥[in] finalize_cb: The function to call when the environment is being torn down. The function receives data so that it might free it. napi_finalize provides more details.

• [in] finalize_hint：在收集期间传递给最终回调的可选提示。

  ¥[in] finalize_hint: Optional hint to pass to the finalize callback during collection.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API associates data with the currently running Node.js environment. data can later be retrieved using napi_get_instance_data(). Any existing data associated with the currently running Node.js environment which was set by means of a previous call to napi_set_instance_data() will be overwritten. If a finalize_cb was provided by the previous call, it will not be called.

napi_get_instance_data#

napi_status napi_get_instance_data(node_api_basic_env env,
                                   void** data); 拷贝

• [in] env：调用 Node-API 调用的环境。

  ¥[in] env: The environment that the Node-API call is invoked under.

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

  ¥[out] data: The data item that was previously associated with the currently running Node.js environment by a call to napi_set_instance_data().

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API retrieves data that was previously associated with the currently running Node.js environment via napi_set_instance_data(). If no data is set, the call will succeed and data will be set to NULL.

基本的 Node-API 数据类型#

¥Basic Node-API data types

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

¥Node-API exposes the following fundamental data types as abstractions that are consumed by the various APIs. These APIs should be treated as opaque, introspectable only with other Node-API calls.

napi_status#

指示 Node-API 调用成功或失败的完整状态代码。目前支持以下状态码。

¥Integral status code indicating the success or failure of a Node-API call. Currently, the following status codes are supported.

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; 拷贝

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

¥If additional information is required upon an API returning a failed status, it can be obtained by calling 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; 拷贝

• error_message：UTF8 编码的字符串，包含错误的 VM 中立描述。

  ¥error_message: UTF8-encoded string containing a VM-neutral description of the error.

• engine_reserved：为特定于 VM 的错误详细信息保留。目前尚未为任何 VM 实现此功能。

  ¥engine_reserved: Reserved for VM-specific error details. This is currently not implemented for any VM.

• engine_error_code：特定于 VM 的错误代码。目前尚未为任何 VM 实现此功能。

  ¥engine_error_code: VM-specific error code. This is currently not implemented for any VM.

• error_code：源自最后一个错误的 Node-API 状态代码。

  ¥error_code: The Node-API status code that originated with the last error.

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

¥See the Error handling section for additional information.

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 的回调传递。

¥napi_env is used to represent a context that the underlying Node-API implementation can use to persist VM-specific state. This structure is passed to native functions when they're invoked, and it must be passed back when making Node-API calls. Specifically, the same napi_env that was passed in when the initial native function was called must be passed to any subsequent nested Node-API calls. Caching the napi_env for the purpose of general reuse, and passing the napi_env between instances of the same addon running on different Worker threads is not allowed. The napi_env becomes invalid when an instance of a native addon is unloaded. Notification of this event is delivered through the callbacks given to napi_add_env_cleanup_hook and napi_set_instance_data.

node_api_basic_env#

napi_env 的这个变体被传递给同步终结器 (node_api_basic_finalize)。Node-API 的一个子集接受 node_api_basic_env 类型的参数作为其第一个参数。这些 API 不访问 JavaScript 引擎的状态，因此可以安全地从同步终结器调用。允许将 napi_env 类型的参数传递给这些 API，但是不允许将 node_api_basic_env 类型的参数传递给访问 JavaScript 引擎状态的 API。当使用标志编译附加组件时，尝试在不进行强制转换的情况下执行此操作将产生编译器警告或错误，这会导致它们在将不正确的指针类型传递到函数时触发警告和/或错误。从同步终结器调用此类 API 最终将导致应用终止。

¥This variant of napi_env is passed to synchronous finalizers (node_api_basic_finalize). There is a subset of Node-APIs which accept a parameter of type node_api_basic_env as their first argument. These APIs do not access the state of the JavaScript engine and are thus safe to call from synchronous finalizers. Passing a parameter of type napi_env to these APIs is allowed, however, passing a parameter of type node_api_basic_env to APIs that access the JavaScript engine state is not allowed. Attempting to do so without a cast will produce a compiler warning or an error when add-ons are compiled with flags which cause them to emit warnings and/or errors when incorrect pointer types are passed into a function. Calling such APIs from a synchronous finalizer will ultimately result in the termination of the application.

napi_value#

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

¥This is an opaque pointer that is used to represent a JavaScript value.

napi_threadsafe_function#

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

¥This is an opaque pointer that represents a JavaScript function which can be called asynchronously from multiple threads via 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() 进行后续使用。

¥A value to be given to napi_release_threadsafe_function() to indicate whether the thread-safe function is to be closed immediately (napi_tsfn_abort) or merely released (napi_tsfn_release) and thus available for subsequent use via napi_acquire_threadsafe_function() and napi_call_threadsafe_function().

typedef enum {
  napi_tsfn_release,
  napi_tsfn_abort
} napi_threadsafe_function_release_mode; 拷贝

napi_threadsafe_function_call_mode#

赋予 napi_call_threadsafe_function() 的值，以指示只要与线程安全函数关联的队列已满，调用是否应阻塞。

¥A value to be given to napi_call_threadsafe_function() to indicate whether the call should block whenever the queue associated with the thread-safe function is full.

typedef enum {
  napi_tsfn_nonblocking,
  napi_tsfn_blocking
} napi_threadsafe_function_call_mode; 拷贝

Node-API 内存管理类型#

¥Node-API memory management types

napi_handle_scope#

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

¥This is an abstraction used to control and modify the lifetime of objects created within a particular scope. In general, Node-API values are created within the context of a handle scope. When a native method is called from JavaScript, a default handle scope will exist. If the user does not explicitly create a new handle scope, Node-API values will be created in the default handle scope. For any invocations of code outside the execution of a native method (for instance, during a libuv callback invocation), the module is required to create a scope before invoking any functions that can result in the creation of JavaScript values.

句柄作用域使用 napi_open_handle_scope 创建，使用 napi_close_handle_scope 销毁。关闭作用域可以向 GC 表明在句柄作用域的生命周期内创建的所有 napi_value 不再从当前堆栈帧中引用。

¥Handle scopes are created using napi_open_handle_scope and are destroyed using napi_close_handle_scope. Closing the scope can indicate to the GC that all napi_values created during the lifetime of the handle scope are no longer referenced from the current stack frame.

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

¥For more details, review the Object lifetime management.

napi_escapable_handle_scope#

可转义句柄范围是一种特殊类型的句柄范围，用于将在特定句柄范围内创建的值返回到父范围。

¥Escapable handle scopes are a special type of handle scope to return values created within a particular handle scope to a parent scope.

napi_ref#

这是用于引用 napi_value 的抽象。这允许用户管理 JavaScript 值的生命周期，包括明确定义它们的最小生命周期。

¥This is the abstraction to use to reference a napi_value. This allows for users to manage the lifetimes of JavaScript values, including defining their minimum lifetimes explicitly.

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

¥For more details, review the Object lifetime management.

napi_type_tag#

存储为两个无符号 64 位整数的 128 位值。它作为一个 UUID，JavaScript 对象或 外部的 可以是 "tagged"，以确保它们属于某种类型。这是比 napi_instanceof 更强的检查，因为如果对象的原型被操纵，后者会报告误报。类型标记与 napi_wrap 一起使用时最有用，因为它确保从封装对象中检索的指针可以安全地转换为与先前应用于 JavaScript 对象的类型标记相对应的原生类型。

¥A 128-bit value stored as two unsigned 64-bit integers. It serves as a UUID with which JavaScript objects or externals can be "tagged" in order to ensure that they are of a certain type. This is a stronger check than napi_instanceof, because the latter can report a false positive if the object's prototype has been manipulated. Type-tagging is most useful in conjunction with napi_wrap because it ensures that the pointer retrieved from a wrapped object can be safely cast to the native type corresponding to the type tag that had been previously applied to the JavaScript object.

typedef struct {
  uint64_t lower;
  uint64_t upper;
} napi_type_tag; 拷贝

napi_async_cleanup_hook_handle#

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

¥An opaque value returned by napi_add_async_cleanup_hook. It must be passed to napi_remove_async_cleanup_hook when the chain of asynchronous cleanup events completes.

Node-API 回调类型#

¥Node-API callback types

napi_callback_info#

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

¥Opaque datatype that is passed to a callback function. It can be used for getting additional information about the context in which the callback was invoked.

napi_callback#

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

¥Function pointer type for user-provided native functions which are to be exposed to JavaScript via Node-API. Callback functions should satisfy the following signature:

typedef napi_value (*napi_callback)(napi_env, napi_callback_info); 拷贝

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

¥Unless for reasons discussed in Object Lifetime Management, creating a handle and/or callback scope inside a napi_callback is not necessary.

node_api_basic_finalize#

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

¥Function pointer type for add-on provided functions that allow the user to be notified when externally-owned data is ready to be cleaned up because the object it was associated with has been garbage-collected. The user must provide a function satisfying the following signature which would get called upon the object's collection. Currently, node_api_basic_finalize can be used for finding out when objects that have external data are collected.

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

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

¥Unless for reasons discussed in Object Lifetime Management, creating a handle and/or callback scope inside the function body is not necessary.

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

¥Since these functions may be called while the JavaScript engine is in a state where it cannot execute JavaScript code, only Node-APIs which accept a node_api_basic_env as their first parameter may be called. node_api_post_finalizer can be used to schedule Node-API calls that require access to the JavaScript engine's state to run after the current garbage collection cycle has completed.

对于 node_api_create_external_string_latin1 和 node_api_create_external_string_utf16，env 参数可以为空，因为在环境关闭的后期可以收集外部字符串。

¥In the case of node_api_create_external_string_latin1 and node_api_create_external_string_utf16 the env parameter may be null, because external strings can be collected during the latter part of environment shutdown.

变更历史：

¥Change History:

• 实验（NAPI_EXPERIMENTAL）：

  ¥experimental (NAPI_EXPERIMENTAL):

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

  ¥Only Node-API calls that accept a node_api_basic_env as their first parameter may be called, otherwise the application will be terminated with an appropriate error message. This feature can be turned off by defining NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.

napi_finalize#

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

¥Function pointer type for add-on provided function that allow the user to schedule a group of calls to Node-APIs in response to a garbage collection event, after the garbage collection cycle has completed. These function pointers can be used with node_api_post_finalizer.

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

变更历史：

¥Change History:

• 实验性的（定义了 NAPI_EXPERIMENTAL）：

  ¥experimental (NAPI_EXPERIMENTAL is defined):

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

  ¥A function of this type may no longer be used as a finalizer, except with node_api_post_finalizer. node_api_basic_finalize must be used instead. This feature can be turned off by defining NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.

napi_async_execute_callback#

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

¥Function pointer used with functions that support asynchronous operations. Callback functions must satisfy the following signature:

typedef void (*napi_async_execute_callback)(napi_env env, void* data); 拷贝

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

¥Implementations of this function must avoid making Node-API calls that execute JavaScript or interact with JavaScript objects. Node-API calls should be in the napi_async_complete_callback instead. Do not use the napi_env parameter as it will likely result in execution of JavaScript.

napi_async_complete_callback#

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

¥Function pointer used with functions that support asynchronous operations. Callback functions must satisfy the following signature:

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

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

¥Unless for reasons discussed in Object Lifetime Management, creating a handle and/or callback scope inside the function body is not necessary.

napi_threadsafe_function_call_js#

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

¥Function pointer used with asynchronous thread-safe function calls. The callback will be called on the main thread. Its purpose is to use a data item arriving via the queue from one of the secondary threads to construct the parameters necessary for a call into JavaScript, usually via napi_call_function, and then make the call into JavaScript.

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

¥The data arriving from the secondary thread via the queue is given in the data parameter and the JavaScript function to call is given in the js_callback parameter.

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

¥Node-API sets up the environment prior to calling this callback, so it is sufficient to call the JavaScript function via napi_call_function rather than via napi_make_callback.

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

¥Callback functions must satisfy the following signature:

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

• [in] env：用于 API 调用的环境，或者 NULL，如果线程安全函数正在被拆除并且 data 可能需要被释放。

  ¥[in] env: The environment to use for API calls, or NULL if the thread-safe function is being torn down and data may need to be freed.

• [in] js_callback：要调用的 JavaScript 函数，或者 NULL，如果线程安全函数正在被拆除并且 data 可能需要被释放。如果线程安全函数是在没有 js_callback 的情况下创建的，它也可能是 NULL。

  ¥[in] js_callback: The JavaScript function to call, or NULL if the thread-safe function is being torn down and data may need to be freed. It may also be NULL if the thread-safe function was created without js_callback.

• [in] context：用于创建线程安全函数的可选数据。

  ¥[in] context: The optional data with which the thread-safe function was created.

• [in] data：由辅助线程创建的数据。回调负责将此原生数据转换为 JavaScript 值（使用 Node-API 函数），这些值可以在调用 js_callback 时作为参数传递。这个指针完全由线程和这个回调管理。因此这个回调应该释放数据。

  ¥[in] data: Data created by the secondary thread. It is the responsibility of the callback to convert this native data to JavaScript values (with Node-API functions) that can be passed as parameters when js_callback is invoked. This pointer is managed entirely by the threads and this callback. Thus this callback should free the data.

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

¥Unless for reasons discussed in Object Lifetime Management, creating a handle and/or callback scope inside the function body is not necessary.

napi_cleanup_hook#

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

¥Function pointer used with napi_add_env_cleanup_hook. It will be called when the environment is being torn down.

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

¥Callback functions must satisfy the following signature:

typedef void (*napi_cleanup_hook)(void* data); 拷贝

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

  ¥[in] data: The data that was passed to napi_add_env_cleanup_hook.

napi_async_cleanup_hook#

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

¥Function pointer used with napi_add_async_cleanup_hook. It will be called when the environment is being torn down.

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

¥Callback functions must satisfy the following signature:

typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
                                        void* data); 拷贝

• [in] handle：完成异步清理后必须传递给 napi_remove_async_cleanup_hook 的句柄。

  ¥[in] handle: The handle that must be passed to napi_remove_async_cleanup_hook after completion of the asynchronous cleanup.

• [in] data：传递给 napi_add_async_cleanup_hook 的数据。

  ¥[in] data: The data that was passed to napi_add_async_cleanup_hook.

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

¥The body of the function should initiate the asynchronous cleanup actions at the end of which handle must be passed in a call to napi_remove_async_cleanup_hook.

错误处理#

¥Error handling

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

¥Node-API uses both return values and JavaScript exceptions for error handling. The following sections explain the approach for each case.

返回值#

¥Return values

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

¥All of the Node-API functions share the same error handling pattern. The return type of all API functions is napi_status.

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

¥The return value will be napi_ok if the request was successful and no uncaught JavaScript exception was thrown. If an error occurred AND an exception was thrown, the napi_status value for the error will be returned. If an exception was thrown, and no error occurred, napi_pending_exception will be returned.

在返回 napi_ok 或 napi_pending_exception 以外的返回值的情况下，必须调用 napi_is_exception_pending 来检查是否有异常挂起。有关更多详细信息，请参阅异常部分。

¥In cases where a return value other than napi_ok or napi_pending_exception is returned, napi_is_exception_pending must be called to check if an exception is pending. See the section on exceptions for more details.

napi_api_types.h 中定义了整套可能的 napi_status 值。

¥The full set of possible napi_status values is defined in napi_api_types.h.

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

¥The napi_status return value provides a VM-independent representation of the error which occurred. In some cases it is useful to be able to get more detailed information, including a string representing the error as well as VM (engine)-specific information.

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

¥In order to retrieve this information napi_get_last_error_info is provided which returns a napi_extended_error_info structure. The format of the napi_extended_error_info structure is as follows:

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

• error_message：所发生错误的文本表示。

  ¥error_message: Textual representation of the error that occurred.

• engine_reserved：不透明句柄仅供引擎使用。

  ¥engine_reserved: Opaque handle reserved for engine use only.

• engine_error_code：VM 特定的错误代码。

  ¥engine_error_code: VM specific error code.

• error_code：最后一个错误的节点 API 状态代码。

  ¥error_code: Node-API status code for the last error.

napi_get_last_error_info 返回最后一次调用 Node-API 的信息。

¥napi_get_last_error_info returns the information for the last Node-API call that was made.

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

¥Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes.

napi_get_last_error_info#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [out] result：包含有关错误的更多信息的 napi_extended_error_info 结构。

  ¥[out] result: The napi_extended_error_info structure with more information about the error.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 检索 napi_extended_error_info 结构，其中包含有关发生的最后一个错误的信息。

¥This API retrieves a napi_extended_error_info structure with information about the last error that occurred.

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

¥The content of the napi_extended_error_info returned is only valid up until a Node-API function is called on the same env. This includes a call to napi_is_exception_pending so it may often be necessary to make a copy of the information so that it can be used later. The pointer returned in error_message points to a statically-defined string so it is safe to use that pointer if you have copied it out of the error_message field (which will be overwritten) before another Node-API function was called.

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

¥Do not rely on the content or format of any of the extended information as it is not subject to SemVer and may change at any time. It is intended only for logging purposes.

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

¥This API can be called even if there is a pending JavaScript exception.

异常#

¥Exceptions

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

¥Any Node-API function call may result in a pending JavaScript exception. This is the case for any of the API functions, even those that may not cause the execution of JavaScript.

如果函数返回的 napi_status 是 napi_ok，则没有异常挂起，也不需要额外的操作。如果返回的 napi_status 不是 napi_ok 或 napi_pending_exception，为了尝试恢复并继续而不是简单地立即返回，必须调用 napi_is_exception_pending 以确定异常是否挂起。

¥If the napi_status returned by a function is napi_ok then no exception is pending and no additional action is required. If the napi_status returned is anything other than napi_ok or napi_pending_exception, in order to try to recover and continue instead of simply returning immediately, napi_is_exception_pending must be called in order to determine if an exception is pending or not.

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

¥In many cases when a Node-API function is called and an exception is already pending, the function will return immediately with a napi_status of napi_pending_exception. However, this is not the case for all functions. Node-API allows a subset of the functions to be called to allow for some minimal cleanup before returning to JavaScript. In that case, napi_status will reflect the status for the function. It will not reflect previous pending exceptions. To avoid confusion, check the error status after every function call.

当异常悬而未决时，可以采用两种方法之一。

¥When an exception is pending one of two approaches can be employed.

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

¥The first approach is to do any appropriate cleanup and then return so that execution will return to JavaScript. As part of the transition back to JavaScript, the exception will be thrown at the point in the JavaScript code where the native method was invoked. The behavior of most Node-API calls is unspecified while an exception is pending, and many will simply return napi_pending_exception, so do as little as possible and then return to JavaScript where the exception can be handled.

第二种方法是尝试处理异常。在某些情况下，原生代码可以捕获异常，采取适当的操作，然后继续。仅在已知可以安全处理异常的特定情况下才建议这样做。在这些情况下，napi_get_and_clear_last_exception 可用于获取和清除异常。成功时，结果将包含最后抛出的 JavaScript Object 的句柄。如果确定，在检索异常后，异常无法处理，毕竟可以用 napi_throw 重新抛出它，其中 error 是要抛出的 JavaScript 值。

¥The second approach is to try to handle the exception. There will be cases where the native code can catch the exception, take the appropriate action, and then continue. This is only recommended in specific cases where it is known that the exception can be safely handled. In these cases napi_get_and_clear_last_exception can be used to get and clear the exception. On success, result will contain the handle to the last JavaScript Object thrown. If it is determined, after retrieving the exception, the exception cannot be handled after all it can be re-thrown it with napi_throw where error is the JavaScript value to be thrown.

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

¥The following utility functions are also available in case native code needs to throw an exception or determine if a napi_value is an instance of a JavaScript Error object: napi_throw_error, napi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_error and napi_is_error.

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

¥The following utility functions are also available in case native code needs to create an Error object: napi_create_error, napi_create_type_error, napi_create_range_error and node_api_create_syntax_error, where result is the napi_value that refers to the newly created JavaScript Error object.

Node.js 项目正在为内部生成的所有错误添加错误代码。目标是让应用使用这些错误代码进行所有错误检查。关联的错误消息将保留，但仅用于记录和显示，期望消息可以在不应用 SemVer 的情况下更改。为了使用 Node-API 支持此模型，无论是内部功能还是模块特定功能（作为其良好实践），throw_ 和 create_ 函数采用可选代码参数，该参数是要添加到错误中的代码字符串 目的。如果可选参数是 NULL，则没有代码与错误关联。如果提供了代码，则与错误关联的名称也会更新为：

¥The Node.js project is adding error codes to all of the errors generated internally. The goal is for applications to use these error codes for all error checking. The associated error messages will remain, but will only be meant to be used for logging and display with the expectation that the message can change without SemVer applying. In order to support this model with Node-API, both in internal functionality and for module specific functionality (as its good practice), the throw_ and create_ functions take an optional code parameter which is the string for the code to be added to the error object. If the optional parameter is NULL then no code will be associated with the error. If a code is provided, the name associated with the error is also updated to be:

originalName [code] 拷贝

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

¥where originalName is the original name associated with the error and code is the code that was provided. For example, if the code is 'ERR_ERROR_1' and a TypeError is being created the name will be:

TypeError [ERR_ERROR_1] 拷贝

napi_throw#

NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] error：要抛出的 JavaScript 值。

  ¥[in] error: The JavaScript value to be thrown.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 抛出提供的 JavaScript 值。

¥This API throws the JavaScript value provided.

napi_throw_error#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] code：要在错误上设置的可选错误代码。

  ¥[in] code: Optional error code to be set on the error.

• [in] msg：表示与错误关联的文本的 C 字符串。

  ¥[in] msg: C string representing the text to be associated with the error.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API throws a JavaScript Error with the text provided.

napi_throw_type_error#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] code：要在错误上设置的可选错误代码。

  ¥[in] code: Optional error code to be set on the error.

• [in] msg：表示与错误关联的文本的 C 字符串。

  ¥[in] msg: C string representing the text to be associated with the error.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API throws a JavaScript TypeError with the text provided.

napi_throw_range_error#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] code：要在错误上设置的可选错误代码。

  ¥[in] code: Optional error code to be set on the error.

• [in] msg：表示与错误关联的文本的 C 字符串。

  ¥[in] msg: C string representing the text to be associated with the error.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API throws a JavaScript RangeError with the text provided.

node_api_throw_syntax_error#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] code：要在错误上设置的可选错误代码。

  ¥[in] code: Optional error code to be set on the error.

• [in] msg：表示与错误关联的文本的 C 字符串。

  ¥[in] msg: C string representing the text to be associated with the error.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API throws a JavaScript SyntaxError with the text provided.

napi_is_error#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要检查的 napi_value。

  ¥[in] value: The napi_value to be checked.

• [out] result：如果 napi_value 表示错误，则设置为 true 的布尔值，否则设置为 false。

  ¥[out] result: Boolean value that is set to true if napi_value represents an error, false otherwise.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API queries a napi_value to check if it represents an error object.

napi_create_error#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] code：可选的 napi_value，带有与错误关联的错误代码的字符串。

  ¥[in] code: Optional napi_value with the string for the error code to be associated with the error.

• [in] msg：napi_value 引用 JavaScript string 用作 Error 的消息。

  ¥[in] msg: napi_value that references a JavaScript string to be used as the message for the Error.

• [out] result：napi_value 表示创建的错误。

  ¥[out] result: napi_value representing the error created.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API returns a JavaScript Error with the text provided.

napi_create_type_error#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] code：可选的 napi_value，带有与错误关联的错误代码的字符串。

  ¥[in] code: Optional napi_value with the string for the error code to be associated with the error.

• [in] msg：napi_value 引用 JavaScript string 用作 Error 的消息。

  ¥[in] msg: napi_value that references a JavaScript string to be used as the message for the Error.

• [out] result：napi_value 表示创建的错误。

  ¥[out] result: napi_value representing the error created.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API returns a JavaScript TypeError with the text provided.

napi_create_range_error#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] code：可选的 napi_value，带有与错误关联的错误代码的字符串。

  ¥[in] code: Optional napi_value with the string for the error code to be associated with the error.

• [in] msg：napi_value 引用 JavaScript string 用作 Error 的消息。

  ¥[in] msg: napi_value that references a JavaScript string to be used as the message for the Error.

• [out] result：napi_value 表示创建的错误。

  ¥[out] result: napi_value representing the error created.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API returns a JavaScript RangeError with the text provided.

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); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] code：可选的 napi_value，带有与错误关联的错误代码的字符串。

  ¥[in] code: Optional napi_value with the string for the error code to be associated with the error.

• [in] msg：napi_value 引用 JavaScript string 用作 Error 的消息。

  ¥[in] msg: napi_value that references a JavaScript string to be used as the message for the Error.

• [out] result：napi_value 表示创建的错误。

  ¥[out] result: napi_value representing the error created.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API returns a JavaScript SyntaxError with the text provided.

napi_get_and_clear_last_exception#

napi_status napi_get_and_clear_last_exception(napi_env env,
                                              napi_value* result); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [out] result：如果一个未决则异常，否则为 NULL。

  ¥[out] result: The exception if one is pending, NULL otherwise.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API can be called even if there is a pending JavaScript exception.

napi_is_exception_pending#

napi_status napi_is_exception_pending(napi_env env, bool* result); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [out] result：如果异常挂起，则设置为 true 的布尔值。

  ¥[out] result: Boolean value that is set to true if an exception is pending.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API can be called even if there is a pending JavaScript exception.

napi_fatal_exception#

napi_status napi_fatal_exception(napi_env env, napi_value err); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] err：传递给 'uncaughtException' 的错误。

  ¥[in] err: The error that is passed to 'uncaughtException'.

在 JavaScript 中触发 'uncaughtException'。如果异步回调抛出无法恢复的异常，则很有用。

¥Trigger an 'uncaughtException' in JavaScript. Useful if an async callback throws an exception with no way to recover.

致命错误#

¥Fatal errors

如果原生插件中出现不可恢复的错误，则可以抛出致命错误以立即终止进程。

¥In the event of an unrecoverable error in a native addon, a fatal error can be thrown to immediately terminate the process.

napi_fatal_error#

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

• [in] location：发生错误的可选位置。

  ¥[in] location: Optional location at which the error occurred.

• [in] location_len：位置的长度（以字节为单位），如果它以 null 结尾则为 NAPI_AUTO_LENGTH。

  ¥[in] location_len: The length of the location in bytes, or NAPI_AUTO_LENGTH if it is null-terminated.

• [in] message：与错误关联的消息。

  ¥[in] message: The message associated with the error.

• [in] message_len：消息的长度（以字节为单位），如果以 null 结尾则为 NAPI_AUTO_LENGTH。

  ¥[in] message_len: The length of the message in bytes, or NAPI_AUTO_LENGTH if it is null-terminated.

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

¥The function call does not return, the process will be terminated.

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

¥This API can be called even if there is a pending JavaScript exception.

对象生命周期管理#

¥Object lifetime management

在进行 Node-API 调用时，底层 VM 的堆中对象的句柄可能会作为 napi_values 返回。这些句柄必须持有对象 'live'，直到原生代码不再需要它们，否则这些对象可能会在原生代码使用完它们之前被收集。

¥As Node-API calls are made, handles to objects in the heap for the underlying VM may be returned as napi_values. These handles must hold the objects 'live' until they are no longer required by the native code, otherwise the objects could be collected before the native code was finished using them.

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

¥As object handles are returned they are associated with a 'scope'. The lifespan for the default scope is tied to the lifespan of the native method call. The result is that, by default, handles remain valid and the objects associated with these handles will be held live for the lifespan of the native method call.

然而，在许多情况下，句柄必须在比本地方法更短或更长的生命周期内保持有效。以下部分描述了可用于更改默认句柄寿命的 Node-API 函数。

¥In many cases, however, it is necessary that the handles remain valid for either a shorter or longer lifespan than that of the native method. The sections which follow describe the Node-API functions that can be used to change the handle lifespan from the default.

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

¥Making handle lifespan shorter than that of the native method

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

¥It is often necessary to make the lifespan of handles shorter than the lifespan of a native method. For example, consider a native method that has a loop which iterates through the elements in a large array:

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
} 拷贝

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

¥This would result in a large number of handles being created, consuming substantial resources. In addition, even though the native code could only use the most recent handle, all of the associated objects would also be kept alive since they all share the same scope.

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

¥To handle this case, Node-API provides the ability to establish a new 'scope' to which newly created handles will be associated. Once those handles are no longer required, the scope can be 'closed' and any handles associated with the scope are invalidated. The methods available to open/close scopes are napi_open_handle_scope and napi_close_handle_scope.

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

¥Node-API only supports a single nested hierarchy of scopes. There is only one active scope at any time, and all new handles will be associated with that scope while it is active. Scopes must be closed in the reverse order from which they are opened. In addition, all scopes created within a native method must be closed before returning from that method.

以前面的例子为例，添加对 napi_open_handle_scope 和 napi_close_handle_scope 的调用将确保在整个循环执行过程中最多只有一个句柄有效：

¥Taking the earlier example, adding calls to napi_open_handle_scope and napi_close_handle_scope would ensure that at most a single handle is valid throughout the execution of the loop:

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;
  }
} 拷贝

嵌套作用域时，有时内部作用域的句柄需要超出该作用域的生命周期。Node-API 支持 '可转义的范围' 以支持这种情况。可转义作用域允许一个句柄为 'promoted'，以便 'escapes' 当前作用域和句柄的生命周期从当前作用域变为外部作用域。

¥When nesting scopes, there are cases where a handle from an inner scope needs to live beyond the lifespan of that scope. Node-API supports an 'escapable scope' in order to support this case. An escapable scope allows one handle to be 'promoted' so that it 'escapes' the current scope and the lifespan of the handle changes from the current scope to that of the outer scope.

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

¥The methods available to open/close escapable scopes are napi_open_escapable_handle_scope and napi_close_escapable_handle_scope.

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

¥The request to promote a handle is made through napi_escape_handle which can only be called once.

napi_open_handle_scope#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [out] result：napi_value 代表新范围。

  ¥[out] result: napi_value representing the new scope.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 开辟了一个新的范围。

¥This API opens a new scope.

napi_close_handle_scope#

NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
                                                napi_handle_scope scope); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] scope：napi_value 表示要关闭的范围。

  ¥[in] scope: napi_value representing the scope to be closed.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 关闭传入的范围。必须按照创建范围的相反顺序关闭范围。

¥This API closes the scope passed in. Scopes must be closed in the reverse order from which they were created.

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

¥This API can be called even if there is a pending JavaScript exception.

napi_open_escapable_handle_scope#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [out] result：napi_value 代表新范围。

  ¥[out] result: napi_value representing the new scope.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 会打开一个新范围，从中可以将一个对象提升到外部范围。

¥This API opens a new scope from which one object can be promoted to the outer scope.

napi_close_escapable_handle_scope#

NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] scope：napi_value 表示要关闭的范围。

  ¥[in] scope: napi_value representing the scope to be closed.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 关闭传入的范围。必须按照创建范围的相反顺序关闭范围。

¥This API closes the scope passed in. Scopes must be closed in the reverse order from which they were created.

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

¥This API can be called even if there is a pending JavaScript exception.

napi_escape_handle#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] scope：napi_value 代表当前范围。

  ¥[in] scope: napi_value representing the current scope.

• [in] escapee：napi_value 表示要转义的 JavaScript Object。

  ¥[in] escapee: napi_value representing the JavaScript Object to be escaped.

• [out] result：napi_value 表示外部作用域中转义的 Object 的句柄。

  ¥[out] result: napi_value representing the handle to the escaped Object in the outer scope.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API promotes the handle to the JavaScript object so that it is valid for the lifetime of the outer scope. It can only be called once per scope. If it is called more than once an error will be returned.

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

¥This API can be called even if there is a pending JavaScript exception.

对生命周期比原生方法长的值的引用#

¥References to values with a lifespan longer than that of the native method

在某些情况下，插件需要能够创建和引用生命周期比单个本地方法调用更长的值。例如，要创建构造函数并稍后在创建实例的请求中使用该构造函数，必须可以在许多不同的实例创建请求中引用构造函数对象。这对于如前一节所述作为 napi_value 返回的普通句柄是不可能的。普通句柄的生命周期由作用域管理，所有作用域都必须在本地方法结束之前关闭。

¥In some cases, an addon will need to be able to create and reference values with a lifespan longer than that of a single native method invocation. For example, to create a constructor and later use that constructor in a request to create instances, it must be possible to reference the constructor object across many different instance creation requests. This would not be possible with a normal handle returned as a napi_value as described in the earlier section. The lifespan of a normal handle is managed by scopes and all scopes must be closed before the end of a native method.

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

¥Node-API provides methods for creating persistent references to values. Currently Node-API only allows references to be created for a limited set of value types, including object, external, function, and symbol.

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

¥Each reference has an associated count with a value of 0 or higher, which determines whether the reference will keep the corresponding value alive. References with a count of 0 do not prevent values from being collected. Values of object (object, function, external) and symbol types are becoming 'weak' references and can still be accessed while they are not collected. Any count greater than 0 will prevent the values from being collected.

符号值有不同的风格。只有使用 napi_create_symbol 函数或 JavaScript Symbol() 构造函数调用创建的局部符号才支持真正的弱引用行为。使用 node_api_symbol_for 函数或 JavaScript Symbol.for() 函数调用创建的全局注册符号始终保持强引用，因为垃圾收集器不会收集它们。Symbol.iterator 等知名符号也是如此。它们也永远不会被垃圾收集器收集。

¥Symbol values have different flavors. The true weak reference behavior is only supported by local symbols created with the napi_create_symbol function or the JavaScript Symbol() constructor calls. Globally registered symbols created with the node_api_symbol_for function or JavaScript Symbol.for() function calls remain always strong references because the garbage collector does not collect them. The same is true for well-known symbols such as Symbol.iterator. They are also never collected by the garbage collector.

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

¥References can be created with an initial reference count. The count can then be modified through napi_reference_ref and napi_reference_unref. If an object is collected while the count for a reference is 0, all subsequent calls to get the object associated with the reference napi_get_reference_value will return NULL for the returned napi_value. An attempt to call napi_reference_ref for a reference whose object has been collected results in an error.

一旦插件不再需要引用，就必须删除它们。删除引用后，将不再阻止收集相应的对象。未能删除持久引用会导致 '内存泄漏' 永久保留用于持久引用的原生内存和堆上的相应对象。

¥References must be deleted once they are no longer required by the addon. When a reference is deleted, it will no longer prevent the corresponding object from being collected. Failure to delete a persistent reference results in a 'memory leak' with both the native memory for the persistent reference and the corresponding object on the heap being retained forever.

可以创建多个指向同一个对象的持久引用，每个持久引用将根据其各自的计数使对象保持活动状态。对同一对象的多个持久引用可能会导致原生内存意外保持活动状态。持久引用的原生结构必须保持活动状态，直到执行引用对象的终结器。如果为同一对象创建新的持久引用，则不会运行该对象的终结器，并且不会释放先前持久引用指向的原生内存。这可以通过在可能的情况下除了 napi_reference_unref 之外还调用 napi_delete_reference 来避免。

¥There can be multiple persistent references created which refer to the same object, each of which will either keep the object live or not based on its individual count. Multiple persistent references to the same object can result in unexpectedly keeping alive native memory. The native structures for a persistent reference must be kept alive until finalizers for the referenced object are executed. If a new persistent reference is created for the same object, the finalizers for that object will not be run and the native memory pointed by the earlier persistent reference will not be freed. This can be avoided by calling napi_delete_reference in addition to napi_reference_unref when possible.

变更历史：

¥Change History:

• 实验性的（定义了 NAPI_EXPERIMENTAL）：

  ¥Experimental (NAPI_EXPERIMENTAL is defined):

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

  ¥References can be created for all value types. The new supported value types do not support weak reference semantic and the values of these types are released when the reference count becomes 0 and cannot be accessed from the reference anymore.

napi_create_reference#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：正在为其创建引用的 napi_value。

  ¥[in] value: The napi_value for which a reference is being created.

• [in] initial_refcount：新引用的初始引用计数。

  ¥[in] initial_refcount: Initial reference count for the new reference.

• [out] result：napi_ref 指向新的引用。

  ¥[out] result: napi_ref pointing to the new reference.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

该 API 对传入的值创建一个具有指定引用计数的新引用。

¥This API creates a new reference with the specified reference count to the value passed in.

napi_delete_reference#

NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] ref：napi_ref 被删除。

  ¥[in] ref: napi_ref to be deleted.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

该 API 删除传入的引用。

¥This API deletes the reference passed in.

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

¥This API can be called even if there is a pending JavaScript exception.

napi_reference_ref#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] ref：napi_ref，其引用计数将增加。

  ¥[in] ref: napi_ref for which the reference count will be incremented.

• [out] result：新的引用计数。

  ¥[out] result: The new reference count.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 增加传入引用的引用计数并返回生成的引用计数。

¥This API increments the reference count for the reference passed in and returns the resulting reference count.

napi_reference_unref#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] ref：将减少其引用计数的 napi_ref。

  ¥[in] ref: napi_ref for which the reference count will be decremented.

• [out] result：新的引用计数。

  ¥[out] result: The new reference count.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 递减传入引用的引用计数并返回生成的引用计数。

¥This API decrements the reference count for the reference passed in and returns the resulting reference count.

napi_get_reference_value#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] ref：请求相应值的 napi_ref。

  ¥[in] ref: The napi_ref for which the corresponding value is being requested.

• [out] result：napi_ref 引用的 napi_value。

  ¥[out] result: The napi_value referenced by the napi_ref.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥If still valid, this API returns the napi_value representing the JavaScript value associated with the napi_ref. Otherwise, result will be NULL.

当前 Node.js 环境退出时的清理#

¥Cleanup on exit of the current Node.js environment

虽然 Node.js 进程通常会在退出时释放其所有资源，但 Node.js 的嵌入程序或未来的 Worker 支持可能需要插件来注册清理钩子，一旦当前 Node.js 环境退出，这些钩子就会运行。

¥While a Node.js process typically releases all its resources when exiting, embedders of Node.js, or future Worker support, may require addons to register clean-up hooks that will be run once the current Node.js environment exits.

Node-API 提供了注册和取消注册此类回调的功能。当这些回调运行时，插件持有的所有资源都应该被释放。

¥Node-API provides functions for registering and un-registering such callbacks. When those callbacks are run, all resources that are being held by the addon should be freed up.

napi_add_env_cleanup_hook#

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

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

¥Registers fun as a function to be run with the arg parameter once the current Node.js environment exits.

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

¥A function can safely be specified multiple times with different arg values. In that case, it will be called multiple times as well. Providing the same fun and arg values multiple times is not allowed and will lead the process to abort.

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

¥The hooks will be called in reverse order, i.e. the most recently added one will be called first.

可以使用 napi_remove_env_cleanup_hook 删除此钩子。通常，当为其添加此钩子的资源无论如何都被拆除时，就会发生这种情况。

¥Removing this hook can be done by using napi_remove_env_cleanup_hook. Typically, that happens when the resource for which this hook was added is being torn down anyway.

对于异步清理，napi_add_async_cleanup_hook 可用。

¥For asynchronous cleanup, napi_add_async_cleanup_hook is available.

napi_remove_env_cleanup_hook#

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

一旦当前 Node.js 环境退出，将 fun 注销为要使用 arg 参数运行的函数。参数和函数值都需要完全匹配。

¥Unregisters fun as a function to be run with the arg parameter once the current Node.js environment exits. Both the argument and the function value need to be exact matches.

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

¥The function must have originally been registered with napi_add_env_cleanup_hook, otherwise the process will abort.

napi_add_async_cleanup_hook#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] hook：在环境拆卸时调用的函数指针。

  ¥[in] hook: The function pointer to call at environment teardown.

• [in] arg：调用时传递给 hook 的指针。

  ¥[in] arg: The pointer to pass to hook when it gets called.

• [out] remove_handle：引用异步清理钩子的可选句柄。

  ¥[out] remove_handle: Optional handle that refers to the asynchronous cleanup hook.

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

¥Registers hook, which is a function of type napi_async_cleanup_hook, as a function to be run with the remove_handle and arg parameters once the current Node.js environment exits.

与 napi_add_env_cleanup_hook 不同的是，hook 允许是异步的。

¥Unlike napi_add_env_cleanup_hook, the hook is allowed to be asynchronous.

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

¥Otherwise, behavior generally matches that of napi_add_env_cleanup_hook.

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

¥If remove_handle is not NULL, an opaque value will be stored in it that must later be passed to napi_remove_async_cleanup_hook, regardless of whether the hook has already been invoked. Typically, that happens when the resource for which this hook was added is being torn down anyway.

napi_remove_async_cleanup_hook#

NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
    napi_async_cleanup_hook_handle remove_handle); 拷贝

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

  ¥[in] remove_handle: The handle to an asynchronous cleanup hook that was created with napi_add_async_cleanup_hook.

注销对应于 remove_handle 的清除钩子。这将阻止执行钩子，除非它已经开始执行。这必须在从 napi_add_async_cleanup_hook 获得的任何 napi_async_cleanup_hook_handle 值上调用。

¥Unregisters the cleanup hook corresponding to remove_handle. This will prevent the hook from being executed, unless it has already started executing. This must be called on any napi_async_cleanup_hook_handle value obtained from napi_add_async_cleanup_hook.

在 Node.js 环境退出时完成#

¥Finalization on the exit of the Node.js environment

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

¥The Node.js environment may be torn down at an arbitrary time as soon as possible with JavaScript execution disallowed, like on the request of worker.terminate(). When the environment is being torn down, the registered napi_finalize callbacks of JavaScript objects, thread-safe functions and environment instance data are invoked immediately and independently.

napi_finalize 回调的调用安排在手动注册的清理钩子之后。为了确保在环境关闭期间插件完成的正确顺序以避免 napi_finalize 回调中的释放后使用，插件应该向 napi_add_env_cleanup_hook 和 napi_add_async_cleanup_hook 注册一个清理钩子，以便以正确的顺序手动释放分配的资源。

¥The invocation of napi_finalize callbacks is scheduled after the manually registered cleanup hooks. In order to ensure a proper order of addon finalization during environment shutdown to avoid use-after-free in the napi_finalize callback, addons should register a cleanup hook with napi_add_env_cleanup_hook and napi_add_async_cleanup_hook to manually release the allocated resource in a proper order.

模块注册#

¥Module registration

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

¥Node-API modules are registered in a manner similar to other modules except that instead of using the NODE_MODULE macro the following is used:

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init) 拷贝

下一个区别是 Init 方法的签名。对于 Node-API 模块，它如下所示：

¥The next difference is the signature for the Init method. For a Node-API module it is as follows:

napi_value Init(napi_env env, napi_value exports); 拷贝

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

¥The return value from Init is treated as the exports object for the module. The Init method is passed an empty object via the exports parameter as a convenience. If Init returns NULL, the parameter passed as exports is exported by the module. Node-API modules cannot modify the module object but can specify anything as the exports property of the module.

将方法 hello 添加为函数，以便它可以作为插件提供的方法调用：

¥To add the method hello as a function so that it can be called as a method provided by the addon:

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;
} 拷贝

要为插件设置 require() 返回的函数：

¥To set a function to be returned by the require() for the addon:

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;
} 拷贝

定义一个类以便创建新实例（通常与 对象封装 一起使用）：

¥To define a class so that new instances can be created (often used with 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;
} 拷贝

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

¥You can also use the NAPI_MODULE_INIT macro, which acts as a shorthand for NAPI_MODULE and defining an Init function:

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;
} 拷贝

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

¥The parameters env and exports are provided to the body of the NAPI_MODULE_INIT macro.

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

¥All Node-API addons are context-aware, meaning they may be loaded multiple times. There are a few design considerations when declaring such a module. The documentation on context-aware addons provides more details.

宏调用后，变量 env 和 exports 将在函数体内可用。

¥The variables env and exports will be available inside the function body following the macro invocation.

有关设置对象属性的更多详细信息，请参阅 使用 JavaScript 属性 部分。

¥For more details on setting properties on objects, see the section on Working with JavaScript properties.

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

¥For more details on building addon modules in general, refer to the existing API.

使用 JavaScript 值#

¥Working with JavaScript values

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

¥Node-API exposes a set of APIs to create all types of JavaScript values. Some of these types are documented under Section 6 of the ECMAScript Language Specification.

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

¥Fundamentally, these APIs are used to do one of the following:

1. 创建一个新的 JavaScript 对象

   ¥Create a new JavaScript object

2. 从原始 C 类型转换为 Node-API 值

   ¥Convert from a primitive C type to a Node-API value

3. 从 Node-API 值转换为原始 C 类型

   ¥Convert from Node-API value to a primitive C type

4. 获取全局实例包括 undefined 和 null

   ¥Get global instances including undefined and null

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

¥Node-API values are represented by the type napi_value. Any Node-API call that requires a JavaScript value takes in a napi_value. In some cases, the API does check the type of the napi_value up-front. However, for better performance, it's better for the caller to make sure that the napi_value in question is of the JavaScript type expected by the API.

枚举类型#

¥Enum types

napi_key_collection_mode#

typedef enum {
  napi_key_include_prototypes,
  napi_key_own_only
} napi_key_collection_mode; 拷贝

描述 Keys/Properties 过滤器枚举：

¥Describes the Keys/Properties filter enums:

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

¥napi_key_collection_mode limits the range of collected properties.

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

¥napi_key_own_only limits the collected properties to the given object only. napi_key_include_prototypes will include all keys of the objects's prototype chain as well.

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; 拷贝

属性过滤器位。它们可以被 or' 构建一个复合过滤器。

¥Property filter bits. They can be or'ed to build a composite filter.

napi_key_conversion#

typedef enum {
  napi_key_keep_numbers,
  napi_key_numbers_to_strings
} napi_key_conversion; 拷贝

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

¥napi_key_numbers_to_strings will convert integer indexes to strings. napi_key_keep_numbers will return numbers for integer indexes.

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; 拷贝

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

¥Describes the type of a napi_value. This generally corresponds to the types described in Section 6.1 of the ECMAScript Language Specification. In addition to types in that section, napi_valuetype can also represent Functions and Objects with external data.

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

¥A JavaScript value of type napi_external appears in JavaScript as a plain object such that no properties can be set on it, and no prototype.

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; 拷贝

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

¥This represents the underlying binary scalar datatype of the TypedArray. Elements of this enum correspond to Section 22.2 of the ECMAScript Language Specification.

对象创建函数#

¥Object creation functions

napi_create_array#

napi_status napi_create_array(napi_env env, napi_value* result) 拷贝

• [in] env：调用 Node-API 调用的环境。

  ¥[in] env: The environment that the Node-API call is invoked under.

• [out] result：代表 JavaScript Array 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript Array.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API returns a Node-API value corresponding to a JavaScript Array type. JavaScript arrays are described in Section 22.1 of the ECMAScript Language Specification.

napi_create_array_with_length#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] length：Array 的初始长度。

  ¥[in] length: The initial length of the Array.

• [out] result：代表 JavaScript Array 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript Array.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 返回对应于 JavaScript Array 类型的 Node-API 值。Array 的长度属性设置为传入的长度参数。但是，不保证底层缓冲区在创建数组时由 VM 预先分配。该行为留给底层 VM 实现。如果缓冲区必须是可以通过 C 直接读取和/或写入的连续内存块，请考虑使用 napi_create_external_arraybuffer。

¥This API returns a Node-API value corresponding to a JavaScript Array type. The Array's length property is set to the passed-in length parameter. However, the underlying buffer is not guaranteed to be pre-allocated by the VM when the array is created. That behavior is left to the underlying VM implementation. If the buffer must be a contiguous block of memory that can be directly read and/or written via C, consider using napi_create_external_arraybuffer.

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

¥JavaScript arrays are described in Section 22.1 of the ECMAScript Language Specification.

napi_create_arraybuffer#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] length：要创建的数组缓冲区的字节长度。

  ¥[in] length: The length in bytes of the array buffer to create.

• [out] data：指向 ArrayBuffer 的底层字节缓冲区的指针。data 可以选择性地通过传递 NULL 来忽略。

  ¥[out] data: Pointer to the underlying byte buffer of the ArrayBuffer. data can optionally be ignored by passing NULL.

• [out] result：代表 JavaScript ArrayBuffer 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript ArrayBuffer.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API returns a Node-API value corresponding to a JavaScript ArrayBuffer. ArrayBuffers are used to represent fixed-length binary data buffers. They are normally used as a backing-buffer for TypedArray objects. The ArrayBuffer allocated will have an underlying byte buffer whose size is determined by the length parameter that's passed in. The underlying buffer is optionally returned back to the caller in case the caller wants to directly manipulate the buffer. This buffer can only be written to directly from native code. To write to this buffer from JavaScript, a typed array or DataView object would need to be created.

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

¥JavaScript ArrayBuffer objects are described in Section 24.1 of the ECMAScript Language Specification.

napi_create_buffer#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] size：底层缓冲区的大小（以字节为单位）。

  ¥[in] size: Size in bytes of the underlying buffer.

• [out] data：指向底层缓冲区的原始指针。data 可以选择性地通过传递 NULL 来忽略。

  ¥[out] data: Raw pointer to the underlying buffer. data can optionally be ignored by passing NULL.

• [out] result：一个 napi_value 代表一个 node::Buffer。

  ¥[out] result: A napi_value representing a node::Buffer.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API allocates a node::Buffer object. While this is still a fully-supported data structure, in most cases using a TypedArray will suffice.

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) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] size：输入缓冲区的大小（以字节为单位）（应与新缓冲区的大小相同）。

  ¥[in] size: Size in bytes of the input buffer (should be the same as the size of the new buffer).

• [in] data：指向要从中复制的基础缓冲区的原始指针。

  ¥[in] data: Raw pointer to the underlying buffer to copy from.

• [out] result_data：指向新 Buffer 的基础数据缓冲区的指针。result_data 可以选择性地通过传递 NULL 来忽略。

  ¥[out] result_data: Pointer to the new Buffer's underlying data buffer. result_data can optionally be ignored by passing NULL.

• [out] result：一个 napi_value 代表一个 node::Buffer。

  ¥[out] result: A napi_value representing a node::Buffer.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API allocates a node::Buffer object and initializes it with data copied from the passed-in buffer. While this is still a fully-supported data structure, in most cases using a TypedArray will suffice.

napi_create_date#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] time：自 1970 年 1 月 1 日 UTC 以来的 ECMAScript 时间值（以毫秒为单位）。

  ¥[in] time: ECMAScript time value in milliseconds since 01 January, 1970 UTC.

• [out] result：代表 JavaScript Date 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript Date.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 不遵守闰秒；它们被忽略，因为 ECMAScript 符合 POSIX 时间规范。

¥This API does not observe leap seconds; they are ignored, as ECMAScript aligns with POSIX time specification.

此 API 分配一个 JavaScript Date 对象。

¥This API allocates a JavaScript Date object.

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

¥JavaScript Date objects are described in Section 20.3 of the ECMAScript Language Specification.

napi_create_external#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] data：指向外部数据的原始指针。

  ¥[in] data: Raw pointer to the external data.

• [in] finalize_cb：收集外部值时调用的可选回调。napi_finalize 提供了更多详细信息。

  ¥[in] finalize_cb: Optional callback to call when the external value is being collected. napi_finalize provides more details.

• [in] finalize_hint：在收集期间传递给最终回调的可选提示。

  ¥[in] finalize_hint: Optional hint to pass to the finalize callback during collection.

• [out] result：表示外部值的 napi_value。

  ¥[out] result: A napi_value representing an external value.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API allocates a JavaScript value with external data attached to it. This is used to pass external data through JavaScript code, so it can be retrieved later by native code using napi_get_value_external.

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

¥The API adds a napi_finalize callback which will be called when the JavaScript object just created has been garbage collected.

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

¥The created value is not an object, and therefore does not support additional properties. It is considered a distinct value type: calling napi_typeof() with an external value yields 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) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] external_data：指向 ArrayBuffer 的底层字节缓冲区的指针。

  ¥[in] external_data: Pointer to the underlying byte buffer of the ArrayBuffer.

• [in] byte_length：底层缓冲区的字节长度。

  ¥[in] byte_length: The length in bytes of the underlying buffer.

• [in] finalize_cb：收集 ArrayBuffer 时调用的可选回调。napi_finalize 提供了更多详细信息。

  ¥[in] finalize_cb: Optional callback to call when the ArrayBuffer is being collected. napi_finalize provides more details.

• [in] finalize_hint：在收集期间传递给最终回调的可选提示。

  ¥[in] finalize_hint: Optional hint to pass to the finalize callback during collection.

• [out] result：代表 JavaScript ArrayBuffer 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript ArrayBuffer.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

Node.js 以外的一些运行时已放弃对外部缓冲区的支持。在 Node.js 以外的运行时，此方法可能会返回 napi_no_external_buffers_allowed 以指示不支持外部缓冲区。如本期 electron/issues/35801 中所述，Electron 就是这样一种运行时。

¥Some runtimes other than Node.js have dropped support for external buffers. On runtimes other than Node.js this method may return napi_no_external_buffers_allowed to indicate that external buffers are not supported. One such runtime is Electron as described in this issue electron/issues/35801.

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

¥In order to maintain broadest compatibility with all runtimes you may define NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED in your addon before includes for the node-api headers. Doing so will hide the 2 functions that create external buffers. This will ensure a compilation error occurs if you accidentally use one of these methods.

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

¥This API returns a Node-API value corresponding to a JavaScript ArrayBuffer. The underlying byte buffer of the ArrayBuffer is externally allocated and managed. The caller must ensure that the byte buffer remains valid until the finalize callback is called.

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

¥The API adds a napi_finalize callback which will be called when the JavaScript object just created has been garbage collected.

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

¥JavaScript ArrayBuffers are described in Section 24.1 of the ECMAScript Language Specification.

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) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] length：输入缓冲区的大小（以字节为单位）（应与新缓冲区的大小相同）。

  ¥[in] length: Size in bytes of the input buffer (should be the same as the size of the new buffer).

• [in] data：指向底层缓冲区的原始指针以暴露给 JavaScript。

  ¥[in] data: Raw pointer to the underlying buffer to expose to JavaScript.

• [in] finalize_cb：收集 ArrayBuffer 时调用的可选回调。napi_finalize 提供了更多详细信息。

  ¥[in] finalize_cb: Optional callback to call when the ArrayBuffer is being collected. napi_finalize provides more details.

• [in] finalize_hint：在收集期间传递给最终回调的可选提示。

  ¥[in] finalize_hint: Optional hint to pass to the finalize callback during collection.

• [out] result：一个 napi_value 代表一个 node::Buffer。

  ¥[out] result: A napi_value representing a node::Buffer.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

Node.js 以外的一些运行时已放弃对外部缓冲区的支持。在 Node.js 以外的运行时，此方法可能会返回 napi_no_external_buffers_allowed 以指示不支持外部缓冲区。如本期 electron/issues/35801 中所述，Electron 就是这样一种运行时。

¥Some runtimes other than Node.js have dropped support for external buffers. On runtimes other than Node.js this method may return napi_no_external_buffers_allowed to indicate that external buffers are not supported. One such runtime is Electron as described in this issue electron/issues/35801.

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

¥In order to maintain broadest compatibility with all runtimes you may define NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED in your addon before includes for the node-api headers. Doing so will hide the 2 functions that create external buffers. This will ensure a compilation error occurs if you accidentally use one of these methods.

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

¥This API allocates a node::Buffer object and initializes it with data backed by the passed in buffer. While this is still a fully-supported data structure, in most cases using a TypedArray will suffice.

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

¥The API adds a napi_finalize callback which will be called when the JavaScript object just created has been garbage collected.

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

¥For Node.js >=4 Buffers are Uint8Arrays.

napi_create_object#

napi_status napi_create_object(napi_env env, napi_value* result) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [out] result：代表 JavaScript Object 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript Object.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 分配默认的 JavaScript Object。它相当于在 JavaScript 中执行 new Object()。

¥This API allocates a default JavaScript Object. It is the equivalent of doing new Object() in JavaScript.

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

¥The JavaScript Object type is described in Section 6.1.7 of the ECMAScript Language Specification.

napi_create_symbol#

napi_status napi_create_symbol(napi_env env,
                               napi_value description,
                               napi_value* result) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] description：可选的 napi_value，它指的是要设置为符号描述的 JavaScript string。

  ¥[in] description: Optional napi_value which refers to a JavaScript string to be set as the description for the symbol.

• [out] result：代表 JavaScript symbol 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript symbol.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates a JavaScript symbol value from a UTF8-encoded C string.

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

¥The JavaScript symbol type is described in Section 19.4 of the ECMAScript Language Specification.

node_api_symbol_for#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] utf8description：UTF-8 C 字符串，表示用作符号描述的文本。

  ¥[in] utf8description: UTF-8 C string representing the text to be used as the description for the symbol.

• [in] length：描述字符串的长度（以字节为单位），如果它以 null 结尾则为 NAPI_AUTO_LENGTH。

  ¥[in] length: The length of the description string in bytes, or NAPI_AUTO_LENGTH if it is null-terminated.

• [out] result：代表 JavaScript symbol 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript symbol.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API searches in the global registry for an existing symbol with the given description. If the symbol already exists it will be returned, otherwise a new symbol will be created in the registry.

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

¥The JavaScript symbol type is described in Section 19.4 of the ECMAScript Language Specification.

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) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] type：TypedArray 中元素的标量数据类型。

  ¥[in] type: Scalar datatype of the elements within the TypedArray.

• [in] length：TypedArray 中的元素数。

  ¥[in] length: Number of elements in the TypedArray.

• [in] arraybuffer：ArrayBuffer 是类型化数组的基础。

  ¥[in] arraybuffer: ArrayBuffer underlying the typed array.

• [in] byte_offset：ArrayBuffer 中开始投影 TypedArray 的字节偏移量。

  ¥[in] byte_offset: The byte offset within the ArrayBuffer from which to start projecting the TypedArray.

• [out] result：代表 JavaScript TypedArray 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript TypedArray.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates a JavaScript TypedArray object over an existing ArrayBuffer. TypedArray objects provide an array-like view over an underlying data buffer where each element has the same underlying binary scalar datatype.

要求 (length * size_of_element) + byte_offset 应该 <= 传入数组的大小（以字节为单位）。如果不是，则引发 RangeError 异常。

¥It's required that (length * size_of_element) + byte_offset should be <= the size in bytes of the array passed in. If not, a RangeError exception is raised.

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

¥JavaScript TypedArray objects are described in Section 22.2 of the ECMAScript Language Specification.

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) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] length：DataView 中的元素数。

  ¥[in] length: Number of elements in the DataView.

• [in] arraybuffer：ArrayBuffer 是 DataView 的基础。

  ¥[in] arraybuffer: ArrayBuffer underlying the DataView.

• [in] byte_offset：ArrayBuffer 中开始投影 DataView 的字节偏移量。

  ¥[in] byte_offset: The byte offset within the ArrayBuffer from which to start projecting the DataView.

• [out] result：代表 JavaScript DataView 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript DataView.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates a JavaScript DataView object over an existing ArrayBuffer. DataView objects provide an array-like view over an underlying data buffer, but one which allows items of different size and type in the ArrayBuffer.

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

¥It is required that byte_length + byte_offset is less than or equal to the size in bytes of the array passed in. If not, a RangeError exception is raised.

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

¥JavaScript DataView objects are described in Section 24.3 of the ECMAScript Language Specification.

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

¥Functions to convert from C types to Node-API

napi_create_int32#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要在 JavaScript 中表示的整数值。

  ¥[in] value: Integer value to be represented in JavaScript.

• [out] result：代表 JavaScript number 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript number.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API is used to convert from the C int32_t type to the JavaScript number type.

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

¥The JavaScript number type is described in Section 6.1.6 of the ECMAScript Language Specification.

napi_create_uint32#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要在 JavaScript 中表示的无符号整数值。

  ¥[in] value: Unsigned integer value to be represented in JavaScript.

• [out] result：代表 JavaScript number 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript number.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API is used to convert from the C uint32_t type to the JavaScript number type.

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

¥The JavaScript number type is described in Section 6.1.6 of the ECMAScript Language Specification.

napi_create_int64#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要在 JavaScript 中表示的整数值。

  ¥[in] value: Integer value to be represented in JavaScript.

• [out] result：代表 JavaScript number 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript number.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API is used to convert from the C int64_t type to the JavaScript number type.

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

¥The JavaScript number type is described in Section 6.1.6 of the ECMAScript Language Specification. Note the complete range of int64_t cannot be represented with full precision in JavaScript. Integer values outside the range of Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) will lose precision.

napi_create_double#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要在 JavaScript 中表示的双精度值。

  ¥[in] value: Double-precision value to be represented in JavaScript.

• [out] result：代表 JavaScript number 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript number.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API is used to convert from the C double type to the JavaScript number type.

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

¥The JavaScript number type is described in Section 6.1.6 of the ECMAScript Language Specification.

napi_create_bigint_int64#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要在 JavaScript 中表示的整数值。

  ¥[in] value: Integer value to be represented in JavaScript.

• [out] result：代表 JavaScript BigInt 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript BigInt.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API converts the C int64_t type to the JavaScript BigInt type.

napi_create_bigint_uint64#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要在 JavaScript 中表示的无符号整数值。

  ¥[in] value: Unsigned integer value to be represented in JavaScript.

• [out] result：代表 JavaScript BigInt 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript BigInt.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API converts the C uint64_t type to the JavaScript BigInt type.

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); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] sign_bit：确定生成的 BigInt 是正数还是负数。

  ¥[in] sign_bit: Determines if the resulting BigInt will be positive or negative.

• [in] word_count：words 数组的长度。

  ¥[in] word_count: The length of the words array.

• [in] words：uint64_t little-endian 64 位字数组。

  ¥[in] words: An array of uint64_t little-endian 64-bit words.

• [out] result：代表 JavaScript BigInt 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript BigInt.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API converts an array of unsigned 64-bit words into a single BigInt value.

生成的 BigInt 计算如下：(–1)^sign_bit (words[0] × (2⁶⁴)⁰ + words[1] × (2⁶⁴)¹ + …)

¥The resulting BigInt is calculated as: (–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); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] str：表示 ISO-8859-1 编码字符串的字符缓冲区。

  ¥[in] str: Character buffer representing an ISO-8859-1-encoded string.

• [in] length：字符串的长度（以字节为单位），如果它以 null 结尾则为 NAPI_AUTO_LENGTH。

  ¥[in] length: The length of the string in bytes, or NAPI_AUTO_LENGTH if it is null-terminated.

• [out] result：代表 JavaScript string 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript string.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates a JavaScript string value from an ISO-8859-1-encoded C string. The native string is copied.

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

¥The JavaScript string type is described in Section 6.1.4 of the ECMAScript Language Specification.

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); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] str：表示 ISO-8859-1 编码字符串的字符缓冲区。

  ¥[in] str: Character buffer representing an ISO-8859-1-encoded string.

• [in] length：字符串的长度（以字节为单位），如果它以 null 结尾则为 NAPI_AUTO_LENGTH。

  ¥[in] length: The length of the string in bytes, or NAPI_AUTO_LENGTH if it is null-terminated.

• [in] finalize_callback：收集字符串时调用的函数。该函数将使用以下参数调用：

  ¥[in] finalize_callback: The function to call when the string is being collected. The function will be called with the following parameters:

  • [in] env：加载项运行的环境。如果字符串是作为工作线程或主 Node.js 实例终止的一部分而被收集的，则该值可能为 null。

    ¥[in] env: The environment in which the add-on is running. This value may be null if the string is being collected as part of the termination of the worker or the main Node.js instance.

  • [in] data：这是作为 void* 指针的值 str。

    ¥[in] data: This is the value str as a void* pointer.

  • [in] finalize_hint：这是赋予 API 的值 finalize_hint。napi_finalize 提供了更多详细信息。该参数是可选的。传递 null 值意味着在收集相应的 JavaScript 字符串时不需要通知加载项。

    ¥[in] finalize_hint: This is the value finalize_hint that was given to the API. napi_finalize provides more details. This parameter is optional. Passing a null value means that the add-on doesn't need to be notified when the corresponding JavaScript string is collected.

• [in] finalize_hint：在收集期间传递给最终回调的可选提示。

  ¥[in] finalize_hint: Optional hint to pass to the finalize callback during collection.

• [out] result：代表 JavaScript string 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript string.

• [out] copied：字符串是否被复制。如果是，则终结器将已被调用来销毁 str。

  ¥[out] copied: Whether the string was copied. If it was, the finalizer will already have been invoked to destroy str.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates a JavaScript string value from an ISO-8859-1-encoded C string. The native string may not be copied and must thus exist for the entire life cycle of the JavaScript value.

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

¥The JavaScript string type is described in Section 6.1.4 of the ECMAScript Language Specification.

napi_create_string_utf16#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] str：表示 UTF16-LE 编码字符串的字符缓冲区。

  ¥[in] str: Character buffer representing a UTF16-LE-encoded string.

• [in] length：以两字节代码单元表示的字符串长度，如果它以 null 终止，则为 NAPI_AUTO_LENGTH。

  ¥[in] length: The length of the string in two-byte code units, or NAPI_AUTO_LENGTH if it is null-terminated.

• [out] result：代表 JavaScript string 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript string.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates a JavaScript string value from a UTF16-LE-encoded C string. The native string is copied.

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

¥The JavaScript string type is described in Section 6.1.4 of the ECMAScript Language Specification.

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); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] str：表示 UTF16-LE 编码字符串的字符缓冲区。

  ¥[in] str: Character buffer representing a UTF16-LE-encoded string.

• [in] length：以两字节代码单元表示的字符串长度，如果它以 null 终止，则为 NAPI_AUTO_LENGTH。

  ¥[in] length: The length of the string in two-byte code units, or NAPI_AUTO_LENGTH if it is null-terminated.

• [in] finalize_callback：收集字符串时调用的函数。该函数将使用以下参数调用：

  ¥[in] finalize_callback: The function to call when the string is being collected. The function will be called with the following parameters:

  • [in] env：加载项运行的环境。如果字符串是作为工作线程或主 Node.js 实例终止的一部分而被收集的，则该值可能为 null。

    ¥[in] env: The environment in which the add-on is running. This value may be null if the string is being collected as part of the termination of the worker or the main Node.js instance.

  • [in] data：这是作为 void* 指针的值 str。

    ¥[in] data: This is the value str as a void* pointer.

  • [in] finalize_hint：这是赋予 API 的值 finalize_hint。napi_finalize 提供了更多详细信息。该参数是可选的。传递 null 值意味着在收集相应的 JavaScript 字符串时不需要通知加载项。

    ¥[in] finalize_hint: This is the value finalize_hint that was given to the API. napi_finalize provides more details. This parameter is optional. Passing a null value means that the add-on doesn't need to be notified when the corresponding JavaScript string is collected.

• [in] finalize_hint：在收集期间传递给最终回调的可选提示。

  ¥[in] finalize_hint: Optional hint to pass to the finalize callback during collection.

• [out] result：代表 JavaScript string 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript string.

• [out] copied：字符串是否被复制。如果是，则终结器将已被调用来销毁 str。

  ¥[out] copied: Whether the string was copied. If it was, the finalizer will already have been invoked to destroy str.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates a JavaScript string value from a UTF16-LE-encoded C string. The native string may not be copied and must thus exist for the entire life cycle of the JavaScript value.

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

¥The JavaScript string type is described in Section 6.1.4 of the ECMAScript Language Specification.

napi_create_string_utf8#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] str：表示 UTF8 编码字符串的字符缓冲区。

  ¥[in] str: Character buffer representing a UTF8-encoded string.

• [in] length：字符串的长度（以字节为单位），如果它以 null 结尾则为 NAPI_AUTO_LENGTH。

  ¥[in] length: The length of the string in bytes, or NAPI_AUTO_LENGTH if it is null-terminated.

• [out] result：代表 JavaScript string 的 napi_value。

  ¥[out] result: A napi_value representing a JavaScript string.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates a JavaScript string value from a UTF8-encoded C string. The native string is copied.

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

¥The JavaScript string type is described in Section 6.1.4 of the ECMAScript Language Specification.

用于创建优化属性键的函数#

¥Functions to create optimized property keys

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

¥Many JavaScript engines including V8 use internalized strings as keys to set and get property values. They typically use a hash table to create and lookup such strings. While it adds some cost per key creation, it improves the performance after that by enabling comparison of string pointers instead of the whole strings.

如果打算将新的 JavaScript 字符串用作属性键，那么对于某些 JavaScript 引擎来说，使用本节中的函数会更有效率。否则，请使用 napi_create_string_utf8 或 node_api_create_external_string_utf8 系列函数，因为使用属性键创建方法创建/存储字符串可能会产生额外的开销。

¥If a new JavaScript string is intended to be used as a property key, then for some JavaScript engines it will be more efficient to use the functions in this section. Otherwise, use the napi_create_string_utf8 or node_api_create_external_string_utf8 series functions as there may be additional overhead in creating/storing strings with the property key creation methods.

node_api_create_property_key_latin1#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] str：表示 ISO-8859-1 编码字符串的字符缓冲区。

  ¥[in] str: Character buffer representing an ISO-8859-1-encoded string.

• [in] length：字符串的长度（以字节为单位），如果它以 null 结尾则为 NAPI_AUTO_LENGTH。

  ¥[in] length: The length of the string in bytes, or NAPI_AUTO_LENGTH if it is null-terminated.

• [out] result：napi_value 代表优化的 JavaScript string，用作对象的属性键。

  ¥[out] result: A napi_value representing an optimized JavaScript string to be used as a property key for objects.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates an optimized JavaScript string value from an ISO-8859-1-encoded C string to be used as a property key for objects. The native string is copied. In contrast with napi_create_string_latin1, subsequent calls to this function with the same str pointer may benefit from a speedup in the creation of the requested napi_value, depending on the engine.

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

¥The JavaScript string type is described in Section 6.1.4 of the ECMAScript Language Specification.

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); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] str：表示 UTF16-LE 编码字符串的字符缓冲区。

  ¥[in] str: Character buffer representing a UTF16-LE-encoded string.

• [in] length：以两字节代码单元表示的字符串长度，如果它以 null 终止，则为 NAPI_AUTO_LENGTH。

  ¥[in] length: The length of the string in two-byte code units, or NAPI_AUTO_LENGTH if it is null-terminated.

• [out] result：napi_value 代表优化的 JavaScript string，用作对象的属性键。

  ¥[out] result: A napi_value representing an optimized JavaScript string to be used as a property key for objects.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates an optimized JavaScript string value from a UTF16-LE-encoded C string to be used as a property key for objects. The native string is copied.

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

¥The JavaScript string type is described in Section 6.1.4 of the ECMAScript Language Specification.

node_api_create_property_key_utf8#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] str：表示 UTF8 编码字符串的字符缓冲区。

  ¥[in] str: Character buffer representing a UTF8-encoded string.

• [in] length：以两字节代码单元表示的字符串长度，如果它以 null 终止，则为 NAPI_AUTO_LENGTH。

  ¥[in] length: The length of the string in two-byte code units, or NAPI_AUTO_LENGTH if it is null-terminated.

• [out] result：napi_value 代表优化的 JavaScript string，用作对象的属性键。

  ¥[out] result: A napi_value representing an optimized JavaScript string to be used as a property key for objects.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API creates an optimized JavaScript string value from a UTF8-encoded C string to be used as a property key for objects. The native string is copied.

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

¥The JavaScript string type is described in Section 6.1.4 of the ECMAScript Language Specification.

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

¥Functions to convert from Node-API to C types

napi_get_array_length#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表查询长度的 JavaScript Array。

  ¥[in] value: napi_value representing the JavaScript Array whose length is being queried.

• [out] result：uint32 代表数组的长度。

  ¥[out] result: uint32 representing length of the array.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 返回数组的长度。

¥This API returns the length of an array.

Array 长度在 ECMAScript 语言规范的 第 22.1.4.1 节 中描述。

¥Array length is described in Section 22.1.4.1 of the ECMAScript Language Specification.

napi_get_arraybuffer_info#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] arraybuffer：napi_value 代表被查询的 ArrayBuffer。

  ¥[in] arraybuffer: napi_value representing the ArrayBuffer being queried.

• [out] data：ArrayBuffer 的底层数据缓冲区。如果 byte_length 是 0，则这可能是 NULL 或任何其他指针值。

  ¥[out] data: The underlying data buffer of the ArrayBuffer. If byte_length is 0, this may be NULL or any other pointer value.

• [out] byte_length：底层数据缓冲区的字节长度。

  ¥[out] byte_length: Length in bytes of the underlying data buffer.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API is used to retrieve the underlying data buffer of an ArrayBuffer and its length.

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

¥WARNING: Use caution while using this API. The lifetime of the underlying data buffer is managed by the ArrayBuffer even after it's returned. A possible safe way to use this API is in conjunction with napi_create_reference, which can be used to guarantee control over the lifetime of the ArrayBuffer. It's also safe to use the returned data buffer within the same callback as long as there are no calls to other APIs that might trigger a GC.

napi_get_buffer_info#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表正在查询的 node::Buffer 或 Uint8Array。

  ¥[in] value: napi_value representing the node::Buffer or Uint8Array being queried.

• [out] data：node::Buffer 或 Uint8Array 的底层数据缓冲区。如果长度是 0，这可能是 NULL 或任何其他指针值。

  ¥[out] data: The underlying data buffer of the node::Buffer or Uint8Array. If length is 0, this may be NULL or any other pointer value.

• [out] length：底层数据缓冲区的字节长度。

  ¥[out] length: Length in bytes of the underlying data buffer.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此方法返回与 napi_get_typedarray_info 相同的 data 和 byte_length。napi_get_typedarray_info 也接受 node::Buffer （Uint8Array）作为值。

¥This method returns the identical data and byte_length as napi_get_typedarray_info. And napi_get_typedarray_info accepts a node::Buffer (a Uint8Array) as the value too.

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

¥This API is used to retrieve the underlying data buffer of a node::Buffer and its length.

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

¥Warning: Use caution while using this API since the underlying data buffer's lifetime is not guaranteed if it's managed by the VM.

napi_get_prototype#

napi_status napi_get_prototype(napi_env env,
                               napi_value object,
                               napi_value* result) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] object：napi_value 表示要返回其原型的 JavaScript Object。这将返回 Object.getPrototypeOf 的等价物（与函数的 prototype 属性不同）。

  ¥[in] object: napi_value representing JavaScript Object whose prototype to return. This returns the equivalent of Object.getPrototypeOf (which is not the same as the function's prototype property).

• [out] result：napi_value 表示给定对象的原型。

  ¥[out] result: napi_value representing prototype of the given object.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] typedarray：napi_value 表示要查询其属性的 TypedArray。

  ¥[in] typedarray: napi_value representing the TypedArray whose properties to query.

• [out] type：TypedArray 中元素的标量数据类型。

  ¥[out] type: Scalar datatype of the elements within the TypedArray.

• [out] length：TypedArray 中的元素数。

  ¥[out] length: The number of elements in the TypedArray.

• [out] data：TypedArray 底层的数据缓冲区由 byte_offset 值调整，使其指向 TypedArray 中的第一个元素。如果数组的长度是 0，这可能是 NULL 或任何其他指针值。

  ¥[out] data: The data buffer underlying the TypedArray adjusted by the byte_offset value so that it points to the first element in the TypedArray. If the length of the array is 0, this may be NULL or any other pointer value.

• [out] arraybuffer：TypedArray 下的 ArrayBuffer。

  ¥[out] arraybuffer: The ArrayBuffer underlying the TypedArray.

• [out] byte_offset：数组的第一个元素所在的基础原生数组中的字节偏移量。data 参数的值已经过调整，因此 data 指向数组中的第一个元素。因此，原生数组的第一个字节将位于 data - byte_offset。

  ¥[out] byte_offset: The byte offset within the underlying native array at which the first element of the arrays is located. The value for the data parameter has already been adjusted so that data points to the first element in the array. Therefore, the first byte of the native array would be at data - byte_offset.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API returns various properties of a typed array.

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

¥Any of the out parameters may be NULL if that property is unneeded.

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

¥Warning: Use caution while using this API since the underlying data buffer is managed by the 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) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] dataview：napi_value 表示要查询其属性的 DataView。

  ¥[in] dataview: napi_value representing the DataView whose properties to query.

• [out] byte_length：DataView 中的字节数。

  ¥[out] byte_length: Number of bytes in the DataView.

• [out] data：DataView 下的数据缓冲区。如果 byte_length 是 0，则这可能是 NULL 或任何其他指针值。

  ¥[out] data: The data buffer underlying the DataView. If byte_length is 0, this may be NULL or any other pointer value.

• [out] arraybuffer：ArrayBuffer 是 DataView 的基础。

  ¥[out] arraybuffer: ArrayBuffer underlying the DataView.

• [out] byte_offset：开始投影 DataView 的数据缓冲区中的字节偏移量。

  ¥[out] byte_offset: The byte offset within the data buffer from which to start projecting the DataView.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥Any of the out parameters may be NULL if that property is unneeded.

此 API 返回 DataView 的各种属性。

¥This API returns various properties of a DataView.

napi_get_date_value#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表一个 JavaScript Date。

  ¥[in] value: napi_value representing a JavaScript Date.

• [out] result：作为 double 的时间值表示为自 1970 年 1 月 1 日 UTC 午夜以来的毫秒数。

  ¥[out] result: Time value as a double represented as milliseconds since midnight at the beginning of 01 January, 1970 UTC.

此 API 不遵守闰秒；它们被忽略，因为 ECMAScript 符合 POSIX 时间规范。

¥This API does not observe leap seconds; they are ignored, as ECMAScript aligns with POSIX time specification.

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

¥Returns napi_ok if the API succeeded. If a non-date napi_value is passed in it returns napi_date_expected.

此 API 返回给定 JavaScript Date 的时间值的 C 双精度基础类型。

¥This API returns the C double primitive of time value for the given JavaScript Date.

napi_get_value_bool#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript Boolean。

  ¥[in] value: napi_value representing JavaScript Boolean.

• [out] result：给定 JavaScript Boolean 的 C 布尔基础类型等价物。

  ¥[out] result: C boolean primitive equivalent of the given JavaScript Boolean.

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

¥Returns napi_ok if the API succeeded. If a non-boolean napi_value is passed in it returns napi_boolean_expected.

此 API 返回给定 JavaScript Boolean 的 C 布尔基础类型等价物。

¥This API returns the C boolean primitive equivalent of the given JavaScript Boolean.

napi_get_value_double#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript number。

  ¥[in] value: napi_value representing JavaScript number.

• [out] result：给定的 JavaScript number 的 C 双精度基础类型等价物。

  ¥[out] result: C double primitive equivalent of the given JavaScript number.

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

¥Returns napi_ok if the API succeeded. If a non-number napi_value is passed in it returns napi_number_expected.

此 API 返回给定 JavaScript number 的 C 双精度基础类型等价物。

¥This API returns the C double primitive equivalent of the given JavaScript number.

napi_get_value_bigint_int64#

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

• [in] env：调用 API 的环境

  ¥[in] env: The environment that the API is invoked under

• [in] value：napi_value 代表 JavaScript BigInt。

  ¥[in] value: napi_value representing JavaScript BigInt.

• [out] result：给定的 JavaScript BigInt 的 C int64_t 基础类型等价物。

  ¥[out] result: C int64_t primitive equivalent of the given JavaScript BigInt.

• [out] lossless：指示 BigInt 值是否已无损转换。

  ¥[out] lossless: Indicates whether the BigInt value was converted losslessly.

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

¥Returns napi_ok if the API succeeded. If a non-BigInt is passed in it returns napi_bigint_expected.

此 API 返回给定 JavaScript BigInt 的 C int64_t 基础类型等价物。如果需要，它将截断该值，将 lossless 设置为 false。

¥This API returns the C int64_t primitive equivalent of the given JavaScript BigInt. If needed it will truncate the value, setting lossless to false.

napi_get_value_bigint_uint64#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript BigInt。

  ¥[in] value: napi_value representing JavaScript BigInt.

• [out] result：给定的 JavaScript BigInt 的 C uint64_t 基础类型等价物。

  ¥[out] result: C uint64_t primitive equivalent of the given JavaScript BigInt.

• [out] lossless：指示 BigInt 值是否已无损转换。

  ¥[out] lossless: Indicates whether the BigInt value was converted losslessly.

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

¥Returns napi_ok if the API succeeded. If a non-BigInt is passed in it returns napi_bigint_expected.

此 API 返回给定 JavaScript BigInt 的 C uint64_t 基础类型等价物。如果需要，它将截断该值，将 lossless 设置为 false。

¥This API returns the C uint64_t primitive equivalent of the given JavaScript BigInt. If needed it will truncate the value, setting lossless to 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); 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript BigInt。

  ¥[in] value: napi_value representing JavaScript BigInt.

• [out] sign_bit：表示 JavaScript BigInt 是正数还是负数的整数。

  ¥[out] sign_bit: Integer representing if the JavaScript BigInt is positive or negative.

• [in/out] word_count：必须初始化为 words 数组的长度。返回时，它将被设置为存储此 BigInt 所需的实际字数。

  ¥[in/out] word_count: Must be initialized to the length of the words array. Upon return, it will be set to the actual number of words that would be needed to store this BigInt.

• [out] words：指向预分配的 64 位字数组的指针。

  ¥[out] words: Pointer to a pre-allocated 64-bit word array.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API converts a single BigInt value into a sign bit, 64-bit little-endian array, and the number of elements in the array. sign_bit and words may be both set to NULL, in order to get only word_count.

napi_get_value_external#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript 外部值。

  ¥[in] value: napi_value representing JavaScript external value.

• [out] result：指向由 JavaScript 外部值封装的数据的指针。

  ¥[out] result: Pointer to the data wrapped by the JavaScript external value.

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

¥Returns napi_ok if the API succeeded. If a non-external napi_value is passed in it returns napi_invalid_arg.

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

¥This API retrieves the external data pointer that was previously passed to napi_create_external().

napi_get_value_int32#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript number。

  ¥[in] value: napi_value representing JavaScript number.

• [out] result：给定的 JavaScript number 的 C int32 基础类型等价物。

  ¥[out] result: C int32 primitive equivalent of the given JavaScript number.

如果 API 成功，则返回 napi_ok。如果在 napi_number_expected 中传递了非数字 napi_value。

¥Returns napi_ok if the API succeeded. If a non-number napi_value is passed in napi_number_expected.

此 API 返回给定 JavaScript number 的 C int32 基础类型等价物。

¥This API returns the C int32 primitive equivalent of the given JavaScript number.

如果该数字超出 32 位整数的范围，则结果将被截断为与底部 32 位等效的值。如果该值 > 2³¹，这可能会导致较大的正数变成负数 - 1.

¥If the number exceeds the range of the 32 bit integer, then the result is truncated to the equivalent of the bottom 32 bits. This can result in a large positive number becoming a negative number if the value is > 2³¹ - 1.

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

¥Non-finite number values (NaN, +Infinity, or -Infinity) set the result to zero.

napi_get_value_int64#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript number。

  ¥[in] value: napi_value representing JavaScript number.

• [out] result：给定的 JavaScript number 的 C int64 基础类型等价物。

  ¥[out] result: C int64 primitive equivalent of the given JavaScript number.

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

¥Returns napi_ok if the API succeeded. If a non-number napi_value is passed in it returns napi_number_expected.

此 API 返回给定 JavaScript number 的 C int64 基础类型等价物。

¥This API returns the C int64 primitive equivalent of the given JavaScript number.

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

¥number values outside the range of Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) will lose precision.

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

¥Non-finite number values (NaN, +Infinity, or -Infinity) set the result to zero.

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) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript 字符串。

  ¥[in] value: napi_value representing JavaScript string.

• [in] buf：写入 ISO-8859-1 编码字符串的缓冲区。如果传入 NULL，则在 result 中返回以字节为单位的字符串长度，不包括空终止符。

  ¥[in] buf: Buffer to write the ISO-8859-1-encoded string into. If NULL is passed in, the length of the string in bytes and excluding the null terminator is returned in result.

• [in] bufsize：目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以 null 终止。

  ¥[in] bufsize: Size of the destination buffer. When this value is insufficient, the returned string is truncated and null-terminated.

• [out] result：复制到缓冲区中的字节数，不包括空终止符。

  ¥[out] result: Number of bytes copied into the buffer, excluding the null terminator.

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

¥Returns napi_ok if the API succeeded. If a non-string napi_value is passed in it returns napi_string_expected.

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

¥This API returns the ISO-8859-1-encoded string corresponding the value passed in.

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) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript 字符串。

  ¥[in] value: napi_value representing JavaScript string.

• [in] buf：将 UTF8 编码的字符串写入的缓冲区。如果传入 NULL，则在 result 中返回以字节为单位的字符串长度，不包括空终止符。

  ¥[in] buf: Buffer to write the UTF8-encoded string into. If NULL is passed in, the length of the string in bytes and excluding the null terminator is returned in result.

• [in] bufsize：目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以 null 终止。

  ¥[in] bufsize: Size of the destination buffer. When this value is insufficient, the returned string is truncated and null-terminated.

• [out] result：复制到缓冲区中的字节数，不包括空终止符。

  ¥[out] result: Number of bytes copied into the buffer, excluding the null terminator.

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

¥Returns napi_ok if the API succeeded. If a non-string napi_value is passed in it returns napi_string_expected.

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

¥This API returns the UTF8-encoded string corresponding the value passed in.

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) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript 字符串。

  ¥[in] value: napi_value representing JavaScript string.

• [in] buf：将 UTF16-LE 编码字符串写入的缓冲区。如果传入 NULL，则返回字符串的 2 字节代码单元长度，不包括空终止符。

  ¥[in] buf: Buffer to write the UTF16-LE-encoded string into. If NULL is passed in, the length of the string in 2-byte code units and excluding the null terminator is returned.

• [in] bufsize：目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以 null 终止。

  ¥[in] bufsize: Size of the destination buffer. When this value is insufficient, the returned string is truncated and null-terminated.

• [out] result：复制到缓冲区中的 2 字节代码单元数，不包括空终止符。

  ¥[out] result: Number of 2-byte code units copied into the buffer, excluding the null terminator.

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

¥Returns napi_ok if the API succeeded. If a non-string napi_value is passed in it returns napi_string_expected.

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

¥This API returns the UTF16-encoded string corresponding the value passed in.

napi_get_value_uint32#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：napi_value 代表 JavaScript number。

  ¥[in] value: napi_value representing JavaScript number.

• [out] result：将给定的 napi_value 等效为 uint32_t 的 C 基础类型。

  ¥[out] result: C primitive equivalent of the given napi_value as a uint32_t.

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

¥Returns napi_ok if the API succeeded. If a non-number napi_value is passed in it returns napi_number_expected.

此 API 将给定 napi_value 的 C 基础类型等效项返回为 uint32_t。

¥This API returns the C primitive equivalent of the given napi_value as a uint32_t.

获取全局实例的函数#

¥Functions to get global instances

napi_get_boolean#

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

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要检索的布尔值。

  ¥[in] value: The value of the boolean to retrieve.

• [out] result：napi_value 表示要检索的 JavaScript Boolean 单例。

  ¥[out] result: napi_value representing JavaScript Boolean singleton to retrieve.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API is used to return the JavaScript singleton object that is used to represent the given boolean value.

napi_get_global#

napi_status napi_get_global(napi_env env, napi_value* result) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [out] result：napi_value 代表 JavaScript global 对象。

  ¥[out] result: napi_value representing JavaScript global object.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 返回 global 对象。

¥This API returns the global object.

napi_get_null#

napi_status napi_get_null(napi_env env, napi_value* result) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [out] result：napi_value 代表 JavaScript null 对象。

  ¥[out] result: napi_value representing JavaScript null object.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 返回 null 对象。

¥This API returns the null object.

napi_get_undefined#

napi_status napi_get_undefined(napi_env env, napi_value* result) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [out] result：napi_value 代表 JavaScript Undefined 值。

  ¥[out] result: napi_value representing JavaScript Undefined value.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

此 API 返回 Undefined 对象。

¥This API returns the Undefined object.

使用 JavaScript 值和抽象操作#

¥Working with JavaScript values and abstract operations

Node-API 公开了一组 API 来对 JavaScript 值执行一些抽象操作。其中一些操作记录在 ECMAScript 语言规范 的 第 7 节 下。

¥Node-API exposes a set of APIs to perform some abstract operations on JavaScript values. Some of these operations are documented under Section 7 of the ECMAScript Language Specification.

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

¥These APIs support doing one of the following:

1. 将 JavaScript 值强制转换为特定的 JavaScript 类型（例如 number 或 string）。

   ¥Coerce JavaScript values to specific JavaScript types (such as number or string).

2. 检查 JavaScript 值的类型。

   ¥Check the type of a JavaScript value.

3. 检查两个 JavaScript 值之间的相等性。

   ¥Check for equality between two JavaScript values.

napi_coerce_to_bool#

napi_status napi_coerce_to_bool(napi_env env,
                                napi_value value,
                                napi_value* result) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要强制转换的 JavaScript 值。

  ¥[in] value: The JavaScript value to coerce.

• [out] result：napi_value 代表强制的 JavaScript Boolean。

  ¥[out] result: napi_value representing the coerced JavaScript Boolean.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

该 API 实现了 ECMAScript 语言规范的 第 7.1.2 节 中定义的抽象操作 ToBoolean()。

¥This API implements the abstract operation ToBoolean() as defined in Section 7.1.2 of the ECMAScript Language Specification.

napi_coerce_to_number#

napi_status napi_coerce_to_number(napi_env env,
                                  napi_value value,
                                  napi_value* result) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要强制转换的 JavaScript 值。

  ¥[in] value: The JavaScript value to coerce.

• [out] result：napi_value 代表强制的 JavaScript number。

  ¥[out] result: napi_value representing the coerced JavaScript number.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

¥This API implements the abstract operation ToNumber() as defined in Section 7.1.3 of the ECMAScript Language Specification. This function potentially runs JS code if the passed-in value is an object.

napi_coerce_to_object#

napi_status napi_coerce_to_object(napi_env env,
                                  napi_value value,
                                  napi_value* result) 拷贝

• [in] env：调用 API 的环境。

  ¥[in] env: The environment that the API is invoked under.

• [in] value：要强制转换的 JavaScript 值。

  ¥[in] value: The JavaScript value to coerce.

• [out] result：napi_value 代表强制的 JavaScript Object。

  ¥[out] result: napi_value representing the coerced JavaScript Object.

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

该 API 实现了 ECMAScript 语言规范的 第 7.1.13 节 中定义的抽象操作 ToObject()。

¥This API implements the abstract operation ToObject() as defined in Section 7.1.13 of the ECMAScript Language Specification.

napi_coerce_to_string#

napi_status napi_coerce_to_string(napi_env env,
                                  napi_value value,
                                  napi_value* result) 拷贝