Node-API | Node.js API 文档

¥Stability: 2 - Stable

Node-API（以前称为 N-API）是用于构建原生插件的 API。它独立于底层 JavaScript 运行时（例如 V8），并作为 Node.js 本身的一部分进行维护。此 API 将在 Node.js 的各个版本中保持稳定的应用二进制接口 (ABI)。它旨在将插件与底层 JavaScript 引擎的变化隔离开来，并允许为一个主要版本编译的模块无需重新编译即可在以后的 Node.js 主要版本上运行。ABI 稳定性指南提供了更深入的解释。

¥Node-API (formerly N-API) is an API for building native Addons. It is independent from the underlying JavaScript runtime (for example, V8) and is maintained as part of Node.js itself. This API will be Application Binary Interface (ABI) stable across versions of Node.js. It is intended to insulate addons from changes in the underlying JavaScript engine and allow modules compiled for one major version to run on later major versions of Node.js without recompilation. The ABI Stability guide provides a more in-depth explanation.

插件是使用标头为 C++ 插件的部分中概述的相同方法/工具构建/打包的。唯一的区别是原生代码使用的 API 集。不使用 V8 或 Node.js 的原生抽象 API，而是使用 Node-API 中可用的函数。

¥Addons are built/packaged with the same approach/tools outlined in the section titled C++ Addons. The only difference is the set of APIs that are used by the native code. Instead of using the V8 or Native Abstractions for Node.js APIs, the functions available in Node-API are used.

Node-API 公开的 API 通常用于创建和操作 JavaScript 值。概念和操作通常映射到 ECMA-262 语言规范中指定的想法。API 具有以下属性：

¥APIs exposed by Node-API are generally used to create and manipulate JavaScript values. Concepts and operations generally map to ideas specified in the ECMA-262 Language Specification. The APIs have the following properties:

所有 Node-API 调用都会返回 napi_status 类型的状态代码。此状态指示 API 调用是成功还是失败。

¥All Node-API calls return a status code of type napi_status. This status indicates whether the API call succeeded or failed.
API 的返回值通过 out 参数传递。

¥The API's return value is passed via an out parameter.
所有 JavaScript 值都被抽象为一个名为 napi_value 的不透明类型。

¥All JavaScript values are abstracted behind an opaque type named napi_value.
如果出现错误状态代码，可以使用 napi_get_last_error_info 获取附加信息。可以在错误处理部分错误处理中找到更多信息。

¥In case of an error status code, additional information can be obtained using napi_get_last_error_info. More information can be found in the error handling section Error handling.

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 代码，第二部分显示插件中实际使用的内容。

¥Node-API is a C API that ensures ABI stability across Node.js versions and different compiler levels. A C++ API can be easier to use. To support using C++, the project maintains a C++ wrapper module called node-addon-api. This wrapper provides an inlinable C++ API. Binaries built with node-addon-api will depend on the symbols for the Node-API C-based functions exported by Node.js. node-addon-api is a more efficient way to write code that calls Node-API. Take, for example, the following node-addon-api code. The first section shows the node-addon-api code and the second section shows what actually gets used in the 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;
}

最终结果是该插件仅使用导出的 C API。因此，它仍然可以获得 C API 提供的 ABI 稳定性的好处。

¥The end result is that the addon only uses the exported C APIs. As a result, it still gets the benefits of the ABI stability provided by the C API.

当使用 node-addon-api 而不是 C API 时，从 node-addon-api 的 API 文档开始。

¥When using node-addon-api instead of the C APIs, start with the API docs for node-addon-api.

Node-API 资源为刚刚开始使用 Node-API 和 node-addon-api 的开发者提供了极好的指导和技巧。可以在 Node-API 媒体页面上找到其他媒体资源。

¥The Node-API Resource offers an excellent orientation and tips for developers just getting started with Node-API and node-addon-api. Additional media resources can be found on the Node-API Media page.