Node.js v24.0.0 文档

node-gyp#

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

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

CMake.js#

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

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

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 时一起上传。当安装原生插件时，二进制文件会从 npm 下载并立即提供给模块用户。

napi_handle_scope#

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

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

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

napi_escapable_handle_scope#

可转义的句柄作用域是一种特殊类型的句柄作用域，用于将特定句柄作用域中创建的值返回到父作用域。

napi_ref#

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

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

napi_type_tag#

一个 128 位的值，存储为两个无符号的 64 位整数。 它充当 UUID，JavaScript 对象或 外部对象 可以使用它进行“标记”，以确保它们属于某种类型。 这是一个比 napi_instanceof 更强的检查，因为如果对象的原型已被操作，后者可能会报告误报。 类型标记最适合与 napi_wrap 结合使用，因为它确保从包装对象检索的指针可以安全地强制转换为先前应用于 JavaScript 对象的类型标记所对应的本机类型。

typedef struct {
  uint64_t lower;
  uint64_t upper;
} napi_type_tag; copy

napi_async_cleanup_hook_handle#

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

napi_callback_info#

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

napi_callback#

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

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

除非由于 对象生命周期管理 中讨论的原因，否则在 napi_callback 中创建句柄和/或回调作用域不是必需的。

node_api_basic_finalize#

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

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

除非由于 对象生命周期管理 中讨论的原因，否则在函数体内部创建句柄和/或回调作用域不是必需的。

由于可以在 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#

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

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

更改历史

• 实验性的 (已定义 NAPI_EXPERIMENTAL)

  除非与 node_api_post_finalizer 一起使用，否则此类型的函数可能不再用作终结器。必须改用 node_api_basic_finalize。可以通过定义 NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT 来关闭此功能。

napi_async_execute_callback#

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

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

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

napi_async_complete_callback#

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

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

除非由于 对象生命周期管理 中讨论的原因，否则在函数体内部创建句柄和/或回调作用域不是必需的。

napi_threadsafe_function_call_js#

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

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

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

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

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

• [in] env：用于 API 调用的环境，如果线程安全函数正在被拆解并且可能需要释放 data，则为 NULL。
• [in] js_callback：要调用的 JavaScript 函数，如果线程安全函数正在被拆解并且可能需要释放 data，则为 NULL。 如果创建线程安全函数时没有 js_callback，它也可能为 NULL。
• [in] context：创建线程安全函数时使用的可选数据。
• [in] data：由辅助线程创建的数据。 回调负责将此原生数据转换为 JavaScript 值（使用 Node-API 函数），这些值可以在调用 js_callback 时作为参数传递。 此指针完全由线程和此回调管理。 因此，此回调应释放数据。

除非由于 对象生命周期管理 中讨论的原因，否则在函数体内部创建句柄和/或回调作用域不是必需的。

napi_cleanup_hook#

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

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

typedef void (*napi_cleanup_hook)(void* data); copy

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

napi_async_cleanup_hook#

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

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

typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,
                                        void* data); copy

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

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

napi_get_last_error_info#

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

• [in] env：API 在其下调用的环境。
• [out] result：包含有关错误的更多信息的 napi_extended_error_info 结构。

如果 API 成功，则返回 napi_ok。

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

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

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

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

napi_throw#

NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); copy

• [in] env：API 在其下调用的环境。
• [in] error: 要抛出的 JavaScript 值。

如果 API 成功，则返回 napi_ok。

此 API 抛出提供的 JavaScript 值。

napi_throw_error#

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

• [in] env：API 在其下调用的环境。
• [in] code: 可选的错误代码，用于设置在错误上。
• [in] msg: C 字符串，表示与错误相关联的文本。

如果 API 成功，则返回 napi_ok。

此 API 抛出一个带有提供的文本的 JavaScript Error。

napi_throw_type_error#

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

• [in] env：API 在其下调用的环境。
• [in] code: 可选的错误代码，用于设置在错误上。
• [in] msg: C 字符串，表示与错误相关联的文本。

如果 API 成功，则返回 napi_ok。

此 API 抛出一个带有提供的文本的 JavaScript TypeError。

napi_throw_range_error#

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

• [in] env：API 在其下调用的环境。
• [in] code: 可选的错误代码，用于设置在错误上。
• [in] msg: C 字符串，表示与错误相关联的文本。

如果 API 成功，则返回 napi_ok。

此 API 抛出一个带有提供的文本的 JavaScript RangeError。

node_api_throw_syntax_error#

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

• [in] env：API 在其下调用的环境。
• [in] code: 可选的错误代码，用于设置在错误上。
• [in] msg: C 字符串，表示与错误相关联的文本。

如果 API 成功，则返回 napi_ok。

此 API 抛出一个带有提供的文本的 JavaScript SyntaxError。

napi_is_error#

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

• [in] env：API 在其下调用的环境。
• [in] value: 要检查的 napi_value。
• [out] result: 布尔值，如果 napi_value 表示一个错误，则设置为 true，否则为 false。

如果 API 成功，则返回 napi_ok。

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

napi_create_error#

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

• [in] env：API 在其下调用的环境。
• [in] code: 可选的 napi_value，包含与错误相关联的错误代码字符串。
• [in] msg: napi_value，引用一个 JavaScript string，用作 Error 的消息。
• [out] result: napi_value，表示创建的错误。

如果 API 成功，则返回 napi_ok。

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

napi_create_type_error#

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

• [in] env：API 在其下调用的环境。
• [in] code: 可选的 napi_value，包含与错误相关联的错误代码字符串。
• [in] msg: napi_value，引用一个 JavaScript string，用作 Error 的消息。
• [out] result: napi_value，表示创建的错误。

如果 API 成功，则返回 napi_ok。

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

napi_create_range_error#

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

• [in] env：API 在其下调用的环境。
• [in] code: 可选的 napi_value，包含与错误相关联的错误代码字符串。
• [in] msg: napi_value，引用一个 JavaScript string，用作 Error 的消息。
• [out] result: napi_value，表示创建的错误。

如果 API 成功，则返回 napi_ok。

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

node_api_create_syntax_error#

NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,
                                                     napi_value code,
                                                     napi_value msg,
                                                     napi_value* result); copy

• [in] env：API 在其下调用的环境。
• [in] code: 可选的 napi_value，包含与错误相关联的错误代码字符串。
• [in] msg: napi_value，引用一个 JavaScript string，用作 Error 的消息。
• [out] result: napi_value，表示创建的错误。

如果 API 成功，则返回 napi_ok。

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

napi_get_and_clear_last_exception#

napi_status napi_get_and_clear_last_exception(napi_env env,
                                              napi_value* result); copy

• [in] env：API 在其下调用的环境。
• [out] result: 如果存在挂起的异常，则为该异常，否则为 NULL。

如果 API 成功，则返回 napi_ok。

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

napi_is_exception_pending#

napi_status napi_is_exception_pending(napi_env env, bool* result); copy

• [in] env：API 在其下调用的环境。
• [out] result: 布尔值，如果存在挂起的异常，则设置为 true。

如果 API 成功，则返回 napi_ok。

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

napi_fatal_exception#

napi_status napi_fatal_exception(napi_env env, napi_value err); copy

• [in] env：API 在其下调用的环境。
• [in] err: 传递给 'uncaughtException' 的错误。

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

napi_fatal_error#

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

• [in] location: 可选的错误发生位置。
• [in] location_len: 位置的长度（以字节为单位），如果以 null 结尾，则为 NAPI_AUTO_LENGTH。
• [in] message: 与错误关联的消息。
• [in] message_len: 消息的长度（以字节为单位），如果以 null 结尾，则为 NAPI_AUTO_LENGTH。

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

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

napi_open_handle_scope#

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

• [in] env：API 在其下调用的环境。
• [out] result: napi_value，表示新的作用域。

如果 API 成功，则返回 napi_ok。

此 API 打开一个新作用域。

napi_close_handle_scope#

NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,
                                                napi_handle_scope scope); copy

• [in] env：API 在其下调用的环境。
• [in] scope: napi_value，表示要关闭的作用域。

如果 API 成功，则返回 napi_ok。

此 API 关闭传入的作用域。 作用域必须以与创建顺序相反的顺序关闭。

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

napi_open_escapable_handle_scope#

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

• [in] env：API 在其下调用的环境。
• [out] result: napi_value，表示新的作用域。

如果 API 成功，则返回 napi_ok。

此 API 打开一个新的作用域，可以从中将一个对象提升到外部作用域。

napi_close_escapable_handle_scope#

NAPI_EXTERN napi_status
    napi_close_escapable_handle_scope(napi_env env,
                                      napi_handle_scope scope); copy

• [in] env：API 在其下调用的环境。
• [in] scope: napi_value，表示要关闭的作用域。

如果 API 成功，则返回 napi_ok。

此 API 关闭传入的作用域。 作用域必须以与创建顺序相反的顺序关闭。

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

napi_escape_handle#

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

• [in] env：API 在其下调用的环境。
• [in] scope: napi_value，表示当前作用域。
• [in] escapee: napi_value，表示要逃逸的 JavaScript Object。
• [out] result: napi_value，表示外部作用域中逃逸的 Object 的句柄。

如果 API 成功，则返回 napi_ok。

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

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

napi_create_reference#

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

• [in] env：API 在其下调用的环境。
• [in] value：要为其创建引用的 napi_value。
• [in] initial_refcount：新引用的初始引用计数。
• [out] result：指向新引用的 napi_ref。

如果 API 成功，则返回 napi_ok。

此 API 使用指定的引用计数创建对传入值的新的引用。

napi_delete_reference#

NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); copy

• [in] env：API 在其下调用的环境。
• [in] ref：要删除的 napi_ref。

如果 API 成功，则返回 napi_ok。

此 API 删除传入的引用。

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

napi_reference_ref#

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

• [in] env：API 在其下调用的环境。
• [in] ref：将为其递增引用计数的 napi_ref。
• [out] result：新的引用计数。

如果 API 成功，则返回 napi_ok。

此 API 递增传入引用的引用计数，并返回结果引用计数。

napi_reference_unref#

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

• [in] env：API 在其下调用的环境。
• [in] ref：将为其递减引用计数的 napi_ref。
• [out] result：新的引用计数。

如果 API 成功，则返回 napi_ok。

此 API 递减传入引用的引用计数，并返回结果引用计数。

napi_get_reference_value#

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

• [in] env：API 在其下调用的环境。
• [in] ref：要为其请求相应值的 napi_ref。
• [out] result：由 napi_ref 引用的 napi_value。

如果 API 成功，则返回 napi_ok。

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

napi_add_env_cleanup_hook#

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

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

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

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

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

对于异步清理，可以使用 napi_add_async_cleanup_hook。

napi_remove_env_cleanup_hook#

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

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

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

napi_add_async_cleanup_hook#

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

• [in] env：API 在其下调用的环境。
• [in] hook：在环境拆卸时调用的函数指针。
• [in] arg：在调用 hook 时传递给它的指针。
• [out] remove_handle：引用异步清理钩子的可选句柄。

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

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

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

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

napi_remove_async_cleanup_hook#

NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(
    napi_async_cleanup_hook_handle remove_handle); copy

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

取消注册与 remove_handle 对应的清理钩子。这将阻止执行钩子，除非它已经开始执行。必须在从 napi_add_async_cleanup_hook 获取的任何 napi_async_cleanup_hook_handle 值上调用此函数。

napi_key_collection_mode#

typedef enum {
  napi_key_include_prototypes,
  napi_key_own_only
} napi_key_collection_mode; copy

描述 Keys/Properties 过滤器枚举

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

napi_key_own_only 将收集的属性限制为仅给定的对象。 napi_key_include_prototypes 将包括对象原型链的所有键。

napi_key_filter#

typedef enum {
  napi_key_all_properties = 0,
  napi_key_writable = 1,
  napi_key_enumerable = 1 << 1,
  napi_key_configurable = 1 << 2,
  napi_key_skip_strings = 1 << 3,
  napi_key_skip_symbols = 1 << 4
} napi_key_filter; copy

属性过滤器位。可以将它们进行“或”运算以构建复合过滤器。

napi_key_conversion#

typedef enum {
  napi_key_keep_numbers,
  napi_key_numbers_to_strings
} napi_key_conversion; copy

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

napi_valuetype#

typedef enum {
  // ES6 types (corresponds to typeof)
  napi_undefined,
  napi_null,
  napi_boolean,
  napi_number,
  napi_string,
  napi_symbol,
  napi_object,
  napi_function,
  napi_external,
  napi_bigint,
} napi_valuetype; copy

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

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

napi_typedarray_type#

typedef enum {
  napi_int8_array,
  napi_uint8_array,
  napi_uint8_clamped_array,
  napi_int16_array,
  napi_uint16_array,
  napi_int32_array,
  napi_uint32_array,
  napi_float32_array,
  napi_float64_array,
  napi_bigint64_array,
  napi_biguint64_array,
} napi_typedarray_type; copy

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

napi_create_array#

napi_status napi_create_array(napi_env env, napi_value* result) copy

• [in] env: 调用 Node-API 的环境。
• [out] result：表示 JavaScript Array 的 napi_value。

如果 API 成功，则返回 napi_ok。

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

napi_create_array_with_length#

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

• [in] env：API 在其下调用的环境。
• [in] length：Array 的初始长度。
• [out] result：表示 JavaScript Array 的 napi_value。

如果 API 成功，则返回 napi_ok。

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

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

napi_create_arraybuffer#

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

• [in] env：API 在其下调用的环境。
• [in] length：要创建的数组缓冲区的长度（以字节为单位）。
• [out] data：指向 ArrayBuffer 的底层字节缓冲区的指针。 可以选择通过传递 NULL 来忽略 data。
• [out] result：表示 JavaScript ArrayBuffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

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

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

napi_create_buffer#

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

• [in] env：API 在其下调用的环境。
• [in] size：底层缓冲区的大小（以字节为单位）。
• [out] data：指向底层缓冲区的原始指针。 可以选择通过传递 NULL 来忽略 data。
• [out] result：表示 node::Buffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

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

napi_create_buffer_copy#

napi_status napi_create_buffer_copy(napi_env env,
                                    size_t length,
                                    const void* data,
                                    void** result_data,
                                    napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] size：输入缓冲区的大小（以字节为单位）（应与新缓冲区的大小相同）。
• [in] data：指向要从中复制的底层缓冲区的原始指针。
• [out] result_data：指向新 Buffer 的底层数据缓冲区的指针。 可以选择通过传递 NULL 来忽略 result_data。
• [out] result：表示 node::Buffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

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

napi_create_date#

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

• [in] env：API 在其下调用的环境。
• [in] time：自 1970 年 1 月 1 日 UTC 以来的 ECMAScript 时间值（以毫秒为单位）。
• [out] result：表示 JavaScript Date 的 napi_value。

如果 API 成功，则返回 napi_ok。

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

此 API 分配一个 JavaScript Date 对象。

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

napi_create_external#

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

• [in] env：API 在其下调用的环境。
• [in] data：指向外部数据的原始指针。
• [in] finalize_cb：当外部值正在被收集时要调用的可选回调。 napi_finalize 提供了更多详细信息。
• [in] finalize_hint: 在垃圾回收期间传递给终结回调的可选提示。
• [out] result：表示外部值的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 分配一个 JavaScript 值，并在其上附加外部数据。 这用于通过 JavaScript 代码传递外部数据，以便以后可以使用 napi_get_value_external 通过本机代码检索它。

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

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

napi_create_external_arraybuffer#

napi_status
napi_create_external_arraybuffer(napi_env env,
                                 void* external_data,
                                 size_t byte_length,
                                 napi_finalize finalize_cb,
                                 void* finalize_hint,
                                 napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] external_data：指向 ArrayBuffer 的底层字节缓冲区的指针。
• [in] byte_length：底层缓冲区的长度（以字节为单位）。
• [in] finalize_cb：当 ArrayBuffer 正在被收集时要调用的可选回调。 napi_finalize 提供了更多详细信息。
• [in] finalize_hint: 在垃圾回收期间传递给终结回调的可选提示。
• [out] result：表示 JavaScript ArrayBuffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

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

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

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

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

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

napi_create_external_buffer#

napi_status napi_create_external_buffer(napi_env env,
                                        size_t length,
                                        void* data,
                                        napi_finalize finalize_cb,
                                        void* finalize_hint,
                                        napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] length：输入缓冲区的大小（以字节为单位）（应与新缓冲区的大小相同）。
• [in] data：指向要暴露给 JavaScript 的底层缓冲区的原始指针。
• [in] finalize_cb：当 ArrayBuffer 正在被收集时要调用的可选回调。 napi_finalize 提供了更多详细信息。
• [in] finalize_hint: 在垃圾回收期间传递给终结回调的可选提示。
• [out] result：表示 node::Buffer 的 napi_value。

如果 API 成功，则返回 napi_ok。

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

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

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

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

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

napi_create_object#

napi_status napi_create_object(napi_env env, napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [out] result：一个 napi_value，代表一个 JavaScript Object。

如果 API 成功，则返回 napi_ok。

此 API 分配一个默认的 JavaScript Object。它等效于在 JavaScript 中执行 new Object()。

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

napi_create_symbol#

napi_status napi_create_symbol(napi_env env,
                               napi_value description,
                               napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] description：可选的 napi_value，引用一个 JavaScript string，将被设置为符号的描述。
• [out] result：一个 napi_value，代表一个 JavaScript symbol。

如果 API 成功，则返回 napi_ok。

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

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

node_api_symbol_for#

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

• [in] env：API 在其下调用的环境。
• [in] utf8description: UTF-8 C 字符串，表示要用作符号描述的文本。
• [in] length：描述字符串的长度（以字节为单位），如果它是以 null 结尾的，则为 NAPI_AUTO_LENGTH。
• [out] result：一个 napi_value，代表一个 JavaScript symbol。

如果 API 成功，则返回 napi_ok。

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

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

napi_create_typedarray#

napi_status napi_create_typedarray(napi_env env,
                                   napi_typedarray_type type,
                                   size_t length,
                                   napi_value arraybuffer,
                                   size_t byte_offset,
                                   napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] type：TypedArray 中元素的标量数据类型。
• [in] length：TypedArray 中的元素数量。
• [in] arraybuffer：作为类型化数组基础的 ArrayBuffer。
• [in] byte_offset：在 ArrayBuffer 中的字节偏移量，从该偏移量开始投影 TypedArray。
• [out] result：一个 napi_value，代表一个 JavaScript TypedArray。

如果 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#

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

• [in] env：API 被调用的环境。
• [in] arraybuffer: 将从中创建缓冲区的 ArrayBuffer。
• [in] byte_offset：在 ArrayBuffer 中的字节偏移量，从该偏移量开始创建缓冲区。
• [in] byte_length：要从 ArrayBuffer 创建的缓冲区的长度（以字节为单位）。
• [out] result：一个 napi_value，代表创建的 JavaScript Buffer 对象。

如果 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#

napi_status napi_create_dataview(napi_env env,
                                 size_t byte_length,
                                 napi_value arraybuffer,
                                 size_t byte_offset,
                                 napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] length：DataView 中的元素数量。
• [in] arraybuffer：作为 DataView 基础的 ArrayBuffer。
• [in] byte_offset：在 ArrayBuffer 中的字节偏移量，从该偏移量开始投影 DataView。
• [out] result：一个 napi_value，代表一个 JavaScript DataView。

如果 API 成功，则返回 napi_ok。

此 API 基于现有的 ArrayBuffer 创建一个 JavaScript DataView 对象。DataView 对象提供了一个类似数组的视图，该视图覆盖了一个底层数据缓冲区，但是它允许 ArrayBuffer 中具有不同大小和类型的项。

要求 byte_length + byte_offset 小于或等于传入数组的大小（以字节为单位）。如果不是，则会引发 RangeError 异常。

JavaScript DataView 对象在 ECMAScript 语言规范的 第 24.3 节中描述。

napi_create_int32#

napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] value：要在 JavaScript 中表示的整数值。
• [out] result：一个 napi_value，代表一个 JavaScript number。

如果 API 成功，则返回 napi_ok。

此 API 用于从 C int32_t 类型转换为 JavaScript number 类型。

JavaScript number 类型在 ECMAScript 语言规范的 第 6.1.6 节中描述。

napi_create_uint32#

napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] value：要在 JavaScript 中表示的无符号整数值。
• [out] result：一个 napi_value，代表一个 JavaScript number。

如果 API 成功，则返回 napi_ok。

此 API 用于从 C uint32_t 类型转换为 JavaScript number 类型。

JavaScript number 类型在 ECMAScript 语言规范的 第 6.1.6 节中描述。

napi_create_int64#

napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] value：要在 JavaScript 中表示的整数值。
• [out] result：一个 napi_value，代表一个 JavaScript number。

如果 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#

napi_status napi_create_double(napi_env env, double value, napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] value：要在 JavaScript 中表示的双精度值。
• [out] result：一个 napi_value，代表一个 JavaScript number。

如果 API 成功，则返回 napi_ok。

此 API 用于从 C double 类型转换为 JavaScript number 类型。

JavaScript number 类型在 ECMAScript 语言规范的 第 6.1.6 节中描述。

napi_create_bigint_int64#

napi_status napi_create_bigint_int64(napi_env env,
                                     int64_t value,
                                     napi_value* result); copy

• [in] env：API 在其下调用的环境。
• [in] value：要在 JavaScript 中表示的整数值。
• [out] result：一个 napi_value，代表一个 JavaScript BigInt。

如果 API 成功，则返回 napi_ok。

此 API 将 C int64_t 类型转换为 JavaScript BigInt 类型。

napi_create_bigint_uint64#

napi_status napi_create_bigint_uint64(napi_env env,
                                      uint64_t value,
                                      napi_value* result); copy

• [in] env：API 在其下调用的环境。
• [in] value：要在 JavaScript 中表示的无符号整数值。
• [out] result：一个 napi_value，代表一个 JavaScript BigInt。

如果 API 成功，则返回 napi_ok。

此 API 将 C uint64_t 类型转换为 JavaScript BigInt 类型。

napi_create_bigint_words#

napi_status napi_create_bigint_words(napi_env env,
                                     int sign_bit,
                                     size_t word_count,
                                     const uint64_t* words,
                                     napi_value* result); copy

• [in] env：API 在其下调用的环境。
• [in] sign_bit：确定生成的 BigInt 将是正数还是负数。
• [in] word_count：words 数组的长度。
• [in] words：一个 uint64_t 小端 64 位字的数组。
• [out] result：一个 napi_value，代表一个 JavaScript BigInt。

如果 API 成功，则返回 napi_ok。

此 API 将一个无符号 64 位字的数组转换为一个 BigInt 值。

生成的 BigInt 的计算公式为：(–1)^sign_bit (words[0] × (2⁶⁴)⁰ + words[1] × (2⁶⁴)¹ + …)

napi_create_string_latin1#

napi_status napi_create_string_latin1(napi_env env,
                                      const char* str,
                                      size_t length,
                                      napi_value* result); copy

• [in] env：API 在其下调用的环境。
• [in] str：表示 ISO-8859-1 编码字符串的字符缓冲区。
• [in] length：字符串的长度（以字节为单位），如果它是以 null 结尾的，则为 NAPI_AUTO_LENGTH。
• [out] result：一个 napi_value，代表一个 JavaScript string。

如果 API 成功，则返回 napi_ok。

此 API 从一个 ISO-8859-1 编码的 C 字符串创建一个 JavaScript string 值。本机字符串被复制。

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

node_api_create_external_string_latin1#

napi_status
node_api_create_external_string_latin1(napi_env env,
                                       char* str,
                                       size_t length,
                                       napi_finalize finalize_callback,
                                       void* finalize_hint,
                                       napi_value* result,
                                       bool* copied); copy

• [in] env：API 在其下调用的环境。
• [in] str：表示 ISO-8859-1 编码字符串的字符缓冲区。
• [in] length：字符串的长度（以字节为单位），如果它是以 null 结尾的，则为 NAPI_AUTO_LENGTH。
• [in] finalize_callback：字符串被收集时要调用的函数。该函数将被调用，并带有以下参数
  • [in] env：插件运行所在的环境。如果字符串是作为工作线程或主 Node.js 实例终止的一部分而被收集的，则此值可能为 null。
  • [in] data：这是作为 void* 指针的 str 值。
  • [in] finalize_hint：这是提供给 API 的 finalize_hint 值。napi_finalize 提供了更多详细信息。此参数是可选的。传递 null 值意味着当相应的 JavaScript 字符串被收集时，不需要通知该插件。
• [in] finalize_hint: 在垃圾回收期间传递给终结回调的可选提示。
• [out] result：一个 napi_value，代表一个 JavaScript string。
• [out] copied：字符串是否被复制。如果是，则终结器将已被调用以销毁 str。

如果 API 成功，则返回 napi_ok。

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

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

napi_create_string_utf16#

napi_status napi_create_string_utf16(napi_env env,
                                     const char16_t* str,
                                     size_t length,
                                     napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] str：表示 UTF16-LE 编码字符串的字符缓冲区。
• [in] length：字符串的长度（以双字节代码单元为单位），如果它是以 null 结尾的，则为 NAPI_AUTO_LENGTH。
• [out] result：一个 napi_value，代表一个 JavaScript string。

如果 API 成功，则返回 napi_ok。

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

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

node_api_create_external_string_utf16#

napi_status
node_api_create_external_string_utf16(napi_env env,
                                      char16_t* str,
                                      size_t length,
                                      napi_finalize finalize_callback,
                                      void* finalize_hint,
                                      napi_value* result,
                                      bool* copied); copy

• [in] env：API 在其下调用的环境。
• [in] str：表示 UTF16-LE 编码字符串的字符缓冲区。
• [in] length：字符串的长度（以双字节代码单元为单位），如果它是以 null 结尾的，则为 NAPI_AUTO_LENGTH。
• [in] finalize_callback：字符串被收集时要调用的函数。该函数将被调用，并带有以下参数
  • [in] env：插件运行所在的环境。如果字符串是作为工作线程或主 Node.js 实例终止的一部分而被收集的，则此值可能为 null。
  • [in] data：这是作为 void* 指针的 str 值。
  • [in] finalize_hint：这是提供给 API 的 finalize_hint 值。napi_finalize 提供了更多详细信息。此参数是可选的。传递 null 值意味着当相应的 JavaScript 字符串被收集时，不需要通知该插件。
• [in] finalize_hint: 在垃圾回收期间传递给终结回调的可选提示。
• [out] result：一个 napi_value，代表一个 JavaScript string。
• [out] copied：字符串是否被复制。如果是，则终结器将已被调用以销毁 str。

如果 API 成功，则返回 napi_ok。

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

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

napi_create_string_utf8#

napi_status napi_create_string_utf8(napi_env env,
                                    const char* str,
                                    size_t length,
                                    napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] str：表示 UTF8 编码字符串的字符缓冲区。
• [in] length：字符串的长度（以字节为单位），如果它是以 null 结尾的，则为 NAPI_AUTO_LENGTH。
• [out] result：一个 napi_value，代表一个 JavaScript string。

如果 API 成功，则返回 napi_ok。

此 API 从一个 UTF8 编码的 C 字符串创建一个 JavaScript string 值。本机字符串被复制。

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

node_api_create_property_key_latin1#

napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
                                                           const char* str,
                                                           size_t length,
                                                           napi_value* result); copy

• [in] env：API 在其下调用的环境。
• [in] str：表示 ISO-8859-1 编码字符串的字符缓冲区。
• [in] length：字符串的长度（以字节为单位），如果它是以 null 结尾的，则为 NAPI_AUTO_LENGTH。
• [out] result：一个 napi_value，表示一个优化的 JavaScript string，用作对象的属性键。

如果 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#

napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
                                                          const char16_t* str,
                                                          size_t length,
                                                          napi_value* result); copy

• [in] env：API 在其下调用的环境。
• [in] str：表示 UTF16-LE 编码字符串的字符缓冲区。
• [in] length：字符串的长度（以双字节代码单元为单位），如果它是以 null 结尾的，则为 NAPI_AUTO_LENGTH。
• [out] result：一个 napi_value，表示一个优化的 JavaScript string，用作对象的属性键。

如果 API 成功，则返回 napi_ok。

此 API 从 UTF16-LE 编码的 C 字符串创建一个优化的 JavaScript string 值，用作对象的属性键。原生字符串会被复制。

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

node_api_create_property_key_utf8#

napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
                                                         const char* str,
                                                         size_t length,
                                                         napi_value* result); copy

• [in] env：API 在其下调用的环境。
• [in] str：表示 UTF8 编码字符串的字符缓冲区。
• [in] length：字符串的长度（以双字节代码单元为单位），如果它是以 null 结尾的，则为 NAPI_AUTO_LENGTH。
• [out] result：一个 napi_value，表示一个优化的 JavaScript string，用作对象的属性键。

如果 API 成功，则返回 napi_ok。

此 API 从 UTF8 编码的 C 字符串创建一个优化的 JavaScript string 值，用作对象的属性键。原生字符串会被复制。

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

napi_get_array_length#

napi_status napi_get_array_length(napi_env env,
                                  napi_value value,
                                  uint32_t* result) copy

• [in] env：API 在其下调用的环境。
• [in] value：napi_value，表示正在查询其长度的 JavaScript Array。
• [out] result：uint32，表示数组的长度。

如果 API 成功，则返回 napi_ok。

此 API 返回数组的长度。

Array 长度在 ECMAScript 语言规范的 Section 22.1.4.1 中描述。

napi_get_arraybuffer_info#

napi_status napi_get_arraybuffer_info(napi_env env,
                                      napi_value arraybuffer,
                                      void** data,
                                      size_t* byte_length) copy

• [in] env：API 在其下调用的环境。
• [in] arraybuffer：napi_value，表示正在查询的 ArrayBuffer。
• [out] data：ArrayBuffer 的底层数据缓冲区。如果 byte_length 为 0，则这可能是 NULL 或任何其他指针值。
• [out] byte_length：底层数据缓冲区的长度（以字节为单位）。

如果 API 成功，则返回 napi_ok。

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

警告：使用此 API 时请小心。底层数据缓冲区的生命周期由 ArrayBuffer 管理，即使在返回后也是如此。使用此 API 的一种可能的安全方法是与 napi_create_reference 结合使用，后者可用于保证对 ArrayBuffer 生命周期的控制。只要没有调用其他可能触发 GC 的 API，也可以在同一个回调中使用返回的数据缓冲区。

napi_get_buffer_info#

napi_status napi_get_buffer_info(napi_env env,
                                 napi_value value,
                                 void** data,
                                 size_t* length) copy

• [in] env：API 在其下调用的环境。
• [in] value：napi_value，表示正在查询的 node::Buffer 或 Uint8Array。
• [out] data：node::Buffer 或 Uint8Array 的底层数据缓冲区。如果 length 为 0，则这可能是 NULL 或任何其他指针值。
• [out] length：底层数据缓冲区的长度（以字节为单位）。

如果 API 成功，则返回 napi_ok。

此方法返回与 napi_get_typedarray_info 相同的 data 和 byte_length。并且 napi_get_typedarray_info 也接受 node::Buffer (Uint8Array) 作为值。

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

警告：使用此 API 时请小心，因为如果底层数据缓冲区由 VM 管理，则无法保证其生命周期。

napi_get_prototype#

napi_status napi_get_prototype(napi_env env,
                               napi_value object,
                               napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [in] object：napi_value，表示要返回其原型的 JavaScript Object。这将返回等效于 Object.getPrototypeOf 的值（这与函数的 prototype 属性不同）。
• [out] result：napi_value，表示给定对象的原型。

如果 API 成功，则返回 napi_ok。

napi_get_typedarray_info#

napi_status napi_get_typedarray_info(napi_env env,
                                     napi_value typedarray,
                                     napi_typedarray_type* type,
                                     size_t* length,
                                     void** data,
                                     napi_value* arraybuffer,
                                     size_t* byte_offset) copy

• [in] env：API 在其下调用的环境。
• [in] typedarray：napi_value，表示要查询其属性的 TypedArray。
• [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 返回类型化数组的各种属性。

如果不需要该属性，则任何 out 参数都可能为 NULL。

警告：使用此 API 时请小心，因为底层数据缓冲区由 VM 管理。

napi_get_dataview_info#

napi_status napi_get_dataview_info(napi_env env,
                                   napi_value dataview,
                                   size_t* byte_length,
                                   void** data,
                                   napi_value* arraybuffer,
                                   size_t* byte_offset) copy

• [in] env：API 在其下调用的环境。
• [in] dataview：napi_value，表示要查询其属性的 DataView。
• [out] byte_length：DataView 中的字节数。
• [out] data：DataView 的底层数据缓冲区。如果 byte_length 为 0，则这可能是 NULL 或任何其他指针值。
• [out] arraybuffer：DataView 的底层 ArrayBuffer。
• [out] byte_offset：从其开始投影 DataView 的数据缓冲区中的字节偏移量。

如果 API 成功，则返回 napi_ok。

如果不需要该属性，则任何 out 参数都可能为 NULL。

此 API 返回 DataView 的各种属性。

napi_get_date_value#

napi_status napi_get_date_value(napi_env env,
                                napi_value value,
                                double* result) copy

• [in] env：API 在其下调用的环境。
• [in] value：napi_value，表示 JavaScript Date。
• [out] result：时间值（double 类型），表示自 1970 年 1 月 1 日午夜（UTC）以来经过的毫秒数。

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

如果 API 成功，则返回 napi_ok。 如果传入非 date 类型的 napi_value，则返回 napi_date_expected。

此 API 返回给定 JavaScript Date 的 C double 类型的时间值。

napi_get_value_bool#

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

• [in] env：API 在其下调用的环境。
• [in] value：napi_value，表示 JavaScript Boolean。
• [out] result：给定 JavaScript Boolean 的 C boolean 原始类型等效值。

如果 API 成功，则返回 napi_ok。 如果传入非 boolean 类型的 napi_value，则返回 napi_boolean_expected。

此 API 返回给定 JavaScript Boolean 的 C boolean 原始类型等效值。

napi_get_value_double#

napi_status napi_get_value_double(napi_env env,
                                  napi_value value,
                                  double* result) copy

• [in] env：API 在其下调用的环境。
• [in] value：napi_value，表示 JavaScript number。
• [out] result：给定 JavaScript number 的 C double 原始类型等效值。

如果 API 成功，则返回 napi_ok。 如果传入非 number 类型的 napi_value，则返回 napi_number_expected。

此 API 返回给定 JavaScript number 的 C double 原始类型等效值。

napi_get_value_bigint_int64#

napi_status napi_get_value_bigint_int64(napi_env env,
                                        napi_value value,
                                        int64_t* result,
                                        bool* lossless); copy

• [in] env: API 调用的环境
• [in] value：napi_value，表示 JavaScript BigInt。
• [out] result：给定 JavaScript BigInt 的 C int64_t 原始类型等效值。
• [out] lossless：指示 BigInt 值是否无损转换。

如果 API 成功，则返回 napi_ok。 如果传入非 BigInt 类型的值，则返回 napi_bigint_expected。

此 API 返回给定 JavaScript BigInt 的 C int64_t 原始类型等效值。 如果需要，它将截断该值，并将 lossless 设置为 false。

napi_get_value_bigint_uint64#

napi_status napi_get_value_bigint_uint64(napi_env env,
                                        napi_value value,
                                        uint64_t* result,
                                        bool* lossless); copy

• [in] env：API 在其下调用的环境。
• [in] value：napi_value，表示 JavaScript BigInt。
• [out] result：给定 JavaScript BigInt 的 C uint64_t 原始类型等效值。
• [out] lossless：指示 BigInt 值是否无损转换。

如果 API 成功，则返回 napi_ok。 如果传入非 BigInt 类型的值，则返回 napi_bigint_expected。

此 API 返回给定 JavaScript BigInt 对应的 C uint64_t 原始类型值。如果需要，它会截断该值，并将 lossless 设置为 false。

napi_get_value_bigint_words#

napi_status napi_get_value_bigint_words(napi_env env,
                                        napi_value value,
                                        int* sign_bit,
                                        size_t* word_count,
                                        uint64_t* words); copy

• [in] env：API 在其下调用的环境。
• [in] value：napi_value，表示 JavaScript BigInt。
• [out] sign_bit: 整数，表示 JavaScript BigInt 是正数还是负数。
• [in/out] word_count: 必须初始化为 words 数组的长度。返回时，它将被设置为存储此 BigInt 所需的实际字数。
• [out] words: 指向预分配的 64 位字数组的指针。

如果 API 成功，则返回 napi_ok。

此 API 将单个 BigInt 值转换为符号位、64 位小端数组和数组中的元素数。sign_bit 和 words 可以都设置为 NULL，以便仅获取 word_count。

napi_get_value_external#

napi_status napi_get_value_external(napi_env env,
                                    napi_value value,
                                    void** result) copy

• [in] env：API 在其下调用的环境。
• [in] value: 表示 JavaScript 外部值的 napi_value。
• [out] result: 指向 JavaScript 外部值所包装数据的指针。

如果 API 成功，则返回 napi_ok。如果传入的不是外部 napi_value，则返回 napi_invalid_arg。

此 API 检索先前传递给 napi_create_external() 的外部数据指针。

napi_get_value_int32#

napi_status napi_get_value_int32(napi_env env,
                                 napi_value value,
                                 int32_t* result) copy

• [in] env：API 在其下调用的环境。
• [in] value：napi_value，表示 JavaScript number。
• [out] result: 给定 JavaScript number 对应的 C int32 原始类型值。

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

此 API 返回给定 JavaScript number 对应的 C int32 原始类型值。

如果数字超过 32 位整数的范围，则结果将被截断为最低 32 位的值。如果值大于 2³¹ - 1，则可能导致较大的正数变为负数。

非有限数字值（NaN、+Infinity 或 -Infinity）会将结果设置为零。

napi_get_value_int64#

napi_status napi_get_value_int64(napi_env env,
                                 napi_value value,
                                 int64_t* result) copy

• [in] env：API 在其下调用的环境。
• [in] value：napi_value，表示 JavaScript number。
• [out] result: 给定 JavaScript number 对应的 C int64 原始类型值。

如果 API 成功，则返回 napi_ok。 如果传入非 number 类型的 napi_value，则返回 napi_number_expected。

此 API 返回给定 JavaScript number 对应的 C int64 原始类型值。

超出 Number.MIN_SAFE_INTEGER -(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) 范围的 number 值会失去精度。

非有限数字值（NaN、+Infinity 或 -Infinity）会将结果设置为零。

napi_get_value_string_latin1#

napi_status napi_get_value_string_latin1(napi_env env,
                                         napi_value value,
                                         char* buf,
                                         size_t bufsize,
                                         size_t* result) copy

• [in] env：API 在其下调用的环境。
• [in] value: 表示 JavaScript 字符串的 napi_value。
• [in] buf: 用于写入 ISO-8859-1 编码字符串的缓冲区。如果传入 NULL，则在 result 中返回字符串的字节长度（不包括空终止符）。
• [in] bufsize: 目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以 null 终止。
• [out] result: 复制到缓冲区的字节数（不包括空终止符）。

如果 API 成功，则返回 napi_ok。如果传入的不是 string napi_value，则返回 napi_string_expected。

此 API 返回与传入值对应的 ISO-8859-1 编码的字符串。

napi_get_value_string_utf8#

napi_status napi_get_value_string_utf8(napi_env env,
                                       napi_value value,
                                       char* buf,
                                       size_t bufsize,
                                       size_t* result) copy

• [in] env：API 在其下调用的环境。
• [in] value: 表示 JavaScript 字符串的 napi_value。
• [in] buf: 用于写入 UTF8 编码字符串的缓冲区。如果传入 NULL，则在 result 中返回字符串的字节长度（不包括空终止符）。
• [in] bufsize: 目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以 null 终止。
• [out] result: 复制到缓冲区的字节数（不包括空终止符）。

如果 API 成功，则返回 napi_ok。如果传入的不是 string napi_value，则返回 napi_string_expected。

此 API 返回与传入值对应的 UTF8 编码的字符串。

napi_get_value_string_utf16#

napi_status napi_get_value_string_utf16(napi_env env,
                                        napi_value value,
                                        char16_t* buf,
                                        size_t bufsize,
                                        size_t* result) copy

• [in] env：API 在其下调用的环境。
• [in] value: 表示 JavaScript 字符串的 napi_value。
• [in] buf: 用于写入 UTF16-LE 编码字符串的缓冲区。如果传入 NULL，则返回字符串中 2 字节代码单元的长度（不包括空终止符）。
• [in] bufsize: 目标缓冲区的大小。当此值不足时，返回的字符串将被截断并以 null 终止。
• [out] result: 复制到缓冲区的 2 字节代码单元数（不包括空终止符）。

如果 API 成功，则返回 napi_ok。如果传入的不是 string napi_value，则返回 napi_string_expected。

此 API 返回与传入值对应的 UTF16 编码的字符串。

napi_get_value_uint32#

napi_status napi_get_value_uint32(napi_env env,
                                  napi_value value,
                                  uint32_t* result) copy

• [in] env：API 在其下调用的环境。
• [in] value：napi_value，表示 JavaScript number。
• [out] result: 给定 napi_value 对应的 C 原始类型值，类型为 uint32_t。

如果 API 成功，则返回 napi_ok。 如果传入非 number 类型的 napi_value，则返回 napi_number_expected。

此 API 返回给定 napi_value 对应的 C 原始类型值，类型为 uint32_t。

napi_get_boolean#

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

• [in] env：API 在其下调用的环境。
• [in] value: 要检索的布尔值。
• [out] result: 表示要检索的 JavaScript Boolean 单例的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 用于返回用于表示给定布尔值的 JavaScript 单例对象。

napi_get_global#

napi_status napi_get_global(napi_env env, napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [out] result: 表示 JavaScript global 对象的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回 global 对象。

napi_get_null#

napi_status napi_get_null(napi_env env, napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [out] result: 表示 JavaScript null 对象的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回 null 对象。

napi_get_undefined#

napi_status napi_get_undefined(napi_env env, napi_value* result) copy

• [in] env：API 在其下调用的环境。
• [out] result: 表示 JavaScript Undefined 值的 napi_value。

如果 API 成功，则返回 napi_ok。

此 API 返回 Undefined 对象。

napi_property_attributes#

typedef enum {
  napi_default = 0,
  napi_writable = 1 << 0,
  napi_enumerable = 1 << 1,
  napi_configurable = 1 << 2,

  // Used with napi_define_class to distinguish static properties
  // from instance properties. Ignored by napi_define_properties.
  napi_static = 1 << 10,

  // Default for class methods.
  napi_default_method = napi_writable | napi_configurable,

  // Default for object properties, like in JS obj[prop].
  napi_default_jsproperty = napi_writable |
                          napi_enumerable |
                          napi_configurable,
} napi_property_attributes; copy

napi_property_attributes 是用于控制在 JavaScript 对象上设置的属性的行为的标志。 除了 napi_static 之外，它们对应于 第 6.1.7.1 节的 ECMAScript 语言规范中列出的属性。 它们可以是以下一个或多个位标志

• napi_default：未在属性上设置显式属性。 默认情况下，属性是只读的、不可枚举的且不可配置的。
• napi_writable：属性是可写的。
• napi_enumerable：属性是可枚举的。
• napi_configurable：属性是可配置的，如 第 6.1.7.1 节的 ECMAScript 语言规范中所定义。
• napi_static：该属性将被定义为类上的静态属性，而不是实例属性，后者是默认属性。 这仅由 napi_define_class 使用。 napi_define_properties 忽略它。
• napi_default_method：与 JS 类中的方法类似，该属性是可配置和可写的，但不可枚举。
• napi_default_jsproperty：与通过 JavaScript 中的赋值设置的属性类似，该属性是可写的、可枚举的和可配置的。

napi_property_descriptor#

typedef struct {
  // One of utf8name or name should be NULL.
  const char* utf8name;
  napi_value name;

  napi_callback method;
  napi_callback getter;
  napi_callback setter;
  napi_value value;

  napi_property_attributes attributes;
  void* data;
} napi_property_descriptor; copy

• utf8name：可选字符串，描述属性的键，编码为 UTF8。 必须为属性提供 utf8name 或 name 之一。
• name：可选的 napi_value，指向要用作属性键的 JavaScript 字符串或符号。 必须为属性提供 utf8name 或 name 之一。
• value：如果属性是数据属性，则通过属性的 get 访问检索的值。 如果传入此值，请将 getter、setter、method 和 data 设置为 NULL（因为不会使用这些成员）。
• getter：当执行属性的 get 访问时要调用的函数。 如果传入此值，请将 value 和 method 设置为 NULL（因为不会使用这些成员）。 当从 JavaScript 代码访问属性时（或者如果使用 Node-API 调用对属性执行 get 操作），运行时会隐式调用给定的函数。 napi_callback 提供了更多详细信息。
• setter：当执行属性的 set 访问时要调用的函数。 如果传入此值，请将 value 和 method 设置为 NULL（因为不会使用这些成员）。 当从 JavaScript 代码设置属性时（或者如果使用 Node-API 调用对属性执行 set 操作），运行时会隐式调用给定的函数。 napi_callback 提供了更多详细信息。
• method：设置此值以使属性描述符对象的 value 属性成为由 method 表示的 JavaScript 函数。 如果传入此值，请将 value、getter 和 setter 设置为 NULL（因为不会使用这些成员）。 napi_callback 提供了更多详细信息。
• attributes：与特定属性关联的属性。 请参见 napi_property_attributes。
• data：如果调用此函数，则传入 method、getter 和 setter 的回调数据。

napi_get_property_names#

napi_status napi_get_property_names(napi_env env,
                                    napi_value object,
                                    napi_value* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：从中检索属性的对象。
• [out] result：表示 JavaScript 值数组的 napi_value，这些值表示对象的属性名称。 该 API 可以用于使用 napi_get_array_length 和 napi_get_element 迭代 result。

如果 API 成功，则返回 napi_ok。

此 API 将 object 的可枚举属性的名称作为字符串数组返回。 键为符号的 object 的属性将不包括在内。

napi_get_all_property_names#

napi_get_all_property_names(napi_env env,
                            napi_value object,
                            napi_key_collection_mode key_mode,
                            napi_key_filter key_filter,
                            napi_key_conversion key_conversion,
                            napi_value* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：从中检索属性的对象。
• [in] key_mode：是否也要检索原型属性。
• [in] key_filter：要检索哪些属性（可枚举/可读/可写）。
• [in] key_conversion：是否将编号的属性键转换为字符串。
• [out] result：表示 JavaScript 值数组的 napi_value，这些值表示对象的属性名称。 可以使用 napi_get_array_length 和 napi_get_element 迭代 result。

如果 API 成功，则返回 napi_ok。

此 API 返回包含此对象的可用属性名称的数组。

napi_set_property#

napi_status napi_set_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value value); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要在其上设置属性的对象。
• [in] key：要设置的属性的名称。
• [in] value：属性值。

如果 API 成功，则返回 napi_ok。

此 API 在传入的 Object 上设置一个属性。

napi_get_property#

napi_status napi_get_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              napi_value* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：从中检索属性的对象。
• [in] key：要检索的属性的名称。
• [out] result：属性的值。

如果 API 成功，则返回 napi_ok。

此 API 从传入的 Object 中获取请求的属性。

napi_has_property#

napi_status napi_has_property(napi_env env,
                              napi_value object,
                              napi_value key,
                              bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] key：要检查其存在的属性的名称。
• [out] result：属性是否存在于对象上。

如果 API 成功，则返回 napi_ok。

此 API 检查传入的 Object 是否具有命名的属性。

napi_delete_property#

napi_status napi_delete_property(napi_env env,
                                 napi_value object,
                                 napi_value key,
                                 bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] key：要删除的属性的名称。
• [out] result：属性删除是否成功。 可以选择通过传递 NULL 来忽略 result。

如果 API 成功，则返回 napi_ok。

此 API 尝试从 object 中删除 key 自身属性。

napi_has_own_property#

napi_status napi_has_own_property(napi_env env,
                                  napi_value object,
                                  napi_value key,
                                  bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] key：要检查其存在的自身属性的名称。
• [out] result：自身属性是否存在于对象上。

如果 API 成功，则返回 napi_ok。

此 API 检查传入的 Object 是否具有指定的自有属性。 key 必须是 string 或 symbol，否则会抛出错误。 Node-API 不会在数据类型之间执行任何转换。

napi_set_named_property#

napi_status napi_set_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value value); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要在其上设置属性的对象。
• [in] utf8Name：要设置的属性的名称。
• [in] value：属性值。

如果 API 成功，则返回 napi_ok。

此方法等效于使用从作为 utf8Name 传入的字符串创建的 napi_value 调用 napi_set_property。

napi_get_named_property#

napi_status napi_get_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    napi_value* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：从中检索属性的对象。
• [in] utf8Name：要获取的属性的名称。
• [out] result：属性的值。

如果 API 成功，则返回 napi_ok。

此方法等效于使用从作为 utf8Name 传入的字符串创建的 napi_value 调用 napi_get_property。

napi_has_named_property#

napi_status napi_has_named_property(napi_env env,
                                    napi_value object,
                                    const char* utf8Name,
                                    bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] utf8Name：要检查其存在的属性的名称。
• [out] result：属性是否存在于对象上。

如果 API 成功，则返回 napi_ok。

此方法等效于使用从作为 utf8Name 传入的字符串创建的 napi_value 调用 napi_has_property。

napi_set_element#

napi_status napi_set_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value value); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要设置属性的对象。
• [in] index：要设置的属性的索引。
• [in] value：属性值。

如果 API 成功，则返回 napi_ok。

此 API 在传入的 Object 上设置一个元素。

napi_get_element#

napi_status napi_get_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             napi_value* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：从中检索属性的对象。
• [in] index：要获取的属性的索引。
• [out] result：属性的值。

如果 API 成功，则返回 napi_ok。

此 API 获取请求索引处的元素。

napi_has_element#

napi_status napi_has_element(napi_env env,
                             napi_value object,
                             uint32_t index,
                             bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] index：要检查其存在的属性的索引。
• [out] result：属性是否存在于对象上。

如果 API 成功，则返回 napi_ok。

此 API 返回传入的 Object 是否在请求的索引处具有元素。

napi_delete_element#

napi_status napi_delete_element(napi_env env,
                                napi_value object,
                                uint32_t index,
                                bool* result); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要查询的对象。
• [in] index：要删除的属性的索引。
• [out] result：元素删除是否成功。 可以通过传递 NULL 来选择性地忽略 result。

如果 API 成功，则返回 napi_ok。

此 API 尝试从 object 中删除指定的 index。

napi_define_properties#

napi_status napi_define_properties(napi_env env,
                                   napi_value object,
                                   size_t property_count,
                                   const napi_property_descriptor* properties); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：从中检索属性的对象。
• [in] property_count：properties 数组中的元素数。
• [in] properties：属性描述符数组。

如果 API 成功，则返回 napi_ok。

此方法允许在给定对象上高效地定义多个属性。 这些属性是使用属性描述符定义的（请参阅 napi_property_descriptor）。 给定这样一个属性描述符数组，此 API 将根据 DefineOwnProperty() （在 ECMA-262 规范的 第 9.1.6 节中描述）一次设置一个对象上的属性。

napi_object_freeze#

napi_status napi_object_freeze(napi_env env,
                               napi_value object); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要冻结的对象。

如果 API 成功，则返回 napi_ok。

此方法冻结给定的对象。 这可以防止向其添加新属性，防止删除现有属性，防止更改现有属性的可枚举性、可配置性或可写性，并防止更改现有属性的值。 它还可以防止对象的原型被更改。 这在 ECMA-262 规范的 第 19.1.2.6 节中进行了描述。

napi_object_seal#

napi_status napi_object_seal(napi_env env,
                             napi_value object); copy

• [in] env: 调用 Node-API 的环境。
• [in] object：要密封的对象。

如果 API 成功，则返回 napi_ok。

此方法密封给定的对象。 这可以防止添加新属性，并将所有现有属性标记为不可配置。 这在 ECMA-262 规范的 第 19.1.2.20 节中进行了描述。

node_api_post_finalizer#

napi_status node_api_post_finalizer(node_api_basic_env env,
                                    napi_finalize finalize_cb,
                                    void* finalize_data,
                                    void* finalize_hint); copy

• [in] env：API 在其下调用的环境。
• [in] finalize_cb: 本地回调函数，当 JavaScript 对象被垃圾回收时，将用于释放本地数据。napi_finalize 提供了更多细节。
• [in] finalize_data：要传递给 finalize_cb 的可选数据。
• [in] finalize_hint：传递给 finalize 回调的可选上下文提示。

如果 API 成功，则返回 napi_ok。

调度一个 napi_finalize 回调，使其在事件循环中异步调用。

通常，finalizer 在 GC（垃圾回收器）收集对象时被调用。此时，调用任何可能导致 GC 状态更改的 Node-API 将被禁用，并导致 Node.js 崩溃。

node_api_post_finalizer 通过允许插件将此类 Node-API 的调用推迟到 GC finalization 之外的时间点来帮助解决此限制。