Node-API
Node-API（以前称为 N-API）是用于构建原生 Addon 的 API。它独立于底层的 JavaScript 运行时（例如，V8），并作为 Node.js 本身的一部分进行维护。此 API 将在 Node.js 的不同版本中保持应用程序二进制接口 (ABI) 稳定性。它旨在使 Addon 免受底层 JavaScript 引擎更改的影响，并允许为一个主要版本编译的模块在以后的 Node.js 主要版本上运行而无需重新编译。ABI 稳定性 指南提供了更深入的解释。
Addon 的构建/打包方法/工具与标题为 C++ Addon 的部分中概述的方法/工具相同。唯一的区别是原生代码使用的 API 集。它不使用 V8 或 Node.js 原生抽象 API，而是使用 Node-API 中提供的函数。
Node-API 公开的 API 通常用于创建和操作 JavaScript 值。概念和操作通常映射到 ECMA-262 语言规范中指定的思想。API 具有以下属性：
- 所有 Node-API 调用都返回
napi_status类型的状态代码。此状态指示 API 调用成功还是失败。 - API 的返回值通过输出参数传递。
- 所有 JavaScript 值都隐藏在一个名为
napi_value的不透明类型后面。 - 如果是错误状态代码，则可以使用
napi_get_last_error_info获取其他信息。更多信息可以在错误处理部分 错误处理 中找到。
Node-API 是一个 C API，它确保了跨 Node.js 版本和不同编译器级别的 ABI 稳定性。C++ API 可能更容易使用。为了支持使用 C++，该项目维护了一个名为 node-addon-api 的 C++ 包装器模块。此包装器提供了一个可内联的 C++ API。使用 node-addon-api 构建的二进制文件将依赖于 Node.js 导出的基于 Node-API C 的函数的符号。node-addon-api 是编写调用 Node-API 代码的更有效方法。例如，以下 node-addon-api 代码。第一部分显示 node-addon-api 代码，第二部分显示 Addon 中实际使用的代码。
Object obj = Object::New(env);
obj["foo"] = String::New(env, "bar");napi_status status;
napi_value object, string;
status = napi_create_object(env, &object);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}
status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}
status = napi_set_named_property(env, object, "foo", string);
if (status != napi_ok) {
napi_throw_error(env, ...);
return;
}最终结果是 Addon 只使用导出的 C API。因此，它仍然可以获得 C API 提供的 ABI 稳定性的好处。
当使用 node-addon-api 代替 C API 时，请从 node-addon-api 的 API 文档 开始。
Node-API 资源 为刚开始使用 Node-API 和 node-addon-api 的开发人员提供了极好的入门指南和技巧。可以在 Node-API 媒体 页面上找到其他媒体资源。
ABI 稳定性的影响
尽管 Node-API 提供了 ABI 稳定性保证，但 Node.js 的其他部分并未提供此保证，并且从附加组件中使用的任何外部库也可能无法提供。特别是，以下任何 API 都不提供跨主要版本的 ABI 稳定性保证：
- 通过任何方式提供的 Node.js C++ API
- 也包含在 Node.js 中并可通过 提供的 libuv API
- 可通过 提供的 V8 API
因此，为了使附加组件在 Node.js 主要版本之间保持 ABI 兼容性，它必须专门使用 Node-API，方法是限制自身仅使用
#include <node_api.h>并检查其使用的所有外部库，以确保外部库提供的 ABI 稳定性保证与 Node-API 类似。
构建
与用 JavaScript 编写的模块不同，使用 Node-API 开发和部署 Node.js 原生附加组件需要一组额外的工具。除了开发 Node.js 所需的基本工具外，原生附加组件开发者还需要一个可以将 C 和 C++ 代码编译成二进制文件的工具链。此外，根据原生附加组件的部署方式，原生附加组件的用户也需要安装 C/C++ 工具链。
对于 Linux 开发者，必要的 C/C++ 工具链软件包很容易获得。GCC 在 Node.js 社区中被广泛用于跨各种平台构建和测试。对于许多开发者来说，LLVM 编译器基础设施也是一个不错的选择。
对于 Mac 开发者，Xcode 提供所有必需的编译器工具。但是，不必安装整个 Xcode IDE。以下命令安装必要的工具链：
xcode-select --install对于 Windows 开发者，Visual Studio 提供所有必需的编译器工具。但是，不必安装整个 Visual Studio IDE。以下命令安装必要的工具链：
npm install --global windows-build-tools以下部分描述了开发和部署 Node.js 原生附加组件的其他可用工具。
构建工具
此处列出的两种工具都需要原生插件的用户安装 C/C++ 工具链才能成功安装原生插件。
node-gyp
node-gyp 是一个基于 Google 的 GYP 工具的 gyp-next 分支构建的构建系统，并与 npm 捆绑在一起。GYP，因此 node-gyp，需要安装 Python。
历史上，node-gyp 一直是构建原生插件的首选工具。它具有广泛的采用率和文档。但是，一些开发者在 node-gyp 中遇到了限制。
CMake.js
对于已经使用 CMake 的项目或受 node-gyp 限制影响的开发者来说，CMake.js 是一个不错的选择。build_with_cmake 是一个基于 CMake 的原生插件项目的示例。
上传预编译二进制文件
这里列出的三个工具允许原生插件开发者和维护者创建并上传二进制文件到公共或私有服务器。这些工具通常与 CI/CD 构建系统（如 Travis CI 和 AppVeyor）集成，以构建和上传适用于各种平台和架构的二进制文件。然后，无需安装 C/C++ 工具链的用户即可下载这些二进制文件。
node-pre-gyp
node-pre-gyp 是一个基于 node-gyp 的工具，它增加了将二进制文件上传到开发者选择的服务器的功能。node-pre-gyp 对将二进制文件上传到 Amazon S3 的支持特别好。
prebuild
prebuild 是一个支持使用 node-gyp 或 CMake.js 进行构建的工具。与支持各种服务器的 node-pre-gyp 不同，prebuild 只将二进制文件上传到 GitHub releases。对于使用 CMake.js 的 GitHub 项目，prebuild 是一个不错的选择。
prebuildify
prebuildify 是一个基于 node-gyp 的工具。prebuildify 的优势在于，构建后的二进制文件会在上传到 npm 时与原生 addon 打包在一起。这些二进制文件从 npm 下载，原生 addon 安装后即可立即供模块用户使用。
使用方法
为了使用 Node-API 函数，需要包含位于 node 开发树 src 目录下的文件 node_api.h：
#include <node_api.h>这将选择给定 Node.js 版本的默认 NAPI_VERSION。为了确保与特定版本的 Node-API 兼容，可以在包含头文件时显式指定版本：
#define NAPI_VERSION 3
#include <node_api.h>这将 Node-API 的表面限制在指定（及更早）版本中可用的功能。
一些 Node-API 的表面是实验性的，需要显式选择加入：
#define NAPI_EXPERIMENTAL
#include <node_api.h>在这种情况下，整个 API 表面，包括任何实验性 API，都将可用于模块代码。
有时，会引入影响已发布和稳定 API 的实验性功能。这些功能可以通过选择退出来禁用：
#define NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT
#include <node_api.h>其中 \<FEATURE_NAME\> 是影响实验性和稳定 API 的实验性功能的名称。
Node-API 版本矩阵
直到 9 版本之前，Node-API 版本是累加的，并且版本号与 Node.js 版本独立。这意味着任何版本都是对先前版本的扩展，因为它包含了先前版本的所有 API 以及一些新增内容。每个 Node.js 版本只支持单个 Node-API 版本。例如，v18.15.0 只支持 Node-API 8 版本。由于 8 是所有先前版本的严格超集，因此实现了 ABI 稳定性。
从 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 版本的功能，则需要更改现有代码并重新编译才能使用这些新函数。
在支持 Node-API 9 及更高版本的 Node.js 版本中，定义 NAPI_VERSION=X 并使用现有的附加组件初始化宏将把运行时将使用的请求的 Node-API 版本烘焙到附加组件中。如果未设置 NAPI_VERSION，则默认为 8。
此表格在较旧的分支中可能未更新，最新信息位于最新的 API 文档中：Node-API 版本矩阵
| Node-API 版本 | 支持的版本 |
|---|---|
| 9 | v18.17.0+，20.3.0+，21.0.0 及所有更高版本 |
| 8 | v12.22.0+，v14.17.0+，v15.12.0+，16.0.0 及所有更高版本 |
| 7 | v10.23.0+，v12.19.0+，v14.12.0+，15.0.0 及所有更高版本 |
| 6 | v10.20.0+，v12.17.0+，14.0.0 及所有更高版本 |
| 5 | v10.17.0+，v12.11.0+，13.0.0 及所有更高版本 |
| 4 | v10.16.0+，v11.8.0+，12.0.0 及所有更高版本 |
| 3 | v6.14.2*，8.11.2+，v9.11.0+*，10.0.0 及所有更高版本 |
| 2 | v8.10.0+，v9.3.0+，10.0.0 及所有更高版本 |
| 1 | v8.6.0+*，v9.0.0+，10.0.0 及所有更高版本 |
- Node-API 为实验性功能。
** Node.js 8.0.0 将 Node-API 作为实验性功能包含在内。它作为 Node-API 1 版本发布，但一直发展到 Node.js 8.6.0。在 Node.js 8.6.0 之前的版本中，API 有所不同。我们推荐使用 Node-API 3 或更高版本。
Node-API 中记录的每个 API 都有一个名为 added in: 的标题，稳定的 API 将具有额外的标题 Node-API version:。当使用支持 Node-API version: 中显示的 Node-API 版本或更高版本的 Node.js 版本时，API 可直接使用。当使用不支持列出的 Node-API version: 的 Node.js 版本，或者没有列出 Node-API version: 时，只有在 #define NAPI_EXPERIMENTAL 在包含 node_api.h 或 js_native_api.h 之前出现时，API 才可用。如果某个 API 似乎在比 added in: 中显示的版本更新的 Node.js 版本上不可用，那么这很可能是其缺失的原因。
与从原生代码访问 ECMAScript 功能严格相关的 Node-API 可以分别在 js_native_api.h 和 js_native_api_types.h 中找到。这些头文件中定义的 API 包含在 node_api.h 和 node_api_types.h 中。这些头文件以这种方式结构化，以便允许在 Node.js 之外实现 Node-API。对于这些实现，Node.js 特定的 API 可能不适用。
附加组件的 Node.js 特定部分可以与将实际功能暴露给 JavaScript 环境的代码分离，以便后者可以与 Node-API 的多个实现一起使用。在下面的示例中，addon.c 和 addon.h 只引用 js_native_api.h。这确保了 addon.c 可以重复用于针对 Node.js 的 Node-API 实现或 Node.js 之外的任何 Node-API 实现进行编译。
addon_node.c 是一个单独的文件，包含附加组件的 Node.js 特定入口点，并在附加组件加载到 Node.js 环境中时通过调用 addon.c 来实例化附加组件。
// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif // _ADDON_H_// 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
第 8.7 节 的 ECMAScript 语言规范 将“Agent”定义为一个独立的环境，JavaScript 代码在其中运行。进程可以并发或顺序地启动和终止多个这样的 Agent。
Node.js 环境对应于一个 ECMAScript Agent。在主进程中，会在启动时创建一个环境，并且可以在单独的线程上创建其他环境以用作 工作线程。当 Node.js 嵌入到另一个应用程序中时，应用程序的主线程也可能在应用程序进程的生命周期内多次构造和销毁 Node.js 环境，这样应用程序创建的每个 Node.js 环境都可能在其生命周期内创建和销毁额外的环境作为工作线程。
从原生插件的角度来看，这意味着它提供的绑定可能被多次调用，来自多个上下文，甚至可能从多个线程并发调用。
原生插件可能需要分配全局状态，在 Node.js 环境的生命周期内使用，以便该状态对于每个插件实例都是唯一的。
为此，Node-API 提供了一种关联数据的方法，使其生命周期与 Node.js 环境的生命周期绑定。
napi_set_instance_data
新增于: v12.8.0, v10.20.0
N-API 版本: 6
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] data: 要提供给此实例绑定程序的数据项。[in] finalize_cb: 环境被销毁时调用的函数。该函数接收data以便释放它。napi_finalize提供更多细节。[in] finalize_hint: 可选提示，在回收期间传递给终结回调函数。
如果 API 成功，则返回 napi_ok。
此 API 将 data 与当前运行的 Node.js 环境关联。稍后可以使用 napi_get_instance_data() 检索 data。任何先前通过调用 napi_set_instance_data() 与当前运行的 Node.js 环境关联的现有数据都将被覆盖。如果先前调用提供了 finalize_cb，则不会调用它。
napi_get_instance_data
新增于：v12.8.0, v10.20.0
N-API 版本：6
napi_status napi_get_instance_data(node_api_basic_env env,
void** data);[in] env: Node-API 调用所在的运行环境。[out] data: 之前通过调用napi_set_instance_data()与当前正在运行的 Node.js 环境关联的数据项。
如果 API 调用成功，则返回 napi_ok。
此 API 获取之前通过 napi_set_instance_data() 与当前正在运行的 Node.js 环境关联的数据。如果未设置数据，则调用将成功，并且 data 将设置为 NULL。
基本 Node-API 数据类型
Node-API 公开了以下基本数据类型作为抽象，供各种 API 使用。这些 API 应被视为不透明的，只能使用其他 Node-API 调用进行内省。
napi_status
新增于：v8.0.0
N-API 版本：1
指示 Node-API 调用成功或失败的整型状态码。当前，支持以下状态码。
typedef enum {
napi_ok,
napi_invalid_arg,
napi_object_expected,
napi_string_expected,
napi_name_expected,
napi_function_expected,
napi_number_expected,
napi_boolean_expected,
napi_array_expected,
napi_generic_failure,
napi_pending_exception,
napi_cancelled,
napi_escape_called_twice,
napi_handle_scope_mismatch,
napi_callback_scope_mismatch,
napi_queue_full,
napi_closing,
napi_bigint_expected,
napi_date_expected,
napi_arraybuffer_expected,
napi_detachable_arraybuffer_expected,
napi_would_deadlock, /* unused */
napi_no_external_buffers_allowed,
napi_cannot_run_js
} napi_status;如果 API 返回失败状态需要更多信息，可以通过调用 napi_get_last_error_info 获取。
napi_extended_error_info
新增于: v8.0.0
N-API 版本: 1
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 编码字符串。engine_reserved: 为虚拟机特定的错误细节保留。目前任何虚拟机均未实现此功能。engine_error_code: 虚拟机特定的错误代码。目前任何虚拟机均未实现此功能。error_code: 上一个错误产生的 Node-API 状态码。
更多信息请参见 错误处理 部分。
napi_env
napi_env 用于表示底层 Node-API 实现可用于持久化虚拟机特定状态的上下文。调用原生函数时会将此结构传递给原生函数，并且在进行 Node-API 调用时必须将其传回。具体来说，必须将初始原生函数调用时传入的相同 napi_env 传递给任何后续嵌套的 Node-API 调用。不允许为了通用重用而缓存 napi_env，也不允许在不同 Worker 线程上运行的同一插件实例之间传递 napi_env。当原生插件实例卸载时，napi_env 将失效。此事件的通知通过传递给 napi_add_env_cleanup_hook 和 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 最终将导致应用程序终止。
napi_value
这是一个不透明指针，用于表示 JavaScript 值。
napi_threadsafe_function
新增于：v10.6.0
N-API 版本：4
这是一个不透明指针，表示一个 JavaScript 函数，可以通过 napi_call_threadsafe_function() 从多个线程异步调用。
napi_threadsafe_function_release_mode
新增于：v10.6.0
N-API 版本：4
一个值，传递给 napi_release_threadsafe_function()，用于指示线程安全函数是否应立即关闭 (napi_tsfn_abort)，或者仅仅释放 (napi_tsfn_release)，以便随后通过 napi_acquire_threadsafe_function() 和 napi_call_threadsafe_function() 使用。
typedef enum {
napi_tsfn_release,
napi_tsfn_abort
} napi_threadsafe_function_release_mode;napi_threadsafe_function_call_mode
新增于：v10.6.0
N-API 版本：4
一个值，传递给 napi_call_threadsafe_function()，用于指示当与线程安全函数关联的队列已满时，调用是否应阻塞。
typedef enum {
napi_tsfn_nonblocking,
napi_tsfn_blocking
} napi_threadsafe_function_call_mode;Node-API 内存管理类型
napi_handle_scope
这是一个用于控制和修改在特定作用域内创建的对象生命周期的抽象。通常，Node-API 值是在句柄作用域的上下文中创建的。当从 JavaScript 调用原生方法时，将存在一个默认的句柄作用域。如果用户没有显式创建新的句柄作用域，则 Node-API 值将在默认句柄作用域中创建。对于在原生方法执行之外的任何代码调用（例如，在 libuv 回调调用期间），模块需要在调用任何可能导致创建 JavaScript 值的函数之前创建一个作用域。
句柄作用域使用 napi_open_handle_scope 创建，并使用 napi_close_handle_scope 销毁。关闭作用域可以向 GC 指示在句柄作用域的生命周期内创建的所有 napi_value 都不再被当前栈帧引用。
更多详情，请查看 对象生命周期管理。
napi_escapable_handle_scope
新增于：v8.0.0
N-API 版本：1
可逃逸句柄作用域是一种特殊的句柄作用域，用于将特定句柄作用域内创建的值返回给父作用域。
napi_ref
新增于：v8.0.0
N-API 版本：1
这是用于引用 napi_value 的抽象。这允许用户管理 JavaScript 值的生命周期，包括显式定义其最小生命周期。
更多详情，请参阅 对象生命周期管理。
napi_type_tag
新增于：v14.8.0, v12.19.0
N-API 版本：8
一个存储为两个无符号 64 位整数的 128 位值。它充当 UUID，JavaScript 对象或 外部对象 可以用它来“标记”，以确保它们属于某种类型。这比 napi_instanceof 更严格的检查，因为如果对象的原型已被操纵，后者可能会报告误报。类型标记与 napi_wrap 一起使用最为有效，因为它确保从包装对象检索的指针可以安全地转换为与先前应用于 JavaScript 对象的类型标记对应的原生类型。
typedef struct {
uint64_t lower;
uint64_t upper;
} napi_type_tag;napi_async_cleanup_hook_handle
新增于：v14.10.0, v12.19.0
由 napi_add_async_cleanup_hook 返回的不透明值。异步清理事件链完成时，必须将其传递给 napi_remove_async_cleanup_hook。
Node-API 回调类型
napi_callback_info
新增于：v8.0.0
N-API 版本：1
传递给回调函数的不透明数据类型。它可以用于获取有关调用回调函数的上下文的其他信息。
napi_callback
新增于：v8.0.0
N-API 版本：1
用户提供的原生函数的函数指针类型，这些函数将通过 Node-API 公开给 JavaScript。回调函数应满足以下签名：
typedef napi_value (*napi_callback)(napi_env, napi_callback_info);除非出于 对象生命周期管理 中讨论的原因，否则在 napi_callback 内创建句柄和/或回调范围并非必要。
node_api_basic_finalize
新增于: v21.6.0, v20.12.0, v18.20.0
用于附加模块提供的函数的函数指针类型，允许用户在与其关联的对象被垃圾回收后，被告知何时可以清理外部拥有的数据。用户必须提供一个满足以下签名的函数，该函数将在对象被回收时被调用。目前，node_api_basic_finalize 可用于查找拥有外部数据的对象何时被收集。
typedef void (*node_api_basic_finalize)(node_api_basic_env env,
void* finalize_data,
void* finalize_hint);除非出于对象生命周期管理中讨论的原因，否则在函数体内部创建句柄和/或回调作用域是没有必要的。
由于这些函数可能在 JavaScript 引擎处于无法执行 JavaScript 代码的状态下被调用，因此只能调用将 node_api_basic_env 作为其第一个参数的 Node-API。node_api_post_finalizer 可用于调度需要访问 JavaScript 引擎状态的 Node-API 调用，以便在当前垃圾回收周期完成后运行。
对于node_api_create_external_string_latin1 和 node_api_create_external_string_utf16，env 参数可能为 null，因为外部字符串可以在环境关闭的后期被收集。
变更历史:
- 实验性 (
NAPI_EXPERIMENTAL): 只能调用将node_api_basic_env作为其第一个参数的 Node-API 调用，否则应用程序将被终止并显示相应的错误消息。此功能可以通过定义NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT来关闭。
napi_finalize
新增于: v8.0.0
N-API 版本: 1
函数指针类型，用于附加组件提供的函数，允许用户在垃圾回收周期完成后，响应垃圾回收事件调度一组对 Node-API 的调用。这些函数指针可以与 node_api_post_finalizer 一起使用。
typedef void (*napi_finalize)(napi_env env,
void* finalize_data,
void* finalize_hint);变更历史：
- 实验性（定义了
NAPI_EXPERIMENTAL）：此类型的函数可能不再用作终结器，除非与node_api_post_finalizer一起使用。必须改用node_api_basic_finalize。可以通过定义NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT来关闭此功能。
napi_async_execute_callback
新增于: v8.0.0
N-API 版本: 1
与支持异步操作的函数一起使用的函数指针。回调函数必须满足以下签名：
typedef void (*napi_async_execute_callback)(napi_env env, void* data);此函数的实现必须避免进行执行 JavaScript 或与 JavaScript 对象交互的 Node-API 调用。Node-API 调用应在 napi_async_complete_callback 中进行。不要使用 napi_env 参数，因为它可能会导致 JavaScript 的执行。
napi_async_complete_callback
新增于：v8.0.0
N-API 版本：1
用于支持异步操作的函数的函数指针。回调函数必须满足以下签名：
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data);除非出于对象生命周期管理中讨论的原因，否则在函数体内部创建句柄和/或回调作用域是不必要的。
napi_threadsafe_function_call_js
新增于：v10.6.0
N-API 版本：4
用于异步线程安全函数调用的函数指针。回调将在主线程上调用。其目的是使用通过队列从辅助线程之一到达的数据项来构造调用 JavaScript 所需的参数，通常通过 napi_call_function，然后调用 JavaScript。
通过队列从辅助线程到达的数据在 data 参数中给出，要调用的 JavaScript 函数在 js_callback 参数中给出。
Node-API 在调用此回调之前设置环境，因此通过 napi_call_function 而不是 napi_make_callback 调用 JavaScript 函数就足够了。
回调函数必须满足以下签名：
typedef void (*napi_threadsafe_function_call_js)(napi_env env,
napi_value js_callback,
void* context,
void* data);[in] env: 用于 API 调用的环境，如果线程安全函数正在被拆除并且可能需要释放data，则为NULL。[in] js_callback: 要调用的 JavaScript 函数，如果线程安全函数正在被拆除并且可能需要释放data，则为NULL。如果线程安全函数是在没有js_callback的情况下创建的，它也可能是NULL。[in] context: 创建线程安全函数时使用的可选数据。[in] data: 由辅助线程创建的数据。回调负责将此原生数据转换为可以用作参数的 JavaScript 值（使用 Node-API 函数），当调用js_callback时可以使用这些值。此指针完全由线程和此回调管理。因此，此回调应释放数据。
除非出于对象生命周期管理中讨论的原因，否则在函数体内部创建句柄和/或回调作用域是不必要的。
napi_cleanup_hook
新增于：v19.2.0, v18.13.0
N-API 版本：3
与 napi_add_env_cleanup_hook 一起使用的函数指针。环境被拆除时将调用它。
回调函数必须满足以下签名：
typedef void (*napi_cleanup_hook)(void* data);[in] data: 传递给napi_add_env_cleanup_hook的数据。
napi_async_cleanup_hook
新增于：v14.10.0, v12.19.0
与 napi_add_async_cleanup_hook 一起使用的函数指针。环境被拆除时将调用它。
回调函数必须满足以下签名：
typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
void* data);[in] handle: 必须传递给napi_remove_async_cleanup_hook的句柄，用于异步清理完成后。[in] data: 传递给napi_add_async_cleanup_hook的数据。
函数体应在异步清理操作结束时启动，此时必须在调用 napi_remove_async_cleanup_hook 时传递 handle。
错误处理
Node-API 使用返回值和 JavaScript 异常进行错误处理。以下部分解释每种情况的方法。
返回值
所有 Node-API 函数共享相同的错误处理模式。所有 API 函数的返回类型都是 napi_status。
如果请求成功且未抛出未捕获的 JavaScript 异常，则返回值将为 napi_ok。如果发生错误并且抛出异常，则将返回错误的 napi_status 值。如果抛出异常，并且没有发生错误，则将返回 napi_pending_exception。
在返回 napi_ok 或 napi_pending_exception 以外的返回值的情况下，必须调用 napi_is_exception_pending 来检查是否挂起了异常。有关详细信息，请参阅关于异常的部分。
完整的 napi_status 值集在 napi_api_types.h 中定义。
napi_status 返回值提供了发生的错误的与虚拟机无关的表示。在某些情况下，能够获取更详细的信息（包括表示错误的字符串以及特定于虚拟机（引擎）的信息）很有用。
为了检索此信息，提供了 napi_get_last_error_info，它返回一个 napi_extended_error_info 结构。napi_extended_error_info 结构的格式如下：
新增于：v8.0.0
N-API 版本：1
typedef struct napi_extended_error_info {
const char* error_message;
void* engine_reserved;
uint32_t engine_error_code;
napi_status error_code;
};error_message: 发生的错误的文本表示。engine_reserved: 仅供引擎使用的 opaque 句柄。engine_error_code: VM 特定的错误代码。error_code: 上一个错误的 Node-API 状态代码。
napi_get_last_error_info 返回上次进行的 Node-API 调用的信息。
不要依赖任何扩展信息的內容或格式，因为它不受 SemVer 的约束，并且可能随时更改。它仅用于日志记录目的。
napi_get_last_error_info
新增于: v8.0.0
N-API 版本: 1
napi_status
napi_get_last_error_info(node_api_basic_env env,
const napi_extended_error_info** result);[in] env: API 调用的环境。[out] result: 包含更多错误信息的napi_extended_error_info结构体。
如果 API 成功，则返回 napi_ok。
此 API 获取一个包含关于最后发生错误信息的 napi_extended_error_info 结构体。
返回的 napi_extended_error_info 的内容仅在对相同 env 调用 Node-API 函数之前有效。这包括对 napi_is_exception_pending 的调用，因此通常需要复制信息以便稍后使用。error_message 中返回的指针指向一个静态定义的字符串，因此如果您在调用另一个 Node-API 函数之前已将其从 error_message 字段（将被覆盖）中复制出来，则可以使用该指针。
不要依赖任何扩展信息的內容或格式，因为它不受 SemVer 约束，并且随时可能更改。它仅用于日志记录目的。
即使存在挂起的 JavaScript 异常，也可以调用此 API。
异常
任何 Node-API 函数调用都可能导致挂起的 JavaScript 异常。对于任何 API 函数，即使那些可能不会导致 JavaScript 执行的函数，情况也是如此。
如果函数返回的 napi_status 为 napi_ok，则没有异常挂起，不需要任何额外操作。如果返回的 napi_status 为除 napi_ok 或 napi_pending_exception 之外的任何值，为了尝试恢复并继续而不是立即返回，必须调用 napi_is_exception_pending 来确定是否挂起了异常。
在许多情况下，当调用 Node-API 函数并且已经挂起了异常时，该函数将立即返回 napi_status 为 napi_pending_exception。但是，并非所有函数都是如此。Node-API 允许调用一部分函数，以便在返回 JavaScript 之前进行一些最小限度的清理。在这种情况下，napi_status 将反映函数的状态。它不会反映之前的挂起异常。为避免混淆，请在每次函数调用后检查错误状态。
当异常挂起时，可以使用两种方法之一。
第一种方法是执行任何适当的清理，然后返回，以便执行将返回到 JavaScript。作为返回 JavaScript 的一部分，异常将在调用原生方法的 JavaScript 代码中的点处被抛出。在异常挂起时，大多数 Node-API 调用的行为未指定，并且许多调用将简单地返回 napi_pending_exception，因此尽可能少做一些事情，然后返回到 JavaScript，在那里可以处理异常。
第二种方法是尝试处理异常。在某些情况下，原生代码可以捕获异常，采取适当的操作，然后继续。仅当已知可以安全地处理异常时才推荐此方法。在这些情况下，可以使用 napi_get_and_clear_last_exception 获取并清除异常。成功后，结果将包含对最后抛出的 JavaScript Object 的句柄。如果确定在检索异常后，最终无法处理异常，则可以使用 napi_throw 重新抛出异常，其中 error 是要抛出的 JavaScript 值。
如果原生代码需要抛出异常或确定 napi_value 是否为 JavaScript Error 对象的实例，则还可以使用以下实用程序函数：napi_throw_error、napi_throw_type_error、napi_throw_range_error、node_api_throw_syntax_error 和 napi_is_error。
如果原生代码需要创建 Error 对象，则还可以使用以下实用程序函数：napi_create_error、napi_create_type_error、napi_create_range_error 和 node_api_create_syntax_error，其中 result 是引用新创建的 JavaScript Error 对象的 napi_value。
Node.js 项目正在为所有内部生成的错误添加错误代码。目标是应用程序对所有错误检查使用这些错误代码。关联的错误消息将保留，但仅用于日志记录和显示，预期消息可以在不应用 SemVer 的情况下更改。为了使用 Node-API 支持此模型，无论是在内部功能中还是在模块特定功能中（因为这是最佳实践），throw_ 和 create_ 函数都采用可选的 code 参数，该参数是添加到错误对象的代码的字符串。如果可选参数为 NULL，则不会将任何代码与错误关联。如果提供代码，则关联错误的名称也会更新为：
originalName [code]其中 originalName 是与错误关联的原始名称，code 是提供的代码。例如，如果代码是 'ERR_ERROR_1' 并且正在创建 TypeError，则名称将为：
TypeError [ERR_ERROR_1]napi_throw
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);[in] env: API 调用的环境。[in] error: 要抛出的 JavaScript 值。
如果 API 成功，则返回 napi_ok。
此 API 抛出提供的 JavaScript 值。
napi_throw_error
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_throw_error(napi_env env,
const char* code,
const char* msg);[in] env: API 调用的环境。[in] code: 可选的错误代码，将设置在错误上。[in] msg: 表示与错误关联的文本的 C 字符串。
如果 API 成功，则返回 napi_ok。
此 API 抛出一个带有提供的文本的 JavaScript Error。
napi_throw_type_error
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,
const char* code,
const char* msg);[in] env: API 调用的环境。[in] code: 可选的错误代码，将设置在错误上。[in] msg: 表示与错误关联的文本的 C 字符串。
如果 API 成功，则返回 napi_ok。
此 API 抛出一个带有提供的文本的 JavaScript TypeError。
napi_throw_range_error
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,
const char* code,
const char* msg);[in] env: API 调用的环境。[in] code: 可选的错误代码，将设置在错误上。[in] msg: 代表与错误关联的文本的 C 字符串。
如果 API 成功，则返回 napi_ok。
此 API 使用提供的文本抛出一个 JavaScript RangeError。
node_api_throw_syntax_error
新增于: v17.2.0, v16.14.0
N-API 版本: 9
NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,
const char* code,
const char* msg);[in] env: API 调用的环境。[in] code: 可选的错误代码，将设置在错误上。[in] msg: 代表与错误关联的文本的 C 字符串。
如果 API 成功，则返回 napi_ok。
此 API 使用提供的文本抛出一个 JavaScript SyntaxError。
napi_is_error
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_is_error(napi_env env,
napi_value value,
bool* result);[in] env: API 调用的环境。[in] value: 待检查的napi_value。[out] result: 布尔值，如果napi_value代表一个错误则设置为 true，否则为 false。
如果 API 成功，则返回 napi_ok。
此 API 查询 napi_value 以检查其是否代表一个错误对象。
napi_create_error
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_create_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: API 调用的环境。[in] code: 可选的napi_value，包含与错误关联的错误代码字符串。[in] msg: 引用 JavaScriptstring的napi_value，用作Error的消息。[out] result: 代表创建的错误的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 返回一个包含提供文本的 JavaScript Error。
napi_create_type_error
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_create_type_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: API 调用的环境。[in] code: 可选的napi_value，包含与错误关联的错误代码字符串。[in] msg:napi_value，引用一个 JavaScriptstring，用作Error的消息。[out] result: 代表创建的错误的napi_value。
如果 API 成功，则返回napi_ok。
此 API 返回一个包含提供的文本的 JavaScript TypeError。
napi_create_range_error
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
napi_value code,
napi_value msg,
napi_value* result);[in] env: API 调用的环境。[in] code: 可选的napi_value，包含与错误关联的错误代码字符串。[in] msg:napi_value，引用一个 JavaScriptstring，用作Error的消息。[out] result: 代表创建的错误的napi_value。
如果 API 成功，则返回napi_ok。
此 API 返回一个包含提供的文本的 JavaScript RangeError。
node_api_create_syntax_error
新增于：v17.2.0, v16.14.0
N-API 版本：9
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] code: 可选的napi_value，包含与错误关联的错误代码字符串。[in] msg:napi_value，引用一个 JavaScriptstring，用作Error的消息。[out] result: 代表已创建错误的napi_value。
如果 API 成功，则返回napi_ok。
此 API 返回一个包含提供的文本的 JavaScript SyntaxError。
napi_get_and_clear_last_exception
新增于：v8.0.0
N-API 版本：1
napi_status napi_get_and_clear_last_exception(napi_env env,
napi_value* result);[in] env: API 调用的环境。[out] result: 如果存在挂起的异常，则为异常；否则为NULL。
如果 API 成功，则返回napi_ok。
即使存在挂起的 JavaScript 异常，也可以调用此 API。
napi_is_exception_pending
新增于: v8.0.0
N-API 版本: 1
napi_status napi_is_exception_pending(napi_env env, bool* result);[in] env: API 调用的环境。[out] result: 布尔值，如果存在未处理异常则设置为 true。
如果 API 调用成功，则返回 napi_ok。
即使存在未处理的 JavaScript 异常，也可以调用此 API。
napi_fatal_exception
新增于: v9.10.0
N-API 版本: 3
napi_status napi_fatal_exception(napi_env env, napi_value err);[in] env: API 调用的环境。[in] err: 传递给'uncaughtException'的错误。
在 JavaScript 中触发'uncaughtException'事件。如果异步回调抛出无法恢复的异常，则此方法很有用。
致命错误
如果原生插件出现不可恢复的错误，可以抛出致命错误以立即终止进程。
napi_fatal_error
新增于: v8.2.0
N-API 版本: 1
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_len: 位置的长度（字节），如果为 null 结尾则为NAPI_AUTO_LENGTH。[in] message: 与错误相关的消息。[in] message_len: 消息的长度（字节），如果为 null 结尾则为NAPI_AUTO_LENGTH。
函数调用不会返回，进程将被终止。
即使存在未处理的 JavaScript 异常，也可以调用此 API。
对象生命周期管理
当进行 Node-API 调用时，底层 VM 堆中对象的句柄可能会以 napi_values 的形式返回。这些句柄必须保持对象的“存活”状态，直到原生代码不再需要它们，否则在原生代码完成使用之前，这些对象可能会被垃圾回收。
返回的对象句柄与一个“作用域”相关联。默认作用域的生命周期与原生方法调用的生命周期绑定。结果是，默认情况下，句柄保持有效，并且与这些句柄关联的对象将在原生方法调用的生命周期内保持存活。
但是，在许多情况下，需要句柄的有效期比原生方法的有效期更短或更长。接下来的部分描述了可用于更改句柄生命周期（使其偏离默认值）的 Node-API 函数。
使句柄生命周期短于原生方法的生命周期
通常需要使句柄的生命周期短于原生方法的生命周期。例如，考虑一个原生方法，它有一个循环，循环遍历大型数组中的元素：
for (int i = 0; i < 1000000; i++) {
napi_value result;
napi_status status = napi_get_element(env, object, i, &result);
if (status != napi_ok) {
break;
}
// 对元素执行某些操作
}这将导致创建大量句柄，从而消耗大量资源。此外，即使原生代码只能使用最新的句柄，所有关联的对象也将保持存活，因为它们共享相同的范围。
为了处理这种情况，Node-API 提供了建立新“作用域”的能力，新创建的句柄将与该作用域关联。一旦不再需要这些句柄，就可以“关闭”作用域，并且与该作用域关联的任何句柄都将失效。用于打开/关闭作用域的方法是 napi_open_handle_scope 和 napi_close_handle_scope。
Node-API 只支持单个嵌套的作用域层次结构。任何时候都只有一个活动作用域，所有新句柄将在该作用域活动时与该作用域关联。作用域必须按打开的相反顺序关闭。此外，在从原生方法返回之前，必须关闭在原生方法内创建的所有作用域。
以之前的例子为例，添加对 napi_open_handle_scope 和 napi_close_handle_scope 的调用将确保在循环执行期间最多只有一个句柄有效：
for (int i = 0; i < 1000000; i++) {
napi_handle_scope scope;
napi_status status = napi_open_handle_scope(env, &scope);
if (status != napi_ok) {
break;
}
napi_value result;
status = napi_get_element(env, object, i, &result);
if (status != napi_ok) {
break;
}
// 对元素执行某些操作
status = napi_close_handle_scope(env, scope);
if (status != napi_ok) {
break;
}
}当嵌套作用域时，内部作用域中的句柄需要超出该作用域的生命周期的情况。Node-API 支持“可逃逸作用域”以支持这种情况。可逃逸作用域允许“提升”一个句柄，以便它“逃逸”当前作用域，并且句柄的生命周期从当前作用域更改为外部作用域。
用于打开/关闭可逃逸作用域的方法是 napi_open_escapable_handle_scope 和 napi_close_escapable_handle_scope。
提升句柄的请求是通过 napi_escape_handle 发出的，该方法只能调用一次。
napi_open_handle_scope
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,
napi_handle_scope* result);[in] env: API 调用的环境。[out] result: 代表新作用域的napi_value。
如果 API 成功，则返回napi_ok。
此 API 打开一个新的作用域。
napi_close_handle_scope
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
napi_handle_scope scope);[in] env: API 调用的环境。[in] scope: 代表要关闭的作用域的napi_value。
如果 API 成功，则返回napi_ok。
此 API 关闭传入的作用域。作用域必须以与创建它们的相反顺序关闭。
即使存在未处理的 JavaScript 异常，也可以调用此 API。
napi_open_escapable_handle_scope
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status
napi_open_escapable_handle_scope(napi_env env,
napi_handle_scope* result);[in] env: API 调用的环境。[out] result: 代表新作用域的napi_value。
如果 API 成功，则返回napi_ok。
此 API 打开一个新的作用域，从中可以将一个对象提升到外部作用域。
napi_close_escapable_handle_scope
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status
napi_close_escapable_handle_scope(napi_env env,
napi_handle_scope scope);[in] env: API 调用的环境。[in] scope: 代表要关闭的作用域的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 关闭传入的作用域。作用域必须按照创建的相反顺序关闭。
即使存在未处理的 JavaScript 异常，也可以调用此 API。
napi_escape_handle
新增于: v8.0.0
N-API 版本: 1
napi_status napi_escape_handle(napi_env env,
napi_escapable_handle_scope scope,
napi_value escapee,
napi_value* result);[in] env: API 调用的环境。[in] scope: 代表当前作用域的napi_value。[in] escapee: 代表要转义的 JavaScriptObject的napi_value。[out] result: 代表在外层作用域中转义的Object的句柄的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 将 JavaScript 对象的句柄提升到外层作用域的生存期内有效。它每个作用域只能调用一次。如果调用多次，则会返回错误。
即使存在未处理的 JavaScript 异常，也可以调用此 API。
对生命周期长于原生方法的值的引用
在某些情况下，插件需要能够创建和引用生命周期长于单个原生方法调用的值。例如，要创建一个构造函数并在稍后使用该构造函数请求创建实例，必须能够跨许多不同的实例创建请求引用构造函数对象。使用前面部分中描述的作为 napi_value 返回的普通句柄无法做到这一点。普通句柄的生命周期由作用域管理，并且所有作用域都必须在原生方法结束之前关闭。
Node-API 提供了创建值持久引用的方法。目前 Node-API 只允许为有限的几种值类型创建引用，包括对象、外部、函数和符号。
每个引用都有一个关联的计数，其值为 0 或更高，这决定了引用是否会使相应的值保持存活。计数为 0 的引用不会阻止值被收集。对象（对象、函数、外部）和符号类型的值将成为“弱”引用，并且在它们未被收集时仍然可以访问。任何大于 0 的计数都将阻止值被收集。
符号值具有不同的类型。真正的弱引用行为仅受使用 napi_create_symbol 函数或 JavaScript Symbol() 构造函数调用创建的局部符号支持。使用 node_api_symbol_for 函数或 JavaScript Symbol.for() 函数调用创建的全局注册符号始终保持强引用，因为垃圾收集器不会收集它们。众所周知的符号（如 Symbol.iterator）也是如此。它们也永远不会被垃圾收集器收集。
可以使用初始引用计数创建引用。然后可以通过 napi_reference_ref 和 napi_reference_unref 修改计数。如果在引用的计数为 0 时对象被收集，则随后所有获取与引用 napi_get_reference_value 关联的对象的调用都将为返回的 napi_value 返回 NULL。尝试对对象已被收集的引用调用 napi_reference_ref 将导致错误。
插件不再需要引用后必须删除它们。删除引用后，它将不再阻止收集相应的对象。未能删除持久引用会导致“内存泄漏”，持久引用的原生内存和堆上相应的对象将永远保留。
可以创建多个引用同一对象的持久引用，每个引用都会根据其单独的计数来保持对象存活与否。对同一对象的多个持久引用可能导致意外地保持原生内存存活。持久引用的原生结构必须保持存活，直到引用的对象的终结器执行完毕。如果为同一对象创建新的持久引用，则该对象的终结器将不会运行，并且先前持久引用指向的原生内存将不会被释放。这可以通过在可能的情况下调用 napi_delete_reference 以及 napi_reference_unref 来避免。
变更历史：
- 实验性（
NAPI_EXPERIMENTAL已定义）：可以为所有值类型创建引用。新支持的值类型不支持弱引用语义，当引用计数变为 0 时，这些类型的值将被释放，并且无法再从引用中访问。
napi_create_reference
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_create_reference(napi_env env,
napi_value value,
uint32_t initial_refcount,
napi_ref* result);[in] env: API 调用的环境。[in] value: 创建引用的napi_value。[in] initial_refcount: 新引用的初始引用计数。[out] result: 指向新引用的napi_ref。
如果 API 成功，则返回 napi_ok。
此 API 使用指定的引用计数创建一个对传入值的新的引用。
napi_delete_reference
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);[in] env: API 调用的环境。[in] ref: 要删除的napi_ref。
如果 API 成功，则返回 napi_ok。
此 API 删除传入的引用。
即使存在未处理的 JavaScript 异常，也可以调用此 API。
napi_reference_ref
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_reference_ref(napi_env env,
napi_ref ref,
uint32_t* result);[in] env: API 调用的环境。[in] ref: 将对其引用计数递增的napi_ref。[out] result: 新的引用计数。
如果 API 成功，则返回 napi_ok。
此 API 将传入引用的引用计数递增，并返回生成的引用计数。
napi_reference_unref
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_reference_unref(napi_env env,
napi_ref ref,
uint32_t* result);[in] env: API 调用的环境。[in] ref: 将对其引用计数递减的napi_ref。[out] result: 新的引用计数。
如果 API 成功，则返回 napi_ok。
此 API 将传入引用的引用计数递减，并返回生成的引用计数。
napi_get_reference_value
新增于：v8.0.0
N-API 版本：1
NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,
napi_ref ref,
napi_value* result);[in] env: API 调用的环境。[in] ref: 请求对应值的napi_ref。[out] result:napi_ref引用的napi_value。
如果 API 成功，则返回napi_ok。
如果仍然有效，此 API 将返回表示与napi_ref关联的 JavaScript 值的napi_value。否则，result 将为NULL。
当前 Node.js 环境退出时的清理
虽然 Node.js 进程通常会在退出时释放其所有资源，但 Node.js 的嵌入器或未来的 Worker 支持可能需要加载项注册清理钩子，这些钩子将在当前 Node.js 环境退出时运行。
Node-API 提供了注册和注销此类回调的函数。当这些回调运行时，加载项持有的所有资源都应释放。
napi_add_env_cleanup_hook
新增于: v10.2.0
N-API 版本: 3
NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,
napi_cleanup_hook fun,
void* arg);注册 fun 为一个函数，在当前 Node.js 环境退出时，使用 arg 参数运行该函数。
可以使用不同的 arg 值多次安全地指定一个函数。在这种情况下，它也将被多次调用。多次提供相同的 fun 和 arg 值是不允许的，并将导致进程中止。
这些钩子将以相反的顺序调用，即最近添加的钩子将首先被调用。
可以使用 napi_remove_env_cleanup_hook 删除此钩子。通常，当为此钩子添加的资源被销毁时，就会发生这种情况。
对于异步清理，可以使用 napi_add_async_cleanup_hook。
napi_remove_env_cleanup_hook
新增于: v10.2.0
N-API 版本: 3
NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,
void (*fun)(void* arg),
void* arg);注销 fun 函数，该函数会在当前 Node.js 环境退出时使用 arg 参数运行。参数和函数值都需要完全匹配。
该函数必须最初使用 napi_add_env_cleanup_hook 注册，否则进程将中止。
napi_add_async_cleanup_hook
[历史]
| 版本 | 变更 |
|---|---|
| v14.10.0, v12.19.0 | 更改了 hook 回调函数的签名。 |
| v14.8.0, v12.19.0 | 新增于: v14.8.0, v12.19.0 |
N-API 版本: 8
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] hook: 在环境拆卸时调用的函数指针。[in] arg: 调用hook时传递给它的指针。[out] remove_handle: 指向异步清理钩子的可选句柄。
注册 hook，这是一个 napi_async_cleanup_hook 类型函数，该函数会在当前 Node.js 环境退出时使用 remove_handle 和 arg 参数运行。
与 napi_add_env_cleanup_hook 不同，允许该钩子异步执行。
否则，行为通常与 napi_add_env_cleanup_hook 相同。
如果 remove_handle 不是 NULL，则一个不透明的值将存储在其中，该值稍后必须传递给 napi_remove_async_cleanup_hook，而不管钩子是否已经被调用。通常，当为此钩子添加的资源正在被拆除时，就会发生这种情况。
napi_remove_async_cleanup_hook
[历史]
| 版本 | 变更 |
|---|---|
| v14.10.0, v12.19.0 | 移除了 env 参数。 |
| v14.8.0, v12.19.0 | 新增于: v14.8.0, v12.19.0 |
NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
napi_async_cleanup_hook_handle remove_handle);[in] remove_handle: 使用napi_add_async_cleanup_hook创建的异步清理钩子的句柄。
注销与 remove_handle 对应的清理钩子。这将阻止钩子执行，除非它已经开始执行。必须对从 napi_add_async_cleanup_hook 获得的任何 napi_async_cleanup_hook_handle 值调用此函数。
Node.js 环境退出时的终结
Node.js 环境可能在任意时间尽快被拆除，此时不允许执行 JavaScript 代码，例如在请求 worker.terminate() 时。当环境正在被拆除时，JavaScript 对象、线程安全函数和环境实例数据的已注册 napi_finalize 回调将立即且独立地被调用。
napi_finalize 回调的调用安排在手动注册的清理钩子之后。为了确保在环境关闭期间插件终结的正确顺序，以避免在 napi_finalize 回调中出现 use-after-free，插件应该使用 napi_add_env_cleanup_hook 和 napi_add_async_cleanup_hook 注册清理钩子，以便以正确的顺序手动释放已分配的资源。
模块注册
Node-API 模块的注册方式与其他模块类似，不同之处在于它不使用 NODE_MODULE 宏，而是使用：
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)另一个区别在于 Init 方法的签名。对于 Node-API 模块，其签名如下：
napi_value Init(napi_env env, napi_value exports);Init 的返回值被视为模块的 exports 对象。Init 方法通过 exports 参数传递一个空对象作为便利。如果 Init 返回 NULL，则作为 exports 参数传递的对象将被模块导出。Node-API 模块不能修改 module 对象，但可以将任何内容指定为模块的 exports 属性。
要添加 hello 方法作为函数，以便可以将其作为插件提供的函数调用：
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_property_descriptor desc = {
"hello",
NULL,
Method,
NULL,
NULL,
NULL,
napi_writable | napi_enumerable | napi_configurable,
NULL
};
status = napi_define_properties(env, exports, 1, &desc);
if (status != napi_ok) return NULL;
return exports;
}要设置一个由插件的 require() 返回的函数：
napi_value Init(napi_env env, napi_value exports) {
napi_value method;
napi_status status;
status = napi_create_function(env, "exports", NAPI_AUTO_LENGTH, Method, NULL, &method);
if (status != napi_ok) return NULL;
return method;
}要定义一个类以便可以创建新实例（通常与 对象包装 一起使用）：
// 注意：部分示例，未包含所有引用的代码
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 函数的简写：
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 参数将提供给宏调用后的函数体。
所有 Node-API 插件都是上下文感知的，这意味着它们可以多次加载。声明此类模块时，有一些设计注意事项。关于 上下文感知插件 的文档提供了更多详细信息。
env 和 exports 变量将在宏调用后的函数体内可用。
有关在对象上设置属性的更多详细信息，请参阅有关 使用 JavaScript 属性 的部分。
有关一般构建插件模块的更多详细信息，请参考现有 API。
使用 JavaScript 值
Node-API 提供了一组 API 来创建所有类型的 JavaScript 值。其中一些类型在 ECMAScript 语言规范 的 第 6 节 中有文档记录。
从根本上说，这些 API 用于执行以下操作之一：
Node-API 值由类型 napi_value 表示。任何需要 JavaScript 值的 Node-API 调用都会传入一个 napi_value。在某些情况下，API 会预先检查 napi_value 的类型。但是，为了提高性能，最好由调用者确保 napi_value 的类型与 API 预期的 JavaScript 类型一致。
枚举类型
napi_key_collection_mode
新增于：v13.7.0, v12.17.0, v10.20.0
N-API 版本：6
typedef enum {
napi_key_include_prototypes,
napi_key_own_only
} napi_key_collection_mode;描述 Keys/Properties 过滤器枚举：
napi_key_collection_mode 限制了收集属性的范围。
napi_key_own_only 将收集的属性限制为仅限于给定对象。napi_key_include_prototypes 还将包含对象原型链中的所有键。
napi_key_filter
新增于: v13.7.0, v12.17.0, v10.20.0
N-API 版本: 6
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;属性过滤器位。它们可以进行按位或运算来构建复合过滤器。
napi_key_conversion
新增于: v13.7.0, v12.17.0, v10.20.0
N-API 版本: 6
typedef enum {
napi_key_keep_numbers,
napi_key_numbers_to_strings
} napi_key_conversion;napi_key_numbers_to_strings 将整数索引转换为字符串。napi_key_keep_numbers 将为整数索引返回数字。
napi_valuetype
typedef enum {
// ES6 类型 (对应于 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。
napi_external 类型的 JavaScript 值在 JavaScript 中显示为一个普通对象，无法设置其任何属性，也没有原型。
napi_typedarray_type
typedef enum {
napi_int8_array,
napi_uint8_array,
napi_uint8_clamped_array,
napi_int16_array,
napi_uint16_array,
napi_int32_array,
napi_uint32_array,
napi_float32_array,
napi_float64_array,
napi_bigint64_array,
napi_biguint64_array,
} napi_typedarray_type;此枚举表示 TypedArray 的底层二进制标量数据类型。此枚举的元素对应于 ECMAScript 语言规范 的 第 22.2 节。
对象创建函数
napi_create_array
新增于：v8.0.0
N-API 版本：1
napi_status napi_create_array(napi_env env, napi_value* result)[in] env: 调用 Node-API 函数的环境。[out] result: 表示 JavaScriptArray的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 返回一个对应于 JavaScript Array 类型的 Node-API 值。JavaScript 数组在 ECMAScript 语言规范的 第 22.1 节 中进行了描述。
napi_create_array_with_length
新增于: v8.0.0
N-API 版本: 1
napi_status napi_create_array_with_length(napi_env env,
size_t length,
napi_value* result)[in] env: API 调用的环境。[in] length:Array的初始长度。[out] result: 表示 JavaScriptArray的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 返回一个对应于 JavaScript Array 类型的 Node-API 值。Array 的 length 属性设置为传入的 length 参数。但是，当创建数组时，不能保证底层缓冲区由 VM 预先分配。此行为留给底层 VM 实现。如果缓冲区必须是可通过 C 直接读取和/或写入的连续内存块，请考虑使用 napi_create_external_arraybuffer。
JavaScript 数组在 ECMAScript 语言规范的 第 22.1 节 中进行了描述。
napi_create_arraybuffer
新增于: v8.0.0
N-API 版本: 1
napi_status napi_create_arraybuffer(napi_env env,
size_t byte_length,
void** data,
napi_value* result)[in] env: API 调用的环境。[in] length: 要创建的 ArrayBuffer 的字节长度。[out] data: 指向ArrayBuffer底层字节缓冲区的指针。data可以通过传递NULL来选择性地忽略。[out] result: 代表 JavaScriptArrayBuffer的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 返回一个对应于 JavaScript ArrayBuffer 的 Node-API 值。ArrayBuffer 用于表示固定长度的二进制数据缓冲区。它们通常用作 TypedArray 对象的底层缓冲区。分配的 ArrayBuffer 将具有一个底层字节缓冲区，其大小由传入的 length 参数确定。如果调用者想要直接操作缓冲区，则可以选择性地将底层缓冲区返回给调用者。此缓冲区只能从原生代码直接写入。要从 JavaScript 写入此缓冲区，需要创建一个类型数组或 DataView 对象。
JavaScript ArrayBuffer 对象在 ECMAScript 语言规范的 第 24.1 节 中进行了描述。
napi_create_buffer
新增于: v8.0.0
N-API 版本: 1
napi_status napi_create_buffer(napi_env env,
size_t size,
void** data,
napi_value* result)[in] env: API 调用的环境。[in] size: 底层缓冲区的字节大小。[out] data: 指向底层缓冲区的原始指针。data可以通过传递NULL来可选忽略。[out] result: 代表node::Buffer的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 分配一个 node::Buffer 对象。虽然这仍然是一个完全受支持的数据结构，但在大多数情况下，使用 TypedArray 就足够了。
napi_create_buffer_copy
新增于: v8.0.0
N-API 版本: 1
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] size: 输入缓冲区的字节大小（应与新缓冲区的大小相同）。[in] data: 指向要从中复制的底层缓冲区的原始指针。[out] result_data: 指向新的Buffer的底层数据缓冲区的指针。result_data可以通过传递NULL来可选忽略。[out] result: 代表node::Buffer的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 分配一个 node::Buffer 对象并使用从传入缓冲区复制的数据对其进行初始化。虽然这仍然是一个完全受支持的数据结构，但在大多数情况下，使用 TypedArray 就足够了。
napi_create_date
新增于: v11.11.0, v10.17.0
N-API 版本: 5
napi_status napi_create_date(napi_env env,
double time,
napi_value* result);[in] env: API 调用的环境。[in] time: 自 1970 年 1 月 1 日 UTC 0 时起的毫秒数，表示 ECMAScript 时间值。[out] result: 代表 JavaScriptDate对象的napi_value。
如果 API 调用成功，则返回napi_ok。
此 API 不考虑闰秒；它们被忽略，因为 ECMAScript 与 POSIX 时间规范一致。
此 API 分配一个 JavaScript Date对象。
JavaScript Date对象在 ECMAScript 语言规范的第 20.3 节中进行了描述。
napi_create_external
新增于: v8.0.0
N-API 版本: 1
napi_status napi_create_external(napi_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint,
napi_value* result)[in] env: API 调用的环境。[in] data: 指向外部数据的原始指针。[in] finalize_cb: 当外部值被回收时调用的可选回调函数。napi_finalize提供了更多细节。[in] finalize_hint: 在回收期间传递给 finalize 回调函数的可选提示信息。[out] result: 代表外部值的napi_value。
如果 API 调用成功，则返回napi_ok。
此 API 分配一个附加了外部数据的 JavaScript 值。这用于通过 JavaScript 代码传递外部数据，以便之后可以使用原生代码通过napi_get_value_external检索它。
API 添加一个napi_finalize回调函数，当新创建的 JavaScript 对象被垃圾回收时将调用该回调函数。
创建的值不是对象，因此不支持附加属性。它被认为是一种不同的值类型：使用外部值调用napi_typeof()将产生napi_external。
napi_create_external_arraybuffer
新增于: v8.0.0
N-API 版本: 1
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] external_data:ArrayBuffer底层字节缓冲区的指针。[in] byte_length: 底层缓冲区的字节长度。[in] finalize_cb:ArrayBuffer被回收时调用的可选回调函数。napi_finalize提供更多细节。[in] finalize_hint: 回收期间传递给 finalize 回调函数的可选提示信息。[out] result: 代表 JavaScriptArrayBuffer的napi_value。
如果 API 调用成功，则返回napi_ok。
除 Node.js 之外的一些运行时已放弃对外部缓冲区的支持。在 Node.js 以外的运行时，此方法可能返回napi_no_external_buffers_allowed以指示不支持外部缓冲区。Electron 就是这样一个运行时，如electron/issues/35801中所述。
为了保持与所有运行时的最广泛兼容性，您可以在包含 node-api 头文件之前，在您的 addon 中定义NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED。这样做会隐藏创建外部缓冲区的两个函数。这将确保如果您意外使用这些方法之一，则会发生编译错误。
此 API 返回对应于 JavaScript ArrayBuffer的 Node-API 值。ArrayBuffer的底层字节缓冲区是外部分配和管理的。调用者必须确保字节缓冲区在调用 finalize 回调函数之前保持有效。
API 添加了一个napi_finalize回调函数，该函数将在刚刚创建的 JavaScript 对象被垃圾回收时调用。
JavaScript ArrayBuffer在 ECMAScript 语言规范的第 24.1 节中进行了描述。
napi_create_external_buffer
新增于：v8.0.0
N-API 版本：1
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] length: 输入缓冲区的字节大小（应与新缓冲区的大小相同）。[in] data: 指向底层缓冲区的原始指针，用于暴露给 JavaScript。[in] finalize_cb:ArrayBuffer被回收时调用的可选回调函数。napi_finalize提供更多详细信息。[in] finalize_hint: 回收期间传递给 finalize 回调函数的可选提示信息。[out] result: 代表node::Buffer的napi_value。
如果 API 成功，则返回 napi_ok。
除 Node.js 之外的某些运行时已放弃对外部缓冲区的支持。在 Node.js 以外的运行时中，此方法可能会返回 napi_no_external_buffers_allowed 以指示不支持外部缓冲区。Electron 就是这样一个运行时，如 此问题 electron/issues/35801 中所述。
为了保持与所有运行时的最大兼容性，您可以在包含 node-api 头文件之前，在您的附加组件中定义 NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED。这样做会隐藏创建外部缓冲区的两个函数。这将确保如果您意外使用这些方法之一，则会发生编译错误。
此 API 分配一个 node::Buffer 对象并使用传入缓冲区支持的数据对其进行初始化。虽然这仍然是一个完全支持的数据结构，但在大多数情况下，使用 TypedArray 就足够了。
该 API 添加了一个 napi_finalize 回调函数，该函数将在刚刚创建的 JavaScript 对象被垃圾回收时调用。
对于 Node.js >=4，Buffers 是 Uint8Array。
napi_create_object
新增于：v8.0.0
N-API 版本：1
napi_status napi_create_object(napi_env env, napi_value* result)[in] env: API 调用的环境。[out] result: 代表 JavaScriptObject的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 分配一个默认的 JavaScript Object。它等同于在 JavaScript 中执行 new Object()。
JavaScript Object 类型在 ECMAScript 语言规范的 第 6.1.7 节 中有描述。
napi_create_symbol
新增于：v8.0.0
N-API 版本：1
napi_status napi_create_symbol(napi_env env,
napi_value description,
napi_value* result)[in] env: API 调用的环境。[in] description: 可选的napi_value，引用一个 JavaScriptstring，将其设置为符号的描述。[out] result: 代表 JavaScriptsymbol的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 从 UTF8 编码的 C 字符串创建一个 JavaScript symbol 值。
JavaScript symbol 类型在 ECMAScript 语言规范的 第 19.4 节 中有描述。
node_api_symbol_for
新增于: v17.5.0, v16.15.0
N-API 版本: 9
napi_status node_api_symbol_for(napi_env env,
const char* utf8description,
size_t length,
napi_value* result)[in] env: API 调用的环境。[in] utf8description: 表示用作符号描述的文本的 UTF-8 C 字符串。[in] length: 描述字符串的长度（以字节为单位），如果它是以 null 结尾的，则为NAPI_AUTO_LENGTH。[out] result: 表示 JavaScriptsymbol的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 在全局注册表中搜索具有给定描述的现有符号。如果符号已存在，则将返回该符号；否则，将在注册表中创建一个新符号。
JavaScript symbol 类型在 ECMAScript 语言规范的 第 19.4 节 中进行了描述。
napi_create_typedarray
新增于: v8.0.0
N-API 版本: 1
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] type:TypedArray中元素的标量数据类型。[in] length:TypedArray中元素的数量。[in] arraybuffer:TypedArray的基础ArrayBuffer。[in] byte_offset:ArrayBuffer中开始投影TypedArray的字节偏移量。[out] result: 代表 JavaScriptTypedArray的napi_value。
如果 API 成功，则返回napi_ok。
此 API 在现有的ArrayBuffer上创建一个 JavaScript TypedArray对象。TypedArray对象提供了一个对底层数据缓冲区的类似数组的视图，其中每个元素具有相同的底层二进制标量数据类型。
要求(length * size_of_element) + byte_offset应该<=传入数组的字节大小。否则，将引发RangeError异常。
JavaScript TypedArray对象在 ECMAScript 语言规范的第 22.2 节中进行了描述。
node_api_create_buffer_from_arraybuffer
新增于：v23.0.0
napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
napi_value arraybuffer,
size_t byte_offset,
size_t byte_length,
napi_value* result)[in] env: API 调用的环境。[in] arraybuffer: 用于创建缓冲区的ArrayBuffer。[in] byte_offset: 在ArrayBuffer中创建缓冲区起始的字节偏移量。[in] byte_length: 从ArrayBuffer创建的缓冲区的字节长度。[out] result: 代表已创建的 JavaScriptBuffer对象的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 从现有的 ArrayBuffer 创建一个 JavaScript Buffer 对象。Buffer 对象是 Node.js 特有的类，提供了一种直接在 JavaScript 中处理二进制数据的方法。
字节范围 [byte_offset, byte_offset + byte_length) 必须在 ArrayBuffer 的范围内。如果 byte_offset + byte_length 超过了 ArrayBuffer 的大小，则会引发 RangeError 异常。
napi_create_dataview
新增于: v8.3.0
N-API 版本: 1
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] length:DataView中元素的数量。[in] arraybuffer:DataView底层的ArrayBuffer。[in] byte_offset:DataView投影开始的ArrayBuffer内的字节偏移量。[out] result: 表示 JavaScriptDataView的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 在现有的 ArrayBuffer 上创建一个 JavaScript DataView 对象。DataView 对象提供对底层数据缓冲区的类似数组的视图，但是允许在 ArrayBuffer 中使用不同大小和类型的项。
要求 byte_length + byte_offset 小于或等于传入数组的字节大小。否则，将引发 RangeError 异常。
JavaScript DataView 对象在 ECMAScript 语言规范的 第 24.3 节 中进行了描述。
从 C 类型转换为 Node-API 的函数
napi_create_int32
新增于：v8.4.0
N-API 版本：1
napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)[in] env: API 所在的环境。[in] value: 需要在 JavaScript 中表示的整数值。[out] result: 代表 JavaScriptnumber的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 用于将 C int32_t 类型转换为 JavaScript number 类型。
JavaScript number 类型在 ECMAScript 语言规范的 第 6.1.6 节 中有描述。
napi_create_uint32
新增于：v8.4.0
N-API 版本：1
napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)[in] env: API 所在的环境。[in] value: 需要在 JavaScript 中表示的无符号整数值。[out] result: 代表 JavaScriptnumber的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 用于将 C uint32_t 类型转换为 JavaScript number 类型。
JavaScript number 类型在 ECMAScript 语言规范的 第 6.1.6 节 中有描述。
napi_create_int64
新增于: v8.4.0
N-API 版本: 1
napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)[in] env: API 调用的环境。[in] value: 需要在 JavaScript 中表示的整数值。[out] result: 表示 JavaScriptnumber的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 用于将 C 的 int64_t 类型转换为 JavaScript 的 number 类型。
JavaScript 的 number 类型在 ECMAScript 语言规范的 第 6.1.6 节 中有描述。请注意，JavaScript 无法完全精确地表示 int64_t 的完整范围。位于 Number.MIN_SAFE_INTEGER -(2**53 - 1) 到 Number.MAX_SAFE_INTEGER (2**53 - 1) 范围之外的整数值将丢失精度。
napi_create_double
新增于: v8.4.0
N-API 版本: 1
napi_status napi_create_double(napi_env env, double value, napi_value* result)[in] env: API 调用的环境。[in] value: 需要在 JavaScript 中表示的双精度值。[out] result: 表示 JavaScriptnumber的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 用于将 C 的 double 类型转换为 JavaScript 的 number 类型。
JavaScript 的 number 类型在 ECMAScript 语言规范的 第 6.1.6 节 中有描述。
napi_create_bigint_int64
新增于: v10.7.0
N-API 版本: 6
napi_status napi_create_bigint_int64(napi_env env,
int64_t value,
napi_value* result);[in] env: API 调用的环境。[in] value: 需要在 JavaScript 中表示的整数值。[out] result: 表示 JavaScriptBigInt的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 将 C 的 int64_t 类型转换为 JavaScript 的 BigInt 类型。
napi_create_bigint_uint64
新增于: v10.7.0
N-API 版本: 6
napi_status napi_create_bigint_uint64(napi_env env,
uint64_t value,
napi_value* result);[in] env: API 调用的环境。[in] value: 需要转换为 JavaScript 数值的无符号整数。[out] result: 代表 JavaScriptBigInt的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 将 C 的 uint64_t 类型转换为 JavaScript 的 BigInt 类型。
napi_create_bigint_words
新增于: v10.7.0
N-API 版本: 6
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] sign_bit: 决定生成的BigInt是正数还是负数。[in] word_count:words数组的长度。[in] words:uint64_t小端序 64 位字的数组。[out] result: 代表 JavaScriptBigInt的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 将无符号 64 位字的数组转换为单个 BigInt 值。
生成的 BigInt 计算方式为： (–1)sign_bit (words[0] × (264)0 + words[1] × (264)1 + …)
napi_create_string_latin1
新增于: v8.0.0
N-API 版本: 1
napi_status napi_create_string_latin1(napi_env env,
const char* str,
size_t length,
napi_value* result);[in] env: API 调用的环境。[in] str: 表示 ISO-8859-1 编码字符串的字符缓冲区。[in] length: 字符串的字节长度，如果字符串以 null 结尾，则为NAPI_AUTO_LENGTH。[out] result: 代表 JavaScriptstring的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 从 ISO-8859-1 编码的 C 字符串创建一个 JavaScript string 值。本机字符串会被复制。
JavaScript string 类型在 ECMAScript 语言规范的 第 6.1.4 节 中进行了描述。
node_api_create_external_string_latin1
新增于: v20.4.0, v18.18.0
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] str: 表示 ISO-8859-1 编码字符串的字符缓冲区。[in] length: 字符串的字节长度，如果字符串以 null 结尾，则为NAPI_AUTO_LENGTH。[in] finalize_callback: 当字符串被回收时调用的函数。该函数将使用以下参数调用：[in] env: 插件运行的环境。如果字符串作为工作线程或主 Node.js 实例终止的一部分被回收，则此值可能为 null。[in] data: 这是str作为void*指针的值。[in] finalize_hint: 这是传递给 API 的finalize_hint值。napi_finalize提供了更多细节。此参数是可选的。传递 null 值表示当相应的 JavaScript 字符串被回收时，不需要通知插件。
[in] finalize_hint: 传递给回收期间最终回调的可选提示。[out] result: 代表 JavaScriptstring的napi_value。[out] copied: 字符串是否被复制。如果被复制，则最终化器将已经被调用以销毁str。
如果 API 成功，则返回 napi_ok。
此 API 从 ISO-8859-1 编码的 C 字符串创建一个 JavaScript string 值。本机字符串可能不会被复制，因此必须存在于 JavaScript 值的整个生命周期中。
JavaScript string 类型在 ECMAScript 语言规范的 第 6.1.4 节 中进行了描述。
napi_create_string_utf16
新增于: v8.0.0
N-API 版本: 1
napi_status napi_create_string_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result)[in] env: API 调用的环境。[in] str: 表示 UTF16-LE 编码字符串的字符缓冲区。[in] length: 字符串的长度（以双字节代码单元为单位），如果字符串以 null 结尾，则为NAPI_AUTO_LENGTH。[out] result: 代表 JavaScriptstring的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 根据 UTF16-LE 编码的 C 字符串创建一个 JavaScript string 值。原生字符串会被复制。
JavaScript string 类型在 ECMAScript 语言规范的第 6.1.4 节中进行了描述。
node_api_create_external_string_utf16
新增于: v20.4.0, v18.18.0
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] str: 表示 UTF16-LE 编码字符串的字符缓冲区。[in] length: 字符串的长度（以双字节代码单元为单位），如果字符串以 null 结尾，则为NAPI_AUTO_LENGTH。[in] finalize_callback: 当字符串被回收时调用的函数。该函数将使用以下参数调用：[in] env: 插件运行的环境。如果字符串作为工作线程或主 Node.js 实例的终止的一部分被回收，此值可能为 null。[in] data:str的值，作为void*指针。[in] finalize_hint: 传递给 API 的finalize_hint值。napi_finalize提供了更多细节。此参数是可选的。传递 null 值表示当相应的 JavaScript 字符串被回收时，不需要通知插件。
[in] finalize_hint: 传递给回收期间的 finalize 回调的可选提示。[out] result: 代表 JavaScriptstring的napi_value。[out] copied: 字符串是否被复制。如果是，则最终确定器将已经被调用以销毁str。
如果 API 成功，则返回 napi_ok。
此 API 根据 UTF16-LE 编码的 C 字符串创建一个 JavaScript string 值。原生字符串可能不会被复制，因此必须在 JavaScript 值的整个生命周期中存在。
JavaScript string 类型在 ECMAScript 语言规范的第 6.1.4 节中进行了描述。
napi_create_string_utf8
新增于: v8.0.0
N-API 版本: 1
napi_status napi_create_string_utf8(napi_env env,
const char* str,
size_t length,
napi_value* result)[in] env: API 调用的环境。[in] str: 代表 UTF8 编码字符串的字符缓冲区。[in] length: 字符串的字节长度，如果字符串以 null 结尾，则为NAPI_AUTO_LENGTH。[out] result: 代表 JavaScriptstring的napi_value。
如果 API 成功，则返回napi_ok。
此 API 从 UTF8 编码的 C 字符串创建一个 JavaScript string 值。原生字符串会被复制。
JavaScript string 类型在 ECMAScript 语言规范的第 6.1.4 节中有所描述。
用于创建优化属性键的函数
包括 V8 在内的许多 JavaScript 引擎都使用内部字符串作为键来设置和获取属性值。它们通常使用哈希表来创建和查找此类字符串。虽然这会增加每个键创建的一些成本，但它通过启用字符串指针的比较而不是整个字符串的比较来提高后续性能。
如果新的 JavaScript 字符串旨在用作属性键，那么对于某些 JavaScript 引擎来说，使用本节中的函数将更高效。否则，请使用napi_create_string_utf8或node_api_create_external_string_utf8系列函数，因为使用属性键创建方法创建/存储字符串可能会产生额外的开销。
node_api_create_property_key_latin1
新增于：v22.9.0, v20.18.0
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] str: 表示 ISO-8859-1 编码字符串的字符缓冲区。[in] length: 字符串的字节长度，如果字符串以 null 结尾，则为NAPI_AUTO_LENGTH。[out] result: 一个napi_value，表示一个优化的 JavaScriptstring，用作对象的属性键。
如果 API 成功，则返回 napi_ok。
此 API 从 ISO-8859-1 编码的 C 字符串创建一个优化的 JavaScript string 值，用作对象的属性键。原生字符串会被复制。与 napi_create_string_latin1 相反，使用相同 str 指针对该函数的后续调用可能会受益于创建请求的 napi_value 的速度提升，具体取决于引擎。
JavaScript string 类型在 ECMAScript 语言规范的第 6.1.4 节中进行了描述。
node_api_create_property_key_utf16
新增于: v21.7.0, v20.12.0
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] str: 表示 UTF16-LE 编码字符串的字符缓冲区。[in] length: 字符串的长度（以双字节代码单元计），如果字符串以 null 结尾，则为NAPI_AUTO_LENGTH。[out] result: 一个napi_value，表示一个优化的 JavaScriptstring，用作对象的属性键。
如果 API 成功，则返回napi_ok。
此 API 从 UTF16-LE 编码的 C 字符串创建一个优化的 JavaScript string 值，用作对象的属性键。原生字符串会被复制。
JavaScript string 类型在 ECMAScript 语言规范的第 6.1.4 节中进行了描述。
node_api_create_property_key_utf8
新增于: v22.9.0, v20.18.0
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] str: 表示 UTF8 编码字符串的字符缓冲区。[in] length: 字符串的长度（以双字节代码单元为单位），如果字符串以 null 结尾，则为NAPI_AUTO_LENGTH。[out] result: 一个napi_value，表示一个优化的 JavaScriptstring，用作对象的属性键。
如果 API 成功，则返回napi_ok。
此 API 从 UTF8 编码的 C 字符串创建一个优化的 JavaScript string 值，用作对象的属性键。原生字符串会被复制。
JavaScript string 类型在 ECMAScript 语言规范的第 6.1.4 节中进行了描述。
从 Node-API 到 C 类型转换的函数
napi_get_array_length
新增于：v8.0.0
N-API 版本：1
napi_status napi_get_array_length(napi_env env,
napi_value value,
uint32_t* result)[in] env: API 调用的环境。[in] value: 代表 JavaScriptArray的napi_value，其长度正在被查询。[out] result: 代表数组长度的uint32。
如果 API 成功，则返回 napi_ok。
此 API 返回数组的长度。
Array 长度在 ECMAScript 语言规范的 第 22.1.4.1 节 中有描述。
napi_get_arraybuffer_info
新增于：v8.0.0
N-API 版本：1
napi_status napi_get_arraybuffer_info(napi_env env,
napi_value arraybuffer,
void** data,
size_t* byte_length)[in] env: API 调用的环境。[in] arraybuffer: 代表正在被查询的ArrayBuffer的napi_value。[out] data:ArrayBuffer的底层数据缓冲区。如果byte_length为0，则此值可能为NULL或任何其他指针值。[out] byte_length: 底层数据缓冲区的长度（字节）。
如果 API 成功，则返回 napi_ok。
此 API 用于检索 ArrayBuffer 的底层数据缓冲区及其长度。
警告：使用此 API 时需谨慎。即使底层数据缓冲区返回后，其生命周期仍由 ArrayBuffer 管理。安全使用此 API 的一种方法是结合使用 napi_create_reference，这可以用来保证对 ArrayBuffer 生命周期 的控制。只要没有调用可能触发 GC 的其他 API，在同一个回调中使用返回的数据缓冲区也是安全的。
napi_get_buffer_info
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_buffer_info(napi_env env,
napi_value value,
void** data,
size_t* length)[in] env: API 调用所在的运行环境。[in] value: 代表被查询的node::Buffer或Uint8Array的napi_value。[out] data:node::Buffer或Uint8Array的底层数据缓冲区。如果长度为0，这可能是NULL或任何其他指针值。[out] length: 底层数据缓冲区的长度（字节）。
如果 API 成功，则返回 napi_ok。
此方法返回与 napi_get_typedarray_info 相同的 data 和 byte_length。并且 napi_get_typedarray_info 也接受 node::Buffer（一个 Uint8Array）作为值。
此 API 用于检索 node::Buffer 的底层数据缓冲区及其长度。
警告: 使用此 API 时需谨慎，因为如果底层数据缓冲区由 VM 管理，则其生命周期无法保证。
napi_get_prototype
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_prototype(napi_env env,
napi_value object,
napi_value* result)[in] env: API 调用的环境。[in] object: 代表 JavaScriptObject的napi_value，用于返回其原型。这返回等效于Object.getPrototypeOf的结果（与函数的prototype属性不同）。[out] result: 代表给定对象原型的napi_value。
如果 API 成功，则返回 napi_ok。
napi_get_typedarray_info
新增于: v8.0.0
N-API 版本: 1
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] typedarray: 代表TypedArray的napi_value，用于查询其属性。[out] type:TypedArray中元素的标量数据类型。[out] length:TypedArray中元素的数量。[out] data:TypedArray底层的缓冲区数据，已根据byte_offset值调整，指向TypedArray中的第一个元素。如果数组长度为0，则可能是NULL或任何其他指针值。[out] arraybuffer:TypedArray底层的ArrayBuffer。[out] byte_offset: 底层原生数组中第一个元素所在的字节偏移量。data参数的值已调整，因此data指向数组的第一个元素。因此，原生数组的第一个字节位于data - byte_offset。
如果 API 成功，则返回 napi_ok。
此 API 返回类型数组的各种属性。
如果不需要某个属性，则其对应的输出参数可以为 NULL。
警告: 使用此 API 时要谨慎，因为底层数据缓冲区由虚拟机管理。
napi_get_dataview_info
新增于: v8.3.0
N-API 版本: 1
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] dataview: 表示需要查询其属性的DataView的napi_value。[out] byte_length:DataView中的字节数。[out] data:DataView底层的 数据缓冲区。如果byte_length为0，则此值可以为NULL或任何其他指针值。[out] arraybuffer:DataView底层的ArrayBuffer。[out] byte_offset: 数据缓冲区中DataView开始投影的字节偏移量。
如果 API 成功，则返回 napi_ok。
如果不需要某个输出参数的属性，则可以将其设置为 NULL。
此 API 返回 DataView 的各种属性。
napi_get_date_value
新增于: v11.11.0, v10.17.0
N-API 版本: 5
napi_status napi_get_date_value(napi_env env,
napi_value value,
double* result)[in] env: API 调用的环境。[in] value: 代表 JavaScriptDate对象的napi_value。[out] result: 时间值，以double类型表示，单位为自 1970 年 1 月 1 日 0 时 0 分 0 秒 UTC 以来经过的毫秒数。
此 API 不考虑闰秒；它们被忽略，因为 ECMAScript 与 POSIX 时间规范一致。
如果 API 成功，则返回 napi_ok。如果传入的不是日期 napi_value，则返回 napi_date_expected。
此 API 返回给定 JavaScript Date 对象的时间值的 C double 原生类型。
napi_get_value_bool
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)[in] env: API 调用的环境。[in] value: 代表 JavaScriptBoolean对象的napi_value。[out] result: 给定 JavaScriptBoolean对象等效的 C 布尔值原生类型。
如果 API 成功，则返回 napi_ok。如果传入的不是布尔值 napi_value，则返回 napi_boolean_expected。
此 API 返回给定 JavaScript Boolean 对象等效的 C 布尔值原生类型。
napi_get_value_double
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_value_double(napi_env env,
napi_value value,
double* result)[in] env: API 调用的环境。[in] value: 代表 JavaScriptnumber的napi_value。[out] result: 给定 JavaScriptnumber的 C 双精度浮点数等效值。
如果 API 成功，则返回 napi_ok。如果传入非数字 napi_value，则返回 napi_number_expected。
此 API 返回给定 JavaScript number 的 C 双精度浮点数等效值。
napi_get_value_bigint_int64
新增于: v10.7.0
N-API 版本: 6
napi_status napi_get_value_bigint_int64(napi_env env,
napi_value value,
int64_t* result,
bool* lossless);[in] env: API 调用的环境。[in] value: 代表 JavaScriptBigInt的napi_value。[out] result: 给定 JavaScriptBigInt的 Cint64_t等效值。[out] lossless: 指示BigInt值是否被无损转换。
如果 API 成功，则返回 napi_ok。如果传入非 BigInt，则返回 napi_bigint_expected。
此 API 返回给定 JavaScript BigInt 的 C int64_t 等效值。如果需要，它将截断值，并将 lossless 设置为 false。
napi_get_value_bigint_uint64
新增于：v10.7.0
N-API 版本：6
napi_status napi_get_value_bigint_uint64(napi_env env,
napi_value value,
uint64_t* result,
bool* lossless);[in] env: API 调用的环境。[in] value: 代表 JavaScriptBigInt的napi_value。[out] result: 给定 JavaScriptBigInt的 Cuint64_t原生等价值。[out] lossless: 指示BigInt值是否被无损转换。
如果 API 成功，则返回 napi_ok。如果传入的不是 BigInt，则返回 napi_bigint_expected。
此 API 返回给定 JavaScript BigInt 的 C uint64_t 原生等价值。如果需要，它将截断值，并将 lossless 设置为 false。
napi_get_value_bigint_words
新增于：v10.7.0
N-API 版本：6
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] value: 代表 JavaScriptBigInt的napi_value。[out] sign_bit: 表示 JavaScriptBigInt是正数还是负数的整数。[in/out] word_count: 必须初始化为words数组的长度。返回时，它将设置为存储此BigInt所需的实际字数。[out] words: 指向预分配的 64 位字数组的指针。
如果 API 成功，则返回 napi_ok。
此 API 将单个 BigInt 值转换为符号位、64 位小端序数组以及数组中的元素数量。为了只获取 word_count，sign_bit 和 words 都可以设置为 NULL。
napi_get_value_external
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_value_external(napi_env env,
napi_value value,
void** result)[in] env: API 调用的环境。[in] value: 代表 JavaScript 外部值的napi_value。[out] result: JavaScript 外部值包装的数据指针。
如果 API 成功，则返回 napi_ok。如果传入非外部 napi_value，则返回 napi_invalid_arg。
此 API 获取之前传递给 napi_create_external() 的外部数据指针。
napi_get_value_int32
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_value_int32(napi_env env,
napi_value value,
int32_t* result)[in] env: API 调用的环境。[in] value: 代表 JavaScriptnumber的napi_value。[out] result: 给定 JavaScriptnumber的 Cint32原始等效值。
如果 API 成功，则返回 napi_ok。如果传入非数字 napi_value，则返回 napi_number_expected。
此 API 返回给定 JavaScript number 的 C int32 原始等效值。
如果数字超过 32 位整数的范围，则结果将被截断为底部 32 位的等效值。如果值 > 231 - 1，则这可能导致很大的正数变成负数。
非有限数值 (NaN、+Infinity 或 -Infinity) 将结果设置为零。
napi_get_value_int64
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_value_int64(napi_env env,
napi_value value,
int64_t* result)[in] env: API 调用的环境。[in] value: 代表 JavaScriptnumber的napi_value。[out] result: 给定 JavaScriptnumber的 Cint64原生类型等价物。
如果 API 成功，则返回 napi_ok。如果传入非数字 napi_value，则返回 napi_number_expected。
此 API 返回给定 JavaScript number 的 C int64 原生类型等价物。
超出 Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) 范围的 number 值将丢失精度。
非有限数值 (NaN, +Infinity 或 -Infinity) 将结果设置为零。
napi_get_value_string_latin1
新增于: v8.0.0
N-API 版本: 1
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] value: 代表 JavaScript 字符串的napi_value。[in] buf: 将 ISO-8859-1 编码的字符串写入的缓冲区。如果传入NULL，则字符串的长度（以字节为单位，不包括空终止符）将返回到result中。[in] bufsize: 目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以 null 结尾。[out] result: 复制到缓冲区的字节数（不包括空终止符）。
如果 API 成功，则返回 napi_ok。如果传入非 string napi_value，则返回 napi_string_expected。
此 API 返回与传入的值相对应的 ISO-8859-1 编码的字符串。
napi_get_value_string_utf8
新增于: v8.0.0
N-API 版本: 1
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] value: 代表 JavaScript 字符串的napi_value。[in] buf: 用于写入 UTF8 编码字符串的缓冲区。如果传入NULL，则字符串的长度（以字节为单位，不包括空终止符）将返回到result中。[in] bufsize: 目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以 null 结尾。[out] result: 复制到缓冲区中的字节数（不包括空终止符）。
如果 API 成功，则返回 napi_ok。如果传入非 string napi_value，则返回 napi_string_expected。
此 API 返回与传入的值对应的 UTF8 编码字符串。
napi_get_value_string_utf16
新增于: v8.0.0
N-API 版本: 1
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] value: 代表 JavaScript 字符串的napi_value。[in] buf: 用于写入 UTF16-LE 编码字符串的缓冲区。如果传入NULL，则返回字符串的长度（以 2 字节代码单元为单位，不包括空终止符）。[in] bufsize: 目标缓冲区的大小。如果此值不足，则返回的字符串将被截断并以 null 结尾。[out] result: 复制到缓冲区的 2 字节代码单元数（不包括空终止符）。
如果 API 成功，则返回 napi_ok。如果传入非 string 的 napi_value，则返回 napi_string_expected。
此 API 返回与传入的值对应的 UTF16 编码字符串。
napi_get_value_uint32
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_value_uint32(napi_env env,
napi_value value,
uint32_t* result)[in] env: API 调用的环境。[in] value: 代表 JavaScriptnumber的napi_value。[out] result: 给定napi_value的 C 原始类型等价物，为uint32_t类型。
如果 API 成功，则返回 napi_ok。如果传入非数字 napi_value，则返回 napi_number_expected。
此 API 返回给定 napi_value 的 C 原始类型等价物，为 uint32_t 类型。
获取全局实例的函数
napi_get_boolean
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)[in] env: API 调用的环境。[in] value: 要检索的布尔值。[out] result: 代表要检索的 JavaScriptBoolean单例的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 用于返回用于表示给定布尔值的 JavaScript 单例对象。
napi_get_global
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_global(napi_env env, napi_value* result)[in] env: API 调用的环境。[out] result: 代表 JavaScriptglobal对象的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 返回 global 对象。
napi_get_null
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_null(napi_env env, napi_value* result)[in] env: API 调用的环境。[out] result: 代表 JavaScriptnull对象的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 返回 null 对象。
napi_get_undefined
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_undefined(napi_env env, napi_value* result)[in] env: API 调用的环境。[out] result: 代表 JavaScript Undefined 值的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 返回 Undefined 对象。
使用 JavaScript 值和抽象操作
Node-API 提供了一组 API 来对 JavaScript 值执行一些抽象操作。其中一些操作在 第 7 节 的 ECMAScript 语言规范 中有说明。
这些 API 支持执行以下操作之一：
napi_coerce_to_bool
新增于：v8.0.0
N-API 版本：1
napi_status napi_coerce_to_bool(napi_env env,
napi_value value,
napi_value* result)[in] env: API 调用的环境。[in] value: 要强制转换的 JavaScript 值。[out] result: 代表强制转换后的 JavaScriptBoolean的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 实现抽象操作 ToBoolean()，其定义在 ECMAScript 语言规范的 第 7.1.2 节 中。
napi_coerce_to_number
新增于: v8.0.0
N-API 版本: 1
napi_status napi_coerce_to_number(napi_env env,
napi_value value,
napi_value* result)[in] env: API 调用的环境。[in] value: 要强制转换的 JavaScript 值。[out] result: 代表强制转换后的 JavaScriptnumber的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 实现抽象操作 ToNumber()，其定义在 ECMAScript 语言规范的 第 7.1.3 节。如果传入的值是对象，此函数可能会运行 JS 代码。
napi_coerce_to_object
新增于: v8.0.0
N-API 版本: 1
napi_status napi_coerce_to_object(napi_env env,
napi_value value,
napi_value* result)[in] env: API 调用的环境。[in] value: 要强制转换的 JavaScript 值。[out] result: 代表强制转换后的 JavaScriptObject的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 实现抽象操作 ToObject()，其定义在 ECMAScript 语言规范的 第 7.1.13 节。
napi_coerce_to_string
新增于: v8.0.0
N-API 版本: 1
napi_status napi_coerce_to_string(napi_env env,
napi_value value,
napi_value* result)[in] env: API 调用的环境。[in] value: 要强制转换的 JavaScript 值。[out] result: 代表强制转换后的 JavaScriptstring的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 实现抽象操作 ToString()，其定义在 ECMAScript 语言规范的 第 7.1.13 节。如果传入的值是对象，则此函数可能会运行 JS 代码。
napi_typeof
新增于: v8.0.0
N-API 版本: 1
napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)[in] env: API 调用的环境。[in] value: 要查询类型的 JavaScript 值。[out] result: JavaScript 值的类型。
如果 API 成功，则返回 napi_ok。
- 如果
value的类型不是已知的 ECMAScript 类型且value不是外部值，则返回napi_invalid_arg。
此 API 表示的行为类似于对对象调用 typeof 运算符，其定义在 ECMAScript 语言规范的 第 12.5.5 节。但是，存在一些差异：
如果 value 的类型无效，则返回错误。
napi_instanceof
新增于: v8.0.0
N-API 版本: 1
napi_status napi_instanceof(napi_env env,
napi_value object,
napi_value constructor,
bool* result)[in] env: API 调用的环境。[in] object: 要检查的 JavaScript 值。[in] constructor: 要检查的构造函数的 JavaScript 函数对象。[out] result: 如果object instanceof constructor为真，则设置为 true 的布尔值。
如果 API 成功，则返回 napi_ok。
此 API 表示根据 ECMAScript 语言规范的 第 12.10.4 节 定义，在对象上调用 instanceof 运算符。
napi_is_array
新增于: v8.0.0
N-API 版本: 1
napi_status napi_is_array(napi_env env, napi_value value, bool* result)[in] env: API 调用的环境。[in] value: 要检查的 JavaScript 值。[out] result: 给定对象是否为数组。
如果 API 成功，则返回 napi_ok。
此 API 表示根据 ECMAScript 语言规范的 第 7.2.2 节 定义，在对象上调用 IsArray 操作。
napi_is_arraybuffer
新增于: v8.0.0
N-API 版本: 1
napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)[in] env: API 调用的环境。[in] value: 要检查的 JavaScript 值。[out] result: 给定对象是否为ArrayBuffer。
如果 API 成功，则返回 napi_ok。
此 API 检查传入的 Object 是否为数组缓冲区。
napi_is_buffer
新增于: v8.0.0
N-API 版本: 1
napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)[in] env: API 调用的环境。[in] value: 要检查的 JavaScript 值。[out] result: 给定的napi_value是否代表一个node::Buffer或Uint8Array对象。
如果 API 成功，则返回 napi_ok。
此 API 检查传入的 Object 是否为缓冲区或 Uint8Array。如果调用者需要检查值是否为 Uint8Array，则应优先使用 napi_is_typedarray。
napi_is_date
新增于：v11.11.0, v10.17.0
N-API 版本：5
napi_status napi_is_date(napi_env env, napi_value value, bool* result)[in] env: API 调用的环境。[in] value: 要检查的 JavaScript 值。[out] result: 给定的napi_value是否表示 JavaScriptDate对象。
如果 API 成功，则返回 napi_ok。
此 API 检查传入的 Object 是否为日期。
napi_is_error
新增于：v8.0.0
N-API 版本：1
napi_status napi_is_error(napi_env env, napi_value value, bool* result)[in] env: API 调用的环境。[in] value: 要检查的 JavaScript 值。[out] result: 给定的napi_value是否表示Error对象。
如果 API 成功，则返回 napi_ok。
此 API 检查传入的 Object 是否为错误。
napi_is_typedarray
新增于：v8.0.0
N-API 版本：1
napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)[in] env: API 调用的环境。[in] value: 要检查的 JavaScript 值。[out] result: 给定的napi_value是否表示TypedArray。
如果 API 成功，则返回 napi_ok。
此 API 检查传入的 Object 是否为类型化数组。
napi_is_dataview
新增于: v8.3.0
N-API 版本: 1
napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)[in] env: API 调用所在的运行环境。[in] value: 要检查的 JavaScript 值。[out] result: 给定的napi_value是否表示一个DataView。
如果 API 成功，则返回 napi_ok。
此 API 检查传入的 Object 是否为 DataView。
napi_strict_equals
新增于: v8.0.0
N-API 版本: 1
napi_status napi_strict_equals(napi_env env,
napi_value lhs,
napi_value rhs,
bool* result)[in] env: API 调用所在的运行环境。[in] lhs: 要检查的 JavaScript 值。[in] rhs: 要比较的 JavaScript 值。[out] result: 两个napi_value对象是否相等。
如果 API 成功，则返回 napi_ok。
此 API 表示对 ECMAScript 语言规范 第 7.2.14 节 中定义的严格相等算法的调用。
napi_detach_arraybuffer
新增于: v13.0.0, v12.16.0, v10.22.0
N-API 版本: 7
napi_status napi_detach_arraybuffer(napi_env env,
napi_value arraybuffer)[in] env: API 调用的环境。[in] arraybuffer: 要分离的 JavaScriptArrayBuffer。
如果 API 成功，则返回 napi_ok。如果传入不可分离的 ArrayBuffer，则返回 napi_detachable_arraybuffer_expected。
通常，如果 ArrayBuffer 之前已被分离，则它是不可分离的。引擎可能会对 ArrayBuffer 是否可分离施加附加条件。例如，V8 要求 ArrayBuffer 为外部的，即使用 napi_create_external_arraybuffer 创建的。
此 API 表示对 ECMAScript 语言规范 第 24.1.1.3 节 中定义的 ArrayBuffer 分离操作的调用。
napi_is_detached_arraybuffer
新增于：v13.3.0, v12.16.0, v10.22.0
N-API 版本：7
napi_status napi_is_detached_arraybuffer(napi_env env,
napi_value arraybuffer,
bool* result)[in] env: API 调用的环境。[in] arraybuffer: 要检查的 JavaScriptArrayBuffer。[out] result:arraybuffer是否已分离。
如果 API 成功，则返回 napi_ok。
如果 ArrayBuffer 的内部数据为 null，则认为它已分离。
此 API 表示对 ECMAScript 语言规范 第 24.1.1.2 节 中定义的 ArrayBuffer IsDetachedBuffer 操作的调用。
使用 JavaScript 属性
Node-API 提供了一组 API 来获取和设置 JavaScript 对象上的属性。其中一些类型在 ECMAScript 语言规范 的 第 7 节 中有文档记录。
JavaScript 中的属性表示为键值对。从根本上说，Node-API 中的所有属性键都可以用以下形式表示：
- 命名：简单的 UTF8 编码字符串
- 整数索引：由
uint32_t表示的索引值 - JavaScript 值：在 Node-API 中由
napi_value表示。这可以是表示string、number或symbol的napi_value。
Node-API 值由类型 napi_value 表示。任何需要 JavaScript 值的 Node-API 调用都会传入 napi_value。但是，确保所讨论的 napi_value 是 API 预期的 JavaScript 类型是调用者的责任。
本节中记录的 API 提供了一个简单的接口来获取和设置由 napi_value 表示的任意 JavaScript 对象上的属性。
例如，考虑以下 JavaScript 代码片段：
const obj = {}
obj.myProp = 123可以使用 Node-API 值通过以下代码片段实现等效功能：
napi_status status = napi_generic_failure;
// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// Create a napi_value for 123
status = napi_create_int32(env, 123, &value);
if (status != napi_ok) return status;
// obj.myProp = 123
status = napi_set_named_property(env, obj, "myProp", value);
if (status != napi_ok) return status;可以以类似的方式设置索引属性。考虑以下 JavaScript 代码片段：
const arr = []
arr[123] = 'hello'可以使用 Node-API 值通过以下代码片段实现等效功能：
napi_status status = napi_generic_failure;
// const arr = [];
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;
// Create a napi_value for 'hello'
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &value);
if (status != napi_ok) return status;
// arr[123] = 'hello';
status = napi_set_element(env, arr, 123, value);
if (status != napi_ok) return status;可以使用本节中描述的 API 获取属性。考虑以下 JavaScript 代码片段：
const arr = []
const value = arr[123]以下是 Node-API 对应部分的近似等效项：
napi_status status = napi_generic_failure;
// const arr = []
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;
// const value = arr[123]
status = napi_get_element(env, arr, 123, &value);
if (status != napi_ok) return status;最后，出于性能原因，还可以在对象上定义多个属性。考虑以下 JavaScript 代码：
const obj = {}
Object.defineProperties(obj, {
foo: { value: 123, writable: true, configurable: true, enumerable: true },
bar: { value: 456, writable: true, configurable: true, enumerable: true },
})以下是 Node-API 对应部分的近似等效项：
napi_status status = napi_status_generic_failure;
// const obj = {};
napi_value obj;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;
// Create napi_values for 123 and 456
napi_value fooValue, barValue;
status = napi_create_int32(env, 123, &fooValue);
if (status != napi_ok) return status;
status = napi_create_int32(env, 456, &barValue);
if (status != napi_ok) return status;
// Set the properties
napi_property_descriptor descriptors[] = {
{ "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },
{ "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }
}
status = napi_define_properties(env,
obj,
sizeof(descriptors) / sizeof(descriptors[0]),
descriptors);
if (status != napi_ok) return status;结构体
napi_property_attributes
[历史]
| 版本 | 变更 |
|---|---|
| v14.12.0 | 新增 napi_default_method 和 napi_default_property。 |
typedef enum {
napi_default = 0,
napi_writable = 1 << 0,
napi_enumerable = 1 << 1,
napi_configurable = 1 << 2,
// 用于 napi_define_class 区分静态属性和实例属性。napi_define_properties 会忽略此标志。
napi_static = 1 << 10,
// 类方法的默认值。
napi_default_method = napi_writable | napi_configurable,
// 对象属性的默认值，例如在 JS 中的 obj[prop]。
napi_default_jsproperty = napi_writable |
napi_enumerable |
napi_configurable,
} napi_property_attributes;napi_property_attributes 是用于控制设置在 JavaScript 对象上的属性行为的标志。除了 napi_static 之外，它们对应于 ECMAScript 语言规范 的 第 6.1.7.1 节 中列出的属性。它们可以是以下一个或多个位标志：
napi_default: 属性未设置显式属性。默认情况下，属性是只读的、不可枚举的且不可配置的。napi_writable: 属性是可写的。napi_enumerable: 属性是可枚举的。napi_configurable: 属性是可配置的，如 ECMAScript 语言规范 的 第 6.1.7.1 节 中所定义的。napi_static: 属性将被定义为类的静态属性，而不是实例属性（这是默认值）。这仅由napi_define_class使用。napi_define_properties会忽略它。napi_default_method: 像 JS 类中的方法一样，属性是可配置的和可写的，但不可枚举的。napi_default_jsproperty: 像在 JavaScript 中通过赋值设置的属性一样，属性是可写的、可枚举的和可配置的。
napi_property_descriptor
typedef struct {
// `utf8name` 或 `name` 中只有一个可以为 NULL。
const char* utf8name;
napi_value name;
napi_callback method;
napi_callback getter;
napi_callback setter;
napi_value value;
napi_property_attributes attributes;
void* data;
} napi_property_descriptor;utf8name：可选字符串，描述属性的键，使用 UTF8 编码。属性必须提供utf8name或name之一。name：可选napi_value，指向用作属性键的 JavaScript 字符串或符号。属性必须提供utf8name或name之一。value：如果属性是数据属性，则通过获取属性访问检索到的值。如果传入此值，请将getter、setter、method和data设置为NULL（因为这些成员不会被使用）。getter：执行属性获取访问时调用的函数。如果传入此值，请将value和method设置为NULL（因为这些成员不会被使用）。当从 JavaScript 代码访问属性（或使用 Node-API 调用执行属性获取）时，运行时会隐式调用给定的函数。napi_callback提供更多详细信息。setter：执行属性设置访问时调用的函数。如果传入此值，请将value和method设置为NULL（因为这些成员不会被使用）。当从 JavaScript 代码设置属性（或使用 Node-API 调用执行属性设置）时，运行时会隐式调用给定的函数。napi_callback提供更多详细信息。method：设置为使属性描述符对象的value属性成为由method表示的 JavaScript 函数。如果传入此值，请将value、getter和setter设置为NULL（因为这些成员不会被使用）。napi_callback提供更多详细信息。attributes：与特定属性关联的属性。参见napi_property_attributes。data：如果调用此函数，则传递到method、getter和setter的回调数据。
函数
napi_get_property_names
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_property_names(napi_env env,
napi_value object,
napi_value* result);[in] env: 调用 Node-API 的环境。[in] object: 要从中检索属性的对象。[out] result: 一个napi_value，表示一个 JavaScript 值数组，这些值代表对象的属性名称。可以使用napi_get_array_length和napi_get_element遍历result。
如果 API 成功，则返回 napi_ok。
此 API 将对象的枚举属性名称作为字符串数组返回。键为符号的 object 属性将不会包含在内。
napi_get_all_property_names
新增于: v13.7.0, v12.17.0, v10.20.0
N-API 版本: 6
napi_get_all_property_names(napi_env env,
napi_value object,
napi_key_collection_mode key_mode,
napi_key_filter key_filter,
napi_key_conversion key_conversion,
napi_value* result);[in] env: 调用 Node-API 的环境。[in] object: 要从中检索属性的对象。[in] key_mode: 是否也检索原型属性。[in] key_filter: 要检索哪些属性（可枚举/可读/可写）。[in] key_conversion: 是否将编号属性键转换为字符串。[out] result: 一个napi_value，表示一个 JavaScript 值数组，这些值代表对象的属性名称。可以使用napi_get_array_length和napi_get_element遍历result。
如果 API 成功，则返回 napi_ok。
此 API 返回一个数组，其中包含此对象可用属性的名称。
napi_set_property
新增于：v8.0.0
N-API 版本：1
napi_status napi_set_property(napi_env env,
napi_value object,
napi_value key,
napi_value value);[in] env: Node-API 调用所在的运行环境。[in] object: 要设置属性的对象。[in] key: 要设置的属性名称。[in] value: 属性值。
如果 API 成功，则返回 napi_ok。
此 API 设置传入的 Object 对象上的属性。
napi_get_property
新增于：v8.0.0
N-API 版本：1
napi_status napi_get_property(napi_env env,
napi_value object,
napi_value key,
napi_value* result);[in] env: Node-API 调用所在的运行环境。[in] object: 要从中检索属性的对象。[in] key: 要检索的属性名称。[out] result: 属性的值。
如果 API 成功，则返回 napi_ok。
此 API 获取传入的 Object 对象中请求的属性。
napi_has_property
新增于: v8.0.0
N-API 版本: 1
napi_status napi_has_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: 调用 Node-API 的环境。[in] object: 要查询的对象。[in] key: 要检查是否存在属性的名称。[out] result: 属性是否存在于对象中。
如果 API 成功，则返回 napi_ok。
此 API 检查传入的 Object 是否具有指定的属性。
napi_delete_property
新增于: v8.2.0
N-API 版本: 1
napi_status napi_delete_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: 调用 Node-API 的环境。[in] object: 要查询的对象。[in] key: 要删除的属性名称。[out] result: 属性删除是否成功。result可以通过传递NULL来忽略。
如果 API 成功，则返回 napi_ok。
此 API 尝试从 object 中删除 key 自有属性。
napi_has_own_property
新增于: v8.2.0
N-API 版本: 1
napi_status napi_has_own_property(napi_env env,
napi_value object,
napi_value key,
bool* result);[in] env: Node-API 调用所在的运行环境。[in] object: 要查询的对象。[in] key: 要检查其是否存在自身的属性名称。[out] result: 对象自身属性是否存在。
如果 API 成功，则返回 napi_ok。
此 API 检查传入的 Object 是否具有指定的自身属性。key 必须是 string 或 symbol，否则将抛出错误。Node-API 不会执行任何数据类型之间的转换。
napi_set_named_property
新增于: v8.0.0
N-API 版本: 1
napi_status napi_set_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value value);[in] env: Node-API 调用所在的运行环境。[in] object: 要在其上设置属性的对象。[in] utf8Name: 要设置的属性名称。[in] value: 属性值。
如果 API 成功，则返回 napi_ok。
此方法等效于使用从 utf8Name 参数传入的字符串创建的 napi_value 调用 napi_set_property。
napi_get_named_property
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_named_property(napi_env env,
napi_value object,
const char* utf8Name,
napi_value* result);[in] env: 调用 Node-API 的环境。[in] object: 获取属性的对象。[in] utf8Name: 要获取的属性名称。[out] result: 属性的值。
如果 API 成功，则返回 napi_ok。
此方法等效于使用作为 utf8Name 传入的字符串创建的 napi_value 调用 napi_get_property。
napi_has_named_property
新增于: v8.0.0
N-API 版本: 1
napi_status napi_has_named_property(napi_env env,
napi_value object,
const char* utf8Name,
bool* result);[in] env: 调用 Node-API 的环境。[in] object: 要查询的对象。[in] utf8Name: 要检查其是否存在属性的名称。[out] result: 属性是否存在于对象上。
如果 API 成功，则返回 napi_ok。
此方法等效于使用作为 utf8Name 传入的字符串创建的 napi_value 调用 napi_has_property。
napi_set_element
新增于: v8.0.0
N-API 版本: 1
napi_status napi_set_element(napi_env env,
napi_value object,
uint32_t index,
napi_value value);[in] env: 调用 Node-API 的环境。[in] object: 要设置属性的对象。[in] index: 要设置的属性的索引。[in] value: 属性值。
如果 API 成功，则返回 napi_ok。
此 API 设置传入的 Object 中的元素。
napi_get_element
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_element(napi_env env,
napi_value object,
uint32_t index,
napi_value* result);[in] env: 调用 Node-API 的环境。[in] object: 要从中检索属性的对象。[in] index: 要获取的属性的索引。[out] result: 属性的值。
如果 API 成功，则返回 napi_ok。
此 API 获取请求索引处的元素。
napi_has_element
新增于: v8.0.0
N-API 版本: 1
napi_status napi_has_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);[in] env: Node-API 调用所在的运行环境。[in] object: 要查询的对象。[in] index: 要检查其是否存在属性的索引。[out] result: 属性是否存在于对象中。
如果 API 成功，则返回 napi_ok。
此 API 返回传入的 Object 是否在请求的索引处具有元素。
napi_delete_element
新增于: v8.2.0
N-API 版本: 1
napi_status napi_delete_element(napi_env env,
napi_value object,
uint32_t index,
bool* result);[in] env: Node-API 调用所在的运行环境。[in] object: 要查询的对象。[in] index: 要删除的属性的索引。[out] result: 元素删除是否成功。result可以通过传递NULL来可选地忽略。
如果 API 成功，则返回 napi_ok。
此 API 尝试从 object 中删除指定的 index。
napi_define_properties
新增于：v8.0.0
N-API 版本：1
napi_status napi_define_properties(napi_env env,
napi_value object,
size_t property_count,
const napi_property_descriptor* properties);[in] env: Node-API 调用所在的运行环境。[in] object: 获取属性的对象。[in] property_count:properties数组中的元素个数。[in] properties: 属性描述符数组。
如果 API 成功，则返回 napi_ok。
此方法允许在给定对象上高效地定义多个属性。属性使用属性描述符定义（参见 napi_property_descriptor）。给定这样一个属性描述符数组，此 API 将根据 DefineOwnProperty() 的定义（在 ECMA-262 规范的 第 9.1.6 节 中描述）一次设置对象上的属性。
napi_object_freeze
新增于: v14.14.0, v12.20.0
N-API 版本: 8
napi_status napi_object_freeze(napi_env env,
napi_value object);[in] env: 调用 Node-API 的环境。[in] object: 要冻结的对象。
如果 API 成功，则返回 napi_ok。
此方法冻结给定的对象。这将阻止向其添加新属性，阻止删除现有属性，阻止更改现有属性的可枚举性、可配置性或可写性，并阻止更改现有属性的值。它还阻止更改对象的原型。这在 ECMA-262 规范的 第 19.1.2.6 节 中进行了描述。
napi_object_seal
新增于: v14.14.0, v12.20.0
N-API 版本: 8
napi_status napi_object_seal(napi_env env,
napi_value object);[in] env: 调用 Node-API 的环境。[in] object: 要密封的对象。
如果 API 成功，则返回 napi_ok。
此方法密封给定的对象。这将阻止向其添加新属性，并将所有现有属性标记为不可配置。这在 ECMA-262 规范的 第 19.1.2.20 节 中进行了描述。
使用 JavaScript 函数
Node-API 提供一组 API，允许 JavaScript 代码回调到原生代码。支持回调到原生代码的 Node-API 使用 napi_callback 类型表示回调函数。当 JavaScript VM 回调到原生代码时，将调用提供的 napi_callback 函数。本节中记录的 API 允许回调函数执行以下操作：
- 获取有关调用回调的上下文的信息。
- 获取传递给回调的参数。
- 从回调返回
napi_value。
此外，Node-API 还提供一组函数，允许从原生代码调用 JavaScript 函数。可以像调用常规 JavaScript 函数一样调用函数，也可以像构造函数一样调用函数。
任何通过 napi_property_descriptor 条目的 data 字段传递给此 API 的非 NULL 数据都可以与 object 关联，并且只要 object 被垃圾回收，就可以通过将 object 和数据都传递给 napi_add_finalizer 来释放。
napi_call_function
新增于: v8.0.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_call_function(napi_env env,
napi_value recv,
napi_value func,
size_t argc,
const napi_value* argv,
napi_value* result);[in] env: API 调用的环境。[in] recv: 传递给被调用函数的this值。[in] func: 代表要调用的 JavaScript 函数的napi_value。[in] argc:argv数组中元素的数量。[in] argv:napi_value数组，代表作为参数传递给函数的 JavaScript 值。[out] result: 代表返回的 JavaScript 对象的napi_value。
如果 API 成功，则返回 napi_ok。
此方法允许从原生插件调用 JavaScript 函数对象。这是从插件的原生代码回调到 JavaScript 的主要机制。对于异步操作后调用 JavaScript 的特殊情况，请参见 napi_make_callback。
一个示例用例如下所示。考虑以下 JavaScript 代码片段：
function AddTwo(num) {
return num + 2
}
global.AddTwo = AddTwo然后，可以使用以下代码从原生插件调用上述函数：
// 获取全局对象上的名为“AddTwo”的函数
napi_value global, add_two, arg;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;
status = napi_get_named_property(env, global, "AddTwo", &add_two);
if (status != napi_ok) return;
// const arg = 1337
status = napi_create_int32(env, 1337, &arg);
if (status != napi_ok) return;
napi_value* argv = &arg;
size_t argc = 1;
// AddTwo(arg);
napi_value return_val;
status = napi_call_function(env, global, add_two, argc, argv, &return_val);
if (status != napi_ok) return;
// 将结果转换回原生类型
int32_t result;
status = napi_get_value_int32(env, return_val, &result);
if (status != napi_ok) return;napi_create_function
新增于: v8.0.0
N-API 版本: 1
napi_status napi_create_function(napi_env env,
const char* utf8name,
size_t length,
napi_callback cb,
void* data,
napi_value* result);[in] env: API 所在的环境。[in] utf8Name: 可选，函数的 UTF8 编码名称。在 JavaScript 中，这将显示为新函数对象的name属性。[in] length:utf8name的长度（字节），如果为 null 结尾，则为NAPI_AUTO_LENGTH。[in] cb: 当调用此函数对象时应调用的原生函数。napi_callback提供更多详细信息。[in] data: 用户提供的数据上下文。稍后调用函数时，这将被传回函数。[out] result: 代表新创建函数的 JavaScript 函数对象的napi_value。
如果 API 成功，则返回 napi_ok。
此 API 允许加载项作者在原生代码中创建函数对象。这是允许从 JavaScript 调用加载项原生代码的主要机制。
此调用后，新创建的函数不会自动从脚本中可见。相反，必须在对 JavaScript 可见的任何对象上显式设置属性，以便函数可以从脚本访问。
为了将函数作为加载项模块导出的一部分公开，请在新创建的函数上设置导出对象。示例模块如下所示：
napi_value SayHello(napi_env env, napi_callback_info info) {
printf("Hello\n");
return NULL;
}
napi_value Init(napi_env env, napi_value exports) {
napi_status status;
napi_value fn;
status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
if (status != napi_ok) return NULL;
status = napi_set_named_property(env, exports, "sayHello", fn);
if (status != napi_ok) return NULL;
return exports;
}
NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)根据以上代码，加载项可以从 JavaScript 中使用，如下所示：
const myaddon = require('./addon')
myaddon.sayHello()传递给 require() 的字符串是 binding.gyp 中负责创建 .node 文件的目标的名称。
通过 data 参数传递给此 API 的任何非 NULL 数据都可以与生成的 JavaScript 函数（在 result 参数中返回）关联，并且可以通过将 JavaScript 函数和数据都传递给 napi_add_finalizer 来在垃圾回收时释放。
JavaScript Function 在 ECMAScript 语言规范的 第 19.2 节 中进行了描述。
napi_get_cb_info
新增于：v8.0.0
N-API 版本：1
napi_status napi_get_cb_info(napi_env env,
napi_callback_info cbinfo,
size_t* argc,
napi_value* argv,
napi_value* thisArg,
void** data)[in] env: API 调用的环境。[in] cbinfo: 传递到回调函数的回调信息。[in-out] argc: 指定提供的argv数组的长度，并接收实际的参数数量。argc可以通过传递NULL来忽略。[out] argv:napi_value的 C 数组，参数将复制到该数组中。如果参数数量超过提供的数量，则只复制请求数量的参数。如果提供的参数少于声明的数量，则argv的其余部分将填充为表示undefined的napi_value值。argv可以通过传递NULL来忽略。[out] thisArg: 接收调用的 JavaScriptthis参数。thisArg可以通过传递NULL来忽略。[out] data: 接收回调的数据指针。data可以通过传递NULL来忽略。
如果 API 成功，则返回 napi_ok。
此方法用于在回调函数中检索有关调用的详细信息，例如参数和给定回调信息的 this 指针。
napi_get_new_target
新增于: v8.6.0
N-API 版本: 1
napi_status napi_get_new_target(napi_env env,
napi_callback_info cbinfo,
napi_value* result)[in] env: API 调用的环境。[in] cbinfo: 传递给回调函数的回调信息。[out] result: 构造函数调用的new.target。
如果 API 成功，则返回 napi_ok。
此 API 返回构造函数调用的 new.target。如果当前回调不是构造函数调用，则结果为 NULL。
napi_new_instance
新增于: v8.0.0
N-API 版本: 1
napi_status napi_new_instance(napi_env env,
napi_value cons,
size_t argc,
napi_value* argv,
napi_value* result)[in] env: API 调用的环境。[in] cons: 代表作为构造函数调用的 JavaScript 函数的napi_value。[in] argc:argv数组中元素的计数。[in] argv: 作为napi_value的 JavaScript 值数组，代表构造函数的参数。如果argc为零，则可以通过传入NULL来省略此参数。[out] result: 代表返回的 JavaScript 对象的napi_value，在本例中是构造的对象。
此方法用于使用代表对象构造函数的给定 napi_value 实例化新的 JavaScript 值。例如，考虑以下代码片段：
function MyObject(param) {
this.param = param
}
const arg = 'hello'
const value = new MyObject(arg)可以使用以下代码片段在 Node-API 中近似实现：
// 获取构造函数 MyObject
napi_value global, constructor, arg, value;
napi_status status = napi_get_global(env, &global);
if (status != napi_ok) return;
status = napi_get_named_property(env, global, "MyObject", &constructor);
if (status != napi_ok) return;
// const arg = "hello"
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &arg);
if (status != napi_ok) return;
napi_value* argv = &arg;
size_t argc = 1;
// const value = new MyObject(arg)
status = napi_new_instance(env, constructor, argc, argv, &value);如果 API 成功，则返回 napi_ok。
对象包装
Node-API 提供了一种“包装” C++ 类和实例的方法，以便可以从 JavaScript 调用类构造函数和方法。
对于包装后的对象，可能难以区分在类原型上调用的函数和在类实例上调用的函数。解决此问题的常用模式是保存对类构造函数的持久引用，以便以后进行 instanceof 检查。
napi_value MyClass_constructor = NULL;
status = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor);
assert(napi_ok == status);
bool is_instance = false;
status = napi_instanceof(env, es_this, MyClass_constructor, &is_instance);
assert(napi_ok == status);
if (is_instance) {
// napi_unwrap() ...
} else {
// otherwise...
}一旦不再需要该引用，就必须释放它。
在某些情况下，napi_instanceof() 不足以确保 JavaScript 对象是特定原生类型的包装器。当通过静态方法而不是作为原型方法的 this 值将包装的 JavaScript 对象传递回附加组件时，尤其如此。在这种情况下，它们可能被错误地解包。
const myAddon = require('./build/Release/my_addon.node')
// `openDatabase()` 返回一个包装原生数据库句柄的 JavaScript 对象。
const dbHandle = myAddon.openDatabase()
// `query()` 返回一个包装原生查询句柄的 JavaScript 对象。
const queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!')
// 下面的行中存在意外错误。`myAddon.queryHasRecords()` 的第一个参数应该是数据库句柄 (`dbHandle`)，而不是查询句柄 (`query`)，因此 while 循环的正确条件应该是
//
// myAddon.queryHasRecords(dbHandle, queryHandle)
//
while (myAddon.queryHasRecords(queryHandle, dbHandle)) {
// retrieve records
}在上面的示例中，myAddon.queryHasRecords() 是一个接受两个参数的方法。第一个是数据库句柄，第二个是查询句柄。在内部，它会解包第一个参数并将结果指针转换为原生数据库句柄。然后，它解包第二个参数并将结果指针转换为查询句柄。如果参数顺序错误，转换将有效，但是，底层数据库操作很可能会失败，甚至会导致无效的内存访问。
为了确保从第一个参数检索到的指针确实是数据库句柄的指针，并且类似地，从第二个参数检索到的指针确实是查询句柄的指针，queryHasRecords() 的实现必须执行类型验证。在 napi_ref 中保留从其实例化数据库句柄的 JavaScript 类构造函数和从其实例化查询句柄的构造函数可以提供帮助，因为 napi_instanceof() 随后可用于确保传递到 queryHashRecords() 的实例确实是正确的类型。
不幸的是，napi_instanceof() 无法防止原型操纵。例如，数据库句柄实例的原型可以设置为查询句柄实例的构造函数的原型。在这种情况下，数据库句柄实例可能显示为查询句柄实例，并且它将通过查询句柄实例的 napi_instanceof() 测试，同时仍然包含指向数据库句柄的指针。
为此，Node-API 提供了类型标记功能。
类型标记是附加组件独有的 128 位整数。Node-API 提供了 napi_type_tag 结构用于存储类型标记。当这样的值与存储在 napi_value 中的 JavaScript 对象或 外部 对象一起传递到 napi_type_tag_object() 时，JavaScript 对象将被“标记”上类型标记。“标记”在 JavaScript 端是不可见的。当 JavaScript 对象到达原生绑定时，可以将 napi_check_object_type_tag() 与原始类型标记一起使用，以确定 JavaScript 对象是否先前已用类型标记“标记”。这创建了一种比 napi_instanceof() 提供的更高保真度的类型检查功能，因为这种类型标记可以在原型操纵和附加组件卸载/重新加载后继续存在。
继续上面的示例，以下骨架附加组件实现说明了 napi_type_tag_object() 和 napi_check_object_type_tag() 的用法。
// 此值是数据库句柄的类型标记。命令
//
// uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\1, 0x\2/'
//
// 可用于获取用于初始化结构的两个值。
static const napi_type_tag DatabaseHandleTypeTag = {
0x1edf75a38336451d, 0xa5ed9ce2e4c00c38
};
// 此值是查询句柄的类型标记。
static const napi_type_tag QueryHandleTypeTag = {
0x9c73317f9fad44a3, 0x93c3920bf3b0ad6a
};
static napi_value
openDatabase(napi_env env, napi_callback_info info) {
napi_status status;
napi_value result;
// 执行导致数据库句柄的底层操作。
DatabaseHandle* dbHandle = open_database();
// 创建一个新的空 JS 对象。
status = napi_create_object(env, &result);
if (status != napi_ok) return NULL;
// 标记对象以指示它持有指向 `DatabaseHandle` 的指针。
status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);
if (status != napi_ok) return NULL;
// 将指向 `DatabaseHandle` 结构的指针存储在 JS 对象中。
status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);
if (status != napi_ok) return NULL;
return result;
}
// 稍后当我们收到一个声称是数据库句柄的 JavaScript 对象时，我们可以使用 `napi_check_object_type_tag()` 来确保它确实是这样的句柄。
static napi_value
query(napi_env env, napi_callback_info info) {
napi_status status;
size_t argc = 2;
napi_value argv[2];
bool is_db_handle;
status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);
if (status != napi_ok) return NULL;
// 检查作为第一个参数传递的对象是否具有先前应用的标记。
status = napi_check_object_type_tag(env,
argv[0],
&DatabaseHandleTypeTag,
&is_db_handle);
if (status != napi_ok) return NULL;
// 如果没有，则抛出 `TypeError`。
if (!is_db_handle) {
// Throw a TypeError.
return NULL;
}
}napi_define_class
新增于: v8.0.0
N-API 版本: 1
napi_status napi_define_class(napi_env env,
const char* utf8name,
size_t length,
napi_callback constructor,
void* data,
size_t property_count,
const napi_property_descriptor* properties,
napi_value* result);[in] env: API 调用的环境。[in] utf8name: JavaScript 构造函数的名称。为清晰起见，建议在包装 C++ 类时使用 C++ 类名。[in] length:utf8name的长度（字节），如果其为 null 终止，则为NAPI_AUTO_LENGTH。[in] constructor: 处理类实例构造的回调函数。在包装 C++ 类时，此方法必须是具有napi_callback签名的静态成员。不能使用 C++ 类构造函数。napi_callback提供更多详细信息。[in] data: 可选数据，作为回调信息的data属性传递给构造函数回调。[in] property_count:properties数组参数中的项目数。[in] properties: 属性描述符数组，描述类上的静态和实例数据属性、访问器和方法。参见napi_property_descriptor。[out] result: 代表类的构造函数的napi_value。
如果 API 成功，则返回 napi_ok。
定义一个 JavaScript 类，包括：
- 一个具有类名的 JavaScript 构造函数。在包装相应的 C++ 类时，通过
constructor传递的回调可用于实例化新的 C++ 类实例，然后可以使用napi_wrap将其放入正在构造的 JavaScript 对象实例中。 - 构造函数上的属性，其实现可以调用 C++ 类的相应 静态 数据属性、访问器和方法（由具有
napi_static属性的属性描述符定义）。 - 构造函数的
prototype对象上的属性。在包装 C++ 类时，可以使用napi_unwrap获取放入 JavaScript 对象实例中的 C++ 类实例后，从不具有napi_static属性的属性描述符中给出的静态函数调用 C++ 类的 非静态 数据属性、访问器和方法。
在包装 C++ 类时，通过 constructor 传递的 C++ 构造函数回调应该是类上的静态方法，它调用实际的类构造函数，然后将新的 C++ 实例包装在 JavaScript 对象中，并返回包装器对象。有关详细信息，请参见 napi_wrap。
从 napi_define_class 返回的 JavaScript 构造函数通常会被保存并稍后用于从原生代码构造类的新的实例，和/或检查提供的数值是否为类的实例。在这种情况下，为防止函数值被垃圾回收，可以使用 napi_create_reference 为其创建一个强持久引用，确保引用计数保持 >= 1。
任何通过 data 参数或 napi_property_descriptor 数组项的 data 字段传递给此 API 的非 NULL 数据都可以与生成的 JavaScript 构造函数（在 result 参数中返回）关联，并在类被垃圾回收时通过将 JavaScript 函数和数据都传递给 napi_add_finalizer 来释放。
napi_wrap
新增于: v8.0.0
N-API 版本: 1
napi_status napi_wrap(napi_env env,
napi_value js_object,
void* native_object,
napi_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);[in] env: API 调用的环境。[in] js_object: 将用作原生对象包装器的 JavaScript 对象。[in] native_object: 将被包装到 JavaScript 对象中的原生实例。[in] finalize_cb: 可选的原生回调，用于在 JavaScript 对象被垃圾回收时释放原生实例。napi_finalize提供更多细节。[in] finalize_hint: 传递给 finalize 回调的可选上下文提示。[out] result: 可选的被包装对象的引用。
如果 API 成功，则返回 napi_ok。
将原生实例包装在 JavaScript 对象中。稍后可以使用 napi_unwrap() 检索原生实例。
当 JavaScript 代码调用使用 napi_define_class() 定义的类的构造函数时，会调用构造函数的 napi_callback。在构造原生类的实例之后，回调必须调用 napi_wrap() 将新构造的实例包装到已创建的 JavaScript 对象中，该对象是构造函数回调的 this 参数。（该 this 对象是从构造函数的 prototype 创建的，因此它已经定义了所有实例属性和方法。）
通常，在包装类实例时，应该提供一个 finalize 回调，该回调只需删除作为 finalize 回调的 data 参数接收到的原生实例。
可选的返回引用最初是一个弱引用，这意味着它的引用计数为 0。通常，在需要实例保持有效的异步操作期间，会暂时递增此引用计数。
警告: 只有在响应 finalize 回调调用时，才应通过 napi_delete_reference 删除可选的返回引用（如果已获得）。如果在此之前删除它，则可能永远不会调用 finalize 回调。因此，当获取引用时，也需要 finalize 回调才能正确处理引用。
Finalizer 回调可能会被延迟，留下一个窗口，在这个窗口中，对象已被垃圾回收（并且弱引用无效），但 finalizer 尚未被调用。当在 napi_wrap() 返回的弱引用上使用 napi_get_reference_value() 时，仍然应该处理空结果。
对对象第二次调用 napi_wrap() 将返回错误。要将另一个原生实例与对象关联，请首先使用 napi_remove_wrap()。
napi_unwrap
新增于: v8.0.0
N-API 版本: 1
napi_status napi_unwrap(napi_env env,
napi_value js_object,
void** result);[in] env: API 所在的环境。[in] js_object: 与原生实例关联的对象。[out] result: 指向已包装原生实例的指针。
如果 API 成功，则返回 napi_ok。
检索先前使用 napi_wrap() 包装在 JavaScript 对象中的原生实例。
当 JavaScript 代码调用类的某个方法或属性访问器时，相应的 napi_callback 将被调用。如果回调是针对实例方法或访问器的，则回调的 this 参数是包装器对象；然后可以通过对包装器对象调用 napi_unwrap() 来获取作为调用的目标的已包装 C++ 实例。
napi_remove_wrap
新增于: v8.5.0
N-API 版本: 1
napi_status napi_remove_wrap(napi_env env,
napi_value js_object,
void** result);[in] env: API 所在的环境。[in] js_object: 与原生实例关联的对象。[out] result: 指向已包装原生实例的指针。
如果 API 成功，则返回 napi_ok。
检索先前使用 napi_wrap() 包装在 JavaScript 对象 js_object 中的原生实例，并移除包装。如果 finalize 回调与包装关联，则当 JavaScript 对象被垃圾回收时，它将不再被调用。
napi_type_tag_object
新增于: v14.8.0, v12.19.0
N-API 版本: 8
napi_status napi_type_tag_object(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag);[in] env: API 调用的环境。[in] js_object: 要标记的 JavaScript 对象或外部对象。[in] type_tag: 用于标记对象的标签。
如果 API 成功，则返回 napi_ok。
将 type_tag 指针的值与 JavaScript 对象或外部对象关联。然后可以使用 napi_check_object_type_tag() 将附加到对象的标签与插件拥有的标签进行比较，以确保对象具有正确的类型。
如果对象已经关联了类型标签，则此 API 将返回 napi_invalid_arg。
napi_check_object_type_tag
新增于: v14.8.0, v12.19.0
N-API 版本: 8
napi_status napi_check_object_type_tag(napi_env env,
napi_value js_object,
const napi_type_tag* type_tag,
bool* result);[in] env: API 调用的环境。[in] js_object: 要检查其类型标签的 JavaScript 对象或外部对象。[in] type_tag: 用于与对象上找到的任何标签进行比较的标签。[out] result: 给定的类型标签是否与对象上的类型标签匹配。如果在对象上找不到类型标签，则也返回false。
如果 API 成功，则返回 napi_ok。
将作为 type_tag 给出的指针与可在 js_object 上找到的任何指针进行比较。如果在 js_object 上找不到标签，或者如果找到标签但它与 type_tag 不匹配，则 result 设置为 false。如果找到标签并且它与 type_tag 匹配，则 result 设置为 true。
napi_add_finalizer
新增于: v8.0.0
N-API 版本: 5
napi_status napi_add_finalizer(napi_env env,
napi_value js_object,
void* finalize_data,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);[in] env: API 调用的环境。[in] js_object: 将附加本地数据的 JavaScript 对象。[in] finalize_data: 传递给finalize_cb的可选数据。[in] finalize_cb: 当 JavaScript 对象被垃圾回收时，将用于释放本地数据的原生回调。napi_finalize提供更多细节。[in] finalize_hint: 传递给 finalize 回调的可选上下文提示。[out] result: JavaScript 对象的可选引用。
如果 API 成功，则返回 napi_ok。
添加一个 napi_finalize 回调，该回调将在 js_object 中的 JavaScript 对象被垃圾回收时调用。
此 API 可以对单个 JavaScript 对象调用多次。
警告: 只有在响应 finalize 回调调用时，才应通过 napi_delete_reference 删除可选的返回引用（如果已获得）。如果在此之前删除它，则可能永远不会调用 finalize 回调。因此，当获得引用时，也需要一个 finalize 回调才能正确释放引用。
node_api_post_finalizer
新增于: v21.0.0, v20.10.0, v18.19.0
napi_status node_api_post_finalizer(node_api_basic_env env,
napi_finalize finalize_cb,
void* finalize_data,
void* finalize_hint);[in] env: API 调用的环境。[in] finalize_cb: 当 JavaScript 对象被垃圾回收时，将用于释放原生数据的原生回调。napi_finalize提供更多细节。[in] finalize_data: 传递给finalize_cb的可选数据。[in] finalize_hint: 传递给 finalize 回调的可选上下文提示。
如果 API 成功，则返回 napi_ok。
调度一个 napi_finalize 回调，以便在事件循环中异步调用。
通常，终结器在 GC（垃圾回收器）收集对象时调用。那时，调用任何可能导致 GC 状态发生变化的 Node-API 将被禁用，并导致 Node.js 崩溃。
node_api_post_finalizer 有助于解决此限制，允许加载项将对这类 Node-API 的调用推迟到 GC 终结之外的时间点。
简单异步操作
Addon 模块通常需要利用 libuv 中的异步辅助函数作为其实现的一部分。这允许它们调度异步执行的工作，以便它们的方法可以在工作完成之前返回。这使得它们可以避免阻塞 Node.js 应用程序的整体执行。
Node-API 为这些支持函数提供了一个 ABI 稳定的接口，涵盖了最常见的异步用例。
Node-API 定义了 napi_async_work 结构，用于管理异步工作者。实例使用 napi_create_async_work 和 napi_delete_async_work 创建/删除。
execute 和 complete 回调函数分别在执行程序准备好执行时和完成其任务时被调用。
execute 函数应避免进行任何可能导致 JavaScript 执行或与 JavaScript 对象交互的 Node-API 调用。通常，任何需要进行 Node-API 调用的代码都应该在 complete 回调中进行。避免在 execute 回调中使用 napi_env 参数，因为它可能会执行 JavaScript。
这些函数实现以下接口：
typedef void (*napi_async_execute_callback)(napi_env env,
void* data);
typedef void (*napi_async_complete_callback)(napi_env env,
napi_status status,
void* data);当这些方法被调用时，传递的 data 参数将是传递到 napi_create_async_work 调用的 addon 提供的 void* 数据。
创建后，可以使用 napi_queue_async_work 函数将异步工作者排队等待执行：
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);如果在工作开始执行之前需要取消工作，可以使用 napi_cancel_async_work。
调用 napi_cancel_async_work 后，complete 回调将使用 napi_cancelled 的状态值被调用。即使工作被取消，也不应该在 complete 回调调用之前删除工作。
napi_create_async_work
[历史]
| 版本 | 变更 |
|---|---|
| v8.6.0 | 添加了 async_resource 和 async_resource_name 参数。 |
| v8.0.0 | 在 v8.0.0 中添加 |
N-API 版本: 1
napi_status napi_create_async_work(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_execute_callback execute,
napi_async_complete_callback complete,
void* data,
napi_async_work* result);[in] env: API 调用的环境。[in] async_resource: 与异步工作关联的可选对象，将传递给可能的async_hooksinit钩子。[in] async_resource_name: 为async_hooksAPI 公开的诊断信息提供的资源类型的标识符。[in] execute: 应该调用的原生函数，用于异步执行逻辑。给定的函数从工作池线程调用，并且可以与主事件循环线程并行执行。[in] complete: 当异步逻辑完成或取消时将调用的原生函数。给定的函数从主事件循环线程调用。napi_async_complete_callback提供更多详细信息。[in] data: 用户提供的数据上下文。这将被传递回 execute 和 complete 函数。[out] result:napi_async_work*，它是新创建的异步工作的句柄。
如果 API 成功，则返回 napi_ok。
此 API 分配一个用于异步执行逻辑的工作对象。一旦不再需要该工作，就应该使用 napi_delete_async_work 释放它。
async_resource_name 应该是一个以 null 结尾的 UTF-8 编码字符串。
async_resource_name 标识符由用户提供，应该代表正在执行的异步工作的类型。还建议为标识符应用命名空间，例如包含模块名称。有关更多信息，请参见 async_hooks 文档。
napi_delete_async_work
新增于: v8.0.0
N-API 版本: 1
napi_status napi_delete_async_work(napi_env env,
napi_async_work work);[in] env: API 调用的环境。[in] work:napi_create_async_work调用返回的句柄。
如果 API 成功，则返回 napi_ok。
此 API 释放之前分配的工作对象。
即使存在挂起的 JavaScript 异常，也可以调用此 API。
napi_queue_async_work
新增于: v8.0.0
N-API 版本: 1
napi_status napi_queue_async_work(node_api_basic_env env,
napi_async_work work);[in] env: API 调用的环境。[in] work:napi_create_async_work调用返回的句柄。
如果 API 成功，则返回 napi_ok。
此 API 请求调度之前分配的工作以执行。一旦成功返回，则不得再次使用相同的 napi_async_work 项调用此 API，否则结果将未定义。
napi_cancel_async_work
新增于: v8.0.0
N-API 版本: 1
napi_status napi_cancel_async_work(node_api_basic_env env,
napi_async_work work);[in] env: API 调用的环境。[in] work:napi_create_async_work调用返回的句柄。
如果 API 成功，则返回 napi_ok。
如果异步工作尚未开始，则此 API 会取消排队的异步工作。如果已经开始执行，则无法取消，并将返回 napi_generic_failure。如果成功，则 complete 回调将使用 napi_cancelled 的状态值被调用。即使异步工作已成功取消，也不应在 complete 回调调用之前删除它。
即使存在未处理的 JavaScript 异常，也可以调用此 API。
自定义异步操作
上述简单的异步工作 API 可能不适用于所有场景。当使用任何其他异步机制时，需要使用以下 API 来确保运行时正确跟踪异步操作。
napi_async_init
新增于：v8.6.0
N-API 版本：1
napi_status napi_async_init(napi_env env,
napi_value async_resource,
napi_value async_resource_name,
napi_async_context* result)[in] env: API 调用的环境。[in] async_resource: 与异步工作关联的对象，它将传递给可能的async_hooksinithook，并且可以通过async_hooks.executionAsyncResource()访问。[in] async_resource_name:async_hooksAPI 公开的诊断信息提供的资源类型的标识符。[out] result: 初始化的异步上下文。
如果 API 成功，则返回 napi_ok。
async_resource 对象需要保持存活直到 napi_async_destroy，以确保 async_hooks 相关的 API 正确运行。为了保持与先前版本的 ABI 兼容性，napi_async_context 不维护对 async_resource 对象的强引用，以避免造成内存泄漏。但是，如果在 napi_async_context 被 napi_async_destroy 销毁之前，async_resource 被 JavaScript 引擎垃圾回收，则调用 napi_async_context 相关的 API（例如 napi_open_callback_scope 和 napi_make_callback）可能会导致问题，例如在使用 AsyncLocalStorage API 时丢失异步上下文。
为了保持与先前版本的 ABI 兼容性，将 NULL 传递给 async_resource 不会导致错误。但是，这并不推荐，因为这将导致 async_hooks init hook 和 async_hooks.executionAsyncResource() 的不良行为，因为底层 async_hooks 实现现在需要该资源才能提供异步回调之间的链接。
napi_async_destroy
新增于: v8.6.0
N-API 版本: 1
napi_status napi_async_destroy(napi_env env,
napi_async_context async_context);[in] env: API 调用的环境。[in] async_context: 要销毁的异步上下文。
如果 API 成功，则返回 napi_ok。
即使存在挂起的 JavaScript 异常，也可以调用此 API。
napi_make_callback
[历史]
| 版本 | 变更 |
|---|---|
| v8.6.0 | 添加了 async_context 参数。 |
| v8.0.0 | 新增于: v8.0.0 |
N-API 版本: 1
NAPI_EXTERN napi_status napi_make_callback(napi_env env,
napi_async_context async_context,
napi_value recv,
napi_value func,
size_t argc,
const napi_value* argv,
napi_value* result);[in] env: API 调用的环境。[in] async_context: 调用回调的异步操作的上下文。这通常是从napi_async_init中先前获得的值。为了保持与以前版本的 ABI 兼容性，将NULL传递给async_context不会导致错误。但是，这会导致异步钩子的操作不正确。潜在问题包括在使用AsyncLocalStorageAPI 时丢失异步上下文。[in] recv: 传递给被调用函数的this值。[in] func: 代表要调用的 JavaScript 函数的napi_value。[in] argc:argv数组中元素的数量。如果argc为零，则可以通过传入NULL来省略此参数。[in] argv: JavaScript 值数组，作为napi_value，代表函数的参数。如果argc为零，则可以通过传入NULL来省略此参数。[out] result: 代表返回的 JavaScript 对象的napi_value。
如果 API 成功，则返回 napi_ok。
此方法允许从原生插件调用 JavaScript 函数对象。此 API 类似于 napi_call_function。但是，它用于在从异步操作返回后（当堆栈上没有其他脚本时）从原生代码回调到 JavaScript。它是 node::MakeCallback 的一个相当简单的包装器。
请注意，不必在 napi_async_complete_callback 内使用 napi_make_callback；在这种情况下，回调的异步上下文已经设置好了，因此直接调用 napi_call_function 就足够了。在实现不使用 napi_create_async_work 的自定义异步行为时，可能需要使用 napi_make_callback 函数。
JavaScript 在回调期间在微任务队列上调度的任何 process.nextTick 或 Promise 都会在返回 C/C++ 之前运行。
napi_open_callback_scope
新增于: v9.6.0
N-API 版本: 3
NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
napi_value resource_object,
napi_async_context context,
napi_callback_scope* result)[in] env: API 调用的环境。[in] resource_object: 与异步工作关联的对象，将传递给可能的async_hooksinit钩子。此参数已弃用，并在运行时被忽略。请改用napi_async_init中的async_resource参数。[in] context: 调用回调的异步操作的上下文。这应该是一个先前从napi_async_init获得的值。[out] result: 新创建的作用域。
在某些情况下（例如，解析 Promise），需要在进行某些 Node-API 调用时拥有与回调关联的作用域的等效项。如果没有其他脚本位于堆栈上，则可以使用 napi_open_callback_scope 和 napi_close_callback_scope 函数来打开/关闭所需的作用域。
napi_close_callback_scope
新增于: v9.6.0
N-API 版本: 3
NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
napi_callback_scope scope)[in] env: API 调用的环境。[in] scope: 要关闭的作用域。
即使存在未处理的 JavaScript 异常，也可以调用此 API。
版本管理
napi_get_node_version
新增于: v8.4.0
N-API 版本: 1
typedef struct {
uint32_t major;
uint32_t minor;
uint32_t patch;
const char* release;
} napi_node_version;
napi_status napi_get_node_version(node_api_basic_env env,
const napi_node_version** version);[in] env: API 调用的环境。[out] version: 指向 Node.js 自身版本信息的指针。
如果 API 成功，则返回 napi_ok。
此函数使用当前运行的 Node.js 的主版本、次版本和修订版本填充 version 结构，并使用 process.release.name 的值填充 release 字段。
返回的缓冲区是静态分配的，不需要释放。
napi_get_version
新增于: v8.0.0
N-API 版本: 1
napi_status napi_get_version(node_api_basic_env env,
uint32_t* result);[in] env: API 调用的环境。[out] result: Node-API 支持的最高版本。
如果 API 成功，则返回 napi_ok。
此 API 返回 Node.js 运行时支持的最高 Node-API 版本。Node-API 计划采用增量式更新，以便更新的 Node.js 版本可以支持更多 API 函数。为了允许加载项在支持它的 Node.js 版本中使用较新的函数，同时在不支持它的 Node.js 版本中提供回退行为：
- 调用
napi_get_version()以确定 API 是否可用。 - 如果可用，则使用
uv_dlsym()动态加载指向该函数的指针。 - 使用动态加载的指针来调用该函数。
- 如果该函数不可用，则提供不使用该函数的替代实现。
内存管理
napi_adjust_external_memory
新增于：v8.5.0
N-API 版本：1
NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
int64_t change_in_bytes,
int64_t* result);[in] env: API 调用的环境。[in] change_in_bytes: 由 JavaScript 对象保持活跃的外部分配内存的变化量。[out] result: 已调整的值
如果 API 成功，则返回 napi_ok。
此函数使 V8 能够了解由 JavaScript 对象保持活跃的外部分配内存量（即，指向其自身由原生插件分配的内存的 JavaScript 对象）。注册外部分配的内存将比平时更频繁地触发全局垃圾回收。
Promise
Node-API 提供了创建 Promise 对象的工具，如 ECMA 规范的 第 25.4 节 所述。它将 promise 实现为一对对象。当通过 napi_create_promise() 创建 promise 时，会创建一个“deferred”对象并与 Promise 一起返回。deferred 对象绑定到已创建的 Promise，并且是使用 napi_resolve_deferred() 或 napi_reject_deferred() 解析或拒绝 Promise 的唯一方法。由 napi_create_promise() 创建的 deferred 对象由 napi_resolve_deferred() 或 napi_reject_deferred() 释放。Promise 对象可以返回到 JavaScript，在那里可以像通常一样使用它。
例如，要创建一个 promise 并将其传递给异步工作程序：
napi_deferred deferred;
napi_value promise;
napi_status status;
// 创建 promise。
status = napi_create_promise(env, &deferred, &promise);
if (status != napi_ok) return NULL;
// 将 deferred 传递给执行异步操作的函数。
do_something_asynchronous(deferred);
// 将 promise 返回给 JS
return promise;上面的函数 do_something_asynchronous() 将执行其异步操作，然后解析或拒绝 deferred，从而结束 promise 并释放 deferred：
napi_deferred deferred;
napi_value undefined;
napi_status status;
// 创建一个值来结束 deferred。
status = napi_get_undefined(env, &undefined);
if (status != napi_ok) return NULL;
// 根据异步操作是否成功，解析或拒绝与 deferred 关联的 promise。
if (asynchronous_action_succeeded) {
status = napi_resolve_deferred(env, deferred, undefined);
} else {
status = napi_reject_deferred(env, deferred, undefined);
}
if (status != napi_ok) return NULL;
// 在这一点上，deferred 已被释放，因此我们应该将其赋值为 NULL。
deferred = NULL;napi_create_promise
新增于: v8.5.0
N-API 版本: 1
napi_status napi_create_promise(napi_env env,
napi_deferred* deferred,
napi_value* promise);[in] env: API 调用的环境。[out] deferred: 新创建的延迟对象，稍后可传递给napi_resolve_deferred()或napi_reject_deferred()来分别解决或拒绝关联的 Promise。[out] promise: 与延迟对象关联的 JavaScript Promise。
如果 API 成功，则返回 napi_ok。
此 API 创建一个延迟对象和一个 JavaScript Promise。
napi_resolve_deferred
新增于: v8.5.0
N-API 版本: 1
napi_status napi_resolve_deferred(napi_env env,
napi_deferred deferred,
napi_value resolution);[in] env: API 调用的环境。[in] deferred: 要解析其关联 Promise 的延迟对象。[in] resolution: 用于解析 Promise 的值。
此 API 通过与其关联的延迟对象来解析 JavaScript Promise。因此，它只能用于解析相应的延迟对象可用的 JavaScript Promise。这实际上意味着必须使用 napi_create_promise() 创建 Promise，并且必须保留从该调用返回的延迟对象才能将其传递给此 API。
延迟对象在成功完成时被释放。
napi_reject_deferred
新增于: v8.5.0
N-API 版本: 1
napi_status napi_reject_deferred(napi_env env,
napi_deferred deferred,
napi_value rejection);[in] env: API 调用的环境。[in] deferred: 与要拒绝的 Promise 关联的 Deferred 对象。[in] rejection: 用于拒绝 Promise 的值。
此 API 通过与其关联的 Deferred 对象来拒绝 JavaScript Promise。因此，它只能用于拒绝对应的 Deferred 对象可用的 JavaScript Promise。这实际上意味着 Promise 必须使用 napi_create_promise() 创建，并且必须保留从该调用返回的 Deferred 对象才能传递给此 API。
Deferred 对象在成功完成时被释放。
napi_is_promise
新增于: v8.5.0
N-API 版本: 1
napi_status napi_is_promise(napi_env env,
napi_value value,
bool* is_promise);[in] env: API 调用的环境。[in] value: 要检查的值。[out] is_promise: 标志，指示promise是否为原生 Promise 对象（即由底层引擎创建的 Promise 对象）。
脚本执行
Node-API 提供了一个 API，用于使用底层的 JavaScript 引擎执行包含 JavaScript 代码的字符串。
napi_run_script
新增于: v8.5.0
N-API 版本: 1
NAPI_EXTERN napi_status napi_run_script(napi_env env,
napi_value script,
napi_value* result);[in] env: API 调用的环境。[in] script: 包含要执行脚本的 JavaScript 字符串。[out] result: 执行脚本的结果值。
此函数执行 JavaScript 代码字符串并返回其结果，但存在以下注意事项：
- 与
eval不同，此函数不允许脚本访问当前词法作用域，因此也不允许访问模块作用域，这意味着诸如require之类的伪全局变量将不可用。 - 脚本可以访问全局作用域。脚本中的函数和
var声明将添加到global对象中。使用let和const进行的变量声明将在全局可见，但不会添加到global对象中。 - 脚本中
this的值为global。
libuv 事件循环
Node-API 提供了一个函数，用于获取与特定 napi_env 关联的当前事件循环。
napi_get_uv_event_loop
新增于：v9.3.0, v8.10.0
N-API 版本：2
NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,
struct uv_loop_s** loop);[in] env: API 调用的环境。[out] loop: 当前 libuv 循环实例。
注意：虽然 libuv 一直以来都比较稳定，但它并不提供 ABI 稳定性保证。应避免使用此函数。使用此函数可能会导致插件无法跨 Node.js 版本工作。异步线程安全函数调用 可以替代许多用例。
异步线程安全函数调用
JavaScript 函数通常只能从原生插件的主线程调用。如果插件创建了额外的线程，则需要 napi_env、napi_value 或 napi_ref 的 Node-API 函数不能从这些线程调用。
当插件具有附加线程并且需要根据这些线程完成的处理来调用 JavaScript 函数时，这些线程必须与插件的主线程通信，以便主线程可以代表它们调用 JavaScript 函数。线程安全函数 API 提供了一种简单的方法来实现这一点。
这些 API 提供了 napi_threadsafe_function 类型以及创建、销毁和调用此类型对象的相关 API。napi_create_threadsafe_function() 创建对 napi_value 的持久引用，该引用保存可以从多个线程调用的 JavaScript 函数。调用是异步发生的。这意味着将把 JavaScript 回调要调用的值放入队列中，并且最终将对队列中的每个值调用 JavaScript 函数。
创建 napi_threadsafe_function 时，可以提供 napi_finalize 回调。当线程安全函数即将被销毁时，此回调将在主线程上被调用。它接收构造期间给定的上下文和最终数据，并提供清理线程的机会，例如通过调用 uv_thread_join()。除了主循环线程之外，在最终回调完成之后，任何线程都不应该使用线程安全函数。
在调用 napi_create_threadsafe_function() 时给定的 context 可以使用 napi_get_threadsafe_function_context() 从任何线程检索。
调用线程安全函数
napi_call_threadsafe_function() 可用于发起对 JavaScript 的调用。napi_call_threadsafe_function() 接受一个参数来控制 API 是否阻塞。如果设置为 napi_tsfn_nonblocking，API 将以非阻塞方式运行，如果队列已满，则返回 napi_queue_full，阻止数据成功添加到队列。如果设置为 napi_tsfn_blocking，API 将阻塞，直到队列中有可用空间。如果线程安全函数创建时最大队列大小为 0，则 napi_call_threadsafe_function() 永远不会阻塞。
从 JavaScript 线程调用 napi_call_threadsafe_function() 时不应使用 napi_tsfn_blocking，因为如果队列已满，它可能会导致 JavaScript 线程死锁。
对 JavaScript 的实际调用由 call_js_cb 参数提供的回调控制。call_js_cb 在主线程上为成功调用 napi_call_threadsafe_function() 放入队列的每个值调用一次。如果没有给出这样的回调，则将使用默认回调，并且生成的 JavaScript 调用将没有参数。call_js_cb 回调在其参数中接收要调用的 JavaScript 函数作为 napi_value，以及创建 napi_threadsafe_function 时使用的 void* 上下文指针，以及由辅助线程之一创建的下一个数据指针。然后，回调可以使用诸如 napi_call_function() 之类的 API 调用 JavaScript。
回调也可能同时使用 env 和 call_js_cb 设置为 NULL 来指示不再可能调用 JavaScript，而队列中仍存在可能需要释放的项目。这通常发生在 Node.js 进程退出时，而线程安全函数仍然处于活动状态。
无需通过 napi_make_callback() 调用 JavaScript，因为 Node-API 在适合回调的上下文中运行 call_js_cb。
事件循环的每次心跳都可能调用零个或多个排队项目。应用程序不应依赖于除调用回调的进度和事件将随着时间的推移而被调用的其他特定行为。
线程安全函数的引用计数
在 napi_threadsafe_function 对象的生命周期中，可以向其中添加和删除线程。因此，除了在创建时指定初始线程数量外，还可以调用 napi_acquire_threadsafe_function 来指示新的线程将开始使用该线程安全函数。类似地，可以调用 napi_release_threadsafe_function 来指示现有线程将停止使用该线程安全函数。
当每个使用该对象的线程都调用了 napi_release_threadsafe_function() 或在调用 napi_call_threadsafe_function 时收到了 napi_closing 的返回状态时，napi_threadsafe_function 对象就会被销毁。在 napi_threadsafe_function 销毁之前，队列会被清空。napi_release_threadsafe_function() 应该是与给定的 napi_threadsafe_function 一起调用的最后一个 API 调用，因为调用完成后，无法保证 napi_threadsafe_function 仍然已分配。出于同样的原因，在接收到 napi_call_threadsafe_function 调用的 napi_closing 返回值后，不要使用线程安全函数。与 napi_threadsafe_function 关联的数据可以在其传递给 napi_create_threadsafe_function() 的 napi_finalize 回调中释放。napi_create_threadsafe_function 的参数 initial_thread_count 表示线程安全函数的初始获取次数，而不是在创建时多次调用 napi_acquire_threadsafe_function。
一旦使用 napi_threadsafe_function 的线程数量达到零，则没有其他线程可以通过调用 napi_acquire_threadsafe_function() 开始使用它。事实上，所有后续与之相关的 API 调用（napi_release_threadsafe_function() 除外）都将返回错误值 napi_closing。
可以通过给 napi_release_threadsafe_function() 传递 napi_tsfn_abort 值来“中止”线程安全函数。这将导致所有后续与线程安全函数相关的 API（napi_release_threadsafe_function() 除外）返回 napi_closing，即使其引用计数尚未达到零。特别是，napi_call_threadsafe_function() 将返回 napi_closing，从而通知线程不再可能对线程安全函数进行异步调用。这可以用作终止线程的条件。从napi_call_threadsafe_function()接收到napi_closing返回值后，线程必须不再使用线程安全函数，因为它不再保证已分配。
决定是否保持进程运行
与 libuv 句柄类似，线程安全函数可以被“引用”和“取消引用”。“引用”的线程安全函数将导致其创建所在的线程上的事件循环保持活动状态，直到线程安全函数被销毁。相反，“未引用”的线程安全函数不会阻止事件循环退出。API napi_ref_threadsafe_function 和 napi_unref_threadsafe_function 用于此目的。
napi_unref_threadsafe_function 既不会将线程安全函数标记为可销毁，napi_ref_threadsafe_function 也不会阻止其被销毁。
napi_create_threadsafe_function
[历史]
| 版本 | 变更 |
|---|---|
| v12.6.0, v10.17.0 | 使 func 参数可选，并使用自定义 call_js_cb。 |
| v10.6.0 | 新增于：v10.6.0 |
N-API 版本：4
NAPI_EXTERN napi_status
napi_create_threadsafe_function(napi_env env,
napi_value func,
napi_value async_resource,
napi_value async_resource_name,
size_t max_queue_size,
size_t initial_thread_count,
void* thread_finalize_data,
napi_finalize thread_finalize_cb,
void* context,
napi_threadsafe_function_call_js call_js_cb,
napi_threadsafe_function* result);[in] env: API 调用的环境。[in] func: 可选的 JavaScript 函数，用于从另一个线程调用。如果将NULL传递给call_js_cb，则必须提供它。[in] async_resource: 与异步工作相关的可选对象，它将传递给可能的async_hooksinit钩子。[in] async_resource_name: 一个 JavaScript 字符串，用于提供正在提供的资源类型的标识符，以便async_hooksAPI 公开的诊断信息使用。[in] max_queue_size: 队列的最大大小。0表示无限制。[in] initial_thread_count: 初始获取次数，即包括主线程在内的初始线程数，这些线程将使用此函数。[in] thread_finalize_data: 可选数据，将传递给thread_finalize_cb。[in] thread_finalize_cb: 可选函数，在napi_threadsafe_function被销毁时调用。[in] context: 可选数据，附加到生成的napi_threadsafe_function。[in] call_js_cb: 可选回调，它在不同线程上的调用作出响应时调用 JavaScript 函数。此回调将在主线程上调用。如果没有给出，则 JavaScript 函数将使用无参数和undefined作为其this值来调用。napi_threadsafe_function_call_js提供更多详细信息。[out] result: 异步线程安全的 JavaScript 函数。
变更历史：
- 实验性（定义了
NAPI_EXPERIMENTAL）：在call_js_cb中抛出的未捕获异常将使用'uncaughtException'事件进行处理，而不是被忽略。
napi_get_threadsafe_function_context
新增于: v10.6.0
N-API 版本: 4
NAPI_EXTERN napi_status
napi_get_threadsafe_function_context(napi_threadsafe_function func,
void** result);[in] func: 用于检索上下文的线程安全函数。[out] result: 用于存储上下文的地址。
此 API 可从使用 func 的任何线程调用。
napi_call_threadsafe_function
[历史]
| 版本 | 变更 |
|---|---|
| v14.5.0 | 已撤销对 napi_would_deadlock 的支持。 |
| v14.1.0 | 当从主线程或工作线程使用 napi_tsfn_blocking 调用且队列已满时，返回 napi_would_deadlock。 |
| v10.6.0 | 新增于: v10.6.0 |
N-API 版本: 4
NAPI_EXTERN napi_status
napi_call_threadsafe_function(napi_threadsafe_function func,
void* data,
napi_threadsafe_function_call_mode is_blocking);[in] func: 要调用的异步线程安全 JavaScript 函数。[in] data: 通过在创建线程安全 JavaScript 函数时提供的回调call_js_cb发送到 JavaScript 的数据。[in] is_blocking: 标志，其值可以是napi_tsfn_blocking（表示如果队列已满则调用应阻塞）或napi_tsfn_nonblocking（表示如果队列已满，则调用应立即返回状态napi_queue_full）。
此 API 不应从 JavaScript 线程使用 napi_tsfn_blocking 调用，因为如果队列已满，它可能会导致 JavaScript 线程死锁。
如果从任何线程使用 abort 设置为 napi_tsfn_abort 调用了 napi_release_threadsafe_function()，则此 API 将返回 napi_closing。只有当 API 返回 napi_ok 时，该值才会添加到队列中。
此 API 可从使用 func 的任何线程调用。
napi_acquire_threadsafe_function
新增于: v10.6.0
N-API 版本: 4
NAPI_EXTERN napi_status
napi_acquire_threadsafe_function(napi_threadsafe_function func);[in] func: 即将开始使用的异步线程安全 JavaScript 函数。
线程在将 func 传递给任何其他线程安全函数 API 之前，应该调用此 API 以指示它将使用 func。这可以防止当所有其他线程停止使用 func 时，func 被销毁。
此 API 可以从任何将开始使用 func 的线程调用。
napi_release_threadsafe_function
新增于: v10.6.0
N-API 版本: 4
NAPI_EXTERN napi_status
napi_release_threadsafe_function(napi_threadsafe_function func,
napi_threadsafe_function_release_mode mode);[in] func: 要递减引用计数的异步线程安全 JavaScript 函数。[in] mode: 标志，其值可以是napi_tsfn_release（指示当前线程不会再调用线程安全函数）或napi_tsfn_abort（指示除了当前线程之外，任何其他线程也不应再调用线程安全函数）。如果设置为napi_tsfn_abort，则对napi_call_threadsafe_function()的进一步调用将返回napi_closing，并且不会再将任何值放入队列中。
当线程停止使用 func 时，应调用此 API。在调用此 API 后将 func 传递给任何线程安全 API 将产生未定义的结果，因为 func 可能已被销毁。
此 API 可以从任何将停止使用 func 的线程调用。
napi_ref_threadsafe_function
新增于: v10.6.0
N-API 版本: 4
NAPI_EXTERN napi_status
napi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);[in] env: API 调用的环境。[in] func: 要引用的线程安全函数。
此 API 用于指示主线程上运行的事件循环在 func 被销毁之前不应退出。类似于 uv_ref，它也是幂等的。
napi_unref_threadsafe_function 既不会将线程安全函数标记为可销毁，napi_ref_threadsafe_function 也不会阻止其被销毁。napi_acquire_threadsafe_function 和 napi_release_threadsafe_function 可用于此目的。
此 API 只能从主线程调用。
napi_unref_threadsafe_function
新增于: v10.6.0
N-API 版本: 4
NAPI_EXTERN napi_status
napi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);[in] env: API 调用的环境。[in] func: 要取消引用的线程安全函数。
此 API 用于指示主线程上运行的事件循环可以在 func 被销毁之前退出。类似于 uv_unref，它也是幂等的。
此 API 只能从主线程调用。
杂项工具
node_api_get_module_file_name
新增于：v15.9.0, v14.18.0, v12.22.0
N-API 版本：9
NAPI_EXTERN napi_status
node_api_get_module_file_name(node_api_basic_env env, const char** result);[in] env: API 调用的环境。[out] result: 包含加载附加组件位置的绝对路径的 URL。对于本地文件系统上的文件，它将以file://开头。该字符串以 null 结尾，属于env，因此不得修改或释放。
如果附加组件加载过程在加载过程中未能确定附加组件的文件名，则 result 可能为空字符串。