Node-API 版本矩阵
¥Node-API version matrix
Node-API 版本是附加的，并且独立于 Node.js 进行版本控制。版本 4 是版本 3 的扩展，因为它具有版本 3 的所有 API，并增加了一些内容。这意味着无需为列为支持更高版本的 Node.js 的新版本重新编译。
¥Node-API versions are additive and versioned independently from Node.js. Version 4 is an extension to version 3 in that it has all of the APIs from version 3 with some additions. This means that it is not necessary to recompile for new versions of Node.js which are listed as supporting a later version.
| 1 | 2 | 3 | |
|---|---|---|---|
| v6.x | v6.14.2* | ||
| v8.x | v8.6.0** | v8.10.0* | v8.11.2 |
| v9.x | v9.0.0* | v9.3.0* | v9.11.0* |
| ≥ v10.x | 所有版本 | 所有版本 | 所有版本 |
| 4 | 5 | 6 | 7 | 8 | |
|---|---|---|---|---|---|
| v10.x | v10.16.0 | v10.17.0 | v10.20.0 | v10.23.0 | |
| v11.x | v11.8.0 | ||||
| v12.x | v12.0.0 | v12.11.0 | v12.17.0 | v12.19.0 | v12.22.0 |
| v13.x | v13.0.0 | v13.0.0 | |||
| v14.x | v14.0.0 | v14.0.0 | v14.0.0 | v14.12.0 | v14.17.0 |
| v15.x | v15.0.0 | v15.0.0 | v15.0.0 | v15.0.0 | v15.12.0 |
| v16.x | v16.0.0 | v16.0.0 | v16.0.0 | v16.0.0 | v16.0.0 |
- Node-API 是实验性的。
¥* Node-API was experimental.
** Node.js 8.0.0 包含 Node-API 作为实验性的。它作为 Node-API 版本 1 发布，但继续改进直到 Node.js 8.6.0。API 在 Node.js 8.6.0 之前的版本中有所不同。我们推荐 Node-API 版本 3 或更高版本。
¥** Node.js 8.0.0 included Node-API as experimental. It was released as Node-API version 1 but continued to evolve until Node.js 8.6.0. The API is different in versions prior to Node.js 8.6.0. We recommend Node-API version 3 or later.
为 Node-API 记录的每个 API 都有一个名为 added in: 的标头，而稳定的 API 将有一个额外的标头 Node-API version:。当使用支持 Node-API version: 或更高版本中所示的 Node-API 版本的 Node.js 版本时，API 可直接使用。当使用不支持列出的 Node-API version: 的 Node.js 版本时，或者如果没有列出 Node-API version:，则只有在包含 node_api.h 或 js_native_api.h 之前包含 #define NAPI_EXPERIMENTAL 时，API 才可用。如果某个 API 在晚于 added in: 中所示版本的 Node.js 版本上似乎不可用，那么这很可能是明显缺失的原因。
¥Each API documented for Node-API will have a header named added in:, and APIs
which are stable will have the additional header Node-API version:.
APIs are directly usable when using a Node.js version which supports
the Node-API version shown in Node-API version: or higher.
When using a Node.js version that does not support the
Node-API version: listed or if there is no Node-API version: listed,
then the API will only be available if
#define NAPI_EXPERIMENTAL precedes the inclusion of node_api.h
or js_native_api.h. If an API appears not to be available on
a version of Node.js which is later than the one shown in added in: then
this is most likely the reason for the apparent absence.
与从原生代码访问 ECMAScript 功能严格相关的 Node-API 可以在 js_native_api.h 和 js_native_api_types.h 中单独找到。这些标头中定义的 API 包含在 node_api.h 和 node_api_types.h 中。标头以这种方式构造，以便允许在 Node.js 之外实现 Node-API。对于这些实现，Node.js 特定的 API 可能不适用。
¥The Node-APIs associated strictly with accessing ECMAScript features from native
code can be found separately in js_native_api.h and js_native_api_types.h.
The APIs defined in these headers are included in node_api.h and
node_api_types.h. The headers are structured in this way in order to allow
implementations of Node-API outside of Node.js. For those implementations the
Node.js specific APIs may not be applicable.
插件的 Node.js 特定部分可以与将实际功能暴露给 JavaScript 环境的代码分开，以便后者可以与 Node-API 的多个实现一起使用。在下面的示例中，addon.c 和 addon.h 仅引用 js_native_api.h。这确保了 addon.c 可以被重用以针对 Node-API 的 Node.js 实现或 Node.js 之外的任何 Node-API 实现进行编译。
¥The Node.js-specific parts of an addon can be separated from the code that
exposes the actual functionality to the JavaScript environment so that the
latter may be used with multiple implementations of Node-API. In the example
below, addon.c and addon.h refer only to js_native_api.h. This ensures
that addon.c can be reused to compile against either the Node.js
implementation of Node-API or any implementation of Node-API outside of Node.js.
addon_node.c 是一个单独的文件，其中包含插件的 Node.js 特定入口点，并在插件加载到 Node.js 环境时通过调用 addon.c 来实例化插件。
¥addon_node.c is a separate file that contains the Node.js specific entry point
to the addon and which instantiates the addon by calling into addon.c when the
addon is loaded into a Node.js environment.
// addon.h
#ifndef _ADDON_H_
#define _ADDON_H_
#include <js_native_api.h>
napi_value create_addon(napi_env env);
#endif // _ADDON_H_ // addon.c
#include "addon.h"
#define NAPI_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 (!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;
NAPI_CALL(env, napi_create_object(env, &result));
napi_value exported_function;
NAPI_CALL(env, napi_create_function(env,
"doSomethingUseful",
NAPI_AUTO_LENGTH,
DoSomethingUseful,
NULL,
&exported_function));
NAPI_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() {
// 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);
}