napi_create_external_arraybuffer

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

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

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

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

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

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

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

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

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

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

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

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

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

如果 API 成功，则返回 napi_ok。

¥Returns napi_ok if the API succeeded.

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

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

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

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

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

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

API 添加了一个 napi_finalize 回调，当刚刚创建的 JavaScript 对象准备好进行垃圾回收时将调用该回调。它与 napi_wrap() 相似，不同之处在于：

¥The API adds a napi_finalize callback which will be called when the JavaScript object just created is ready for garbage collection. It is similar to napi_wrap() except that:

• 以后无法使用 napi_unwrap() 检索原生数据，

  ¥the native data cannot be retrieved later using napi_unwrap(),

• 以后也不能使用 napi_remove_wrap() 将其删除，并且

  ¥nor can it be removed later using napi_remove_wrap(), and

• API 创建的对象可以与 napi_wrap() 一起使用。

  ¥the object created by the API can be used with napi_wrap().

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

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