napi_wrap

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。

【Returns napi_ok if the API succeeded.】

将本地实例封装到 JavaScript 对象中。可以使用 napi_unwrap() 在以后检索该本地实例。

【Wraps a native instance in a JavaScript object. The native instance can be retrieved later using napi_unwrap().】

当 JavaScript 代码调用使用 napi_define_class() 定义的类的构造函数时，会调用构造函数的 napi_callback。 在构造原生类的实例之后，回调函数必须调用 napi_wrap()，将新构造的实例封装到已经创建好的 JavaScript 对象中，该对象就是构造函数回调的 this 参数。（该 this 对象是从构造函数的 prototype 创建的，因此它已经定义了所有实例属性和方法。）

【When JavaScript code invokes a constructor for a class that was defined using napi_define_class(), the napi_callback for the constructor is invoked. After constructing an instance of the native class, the callback must then call napi_wrap() to wrap the newly constructed instance in the already-created JavaScript object that is the this argument to the constructor callback. (That this object was created from the constructor function's prototype, so it already has definitions of all the instance properties and methods.)】

通常在封装一个类实例时，应该提供一个 finalize 回调，该回调只需删除作为 data 参数传递给 finalize 回调的原生实例。

【Typically when wrapping a class instance, a finalize callback should be provided that simply deletes the native instance that is received as the data argument to the finalize callback.】

可选返回引用最初是一个弱引用，这意味着它的引用计数为0。通常在异步操作中，如果需要保持实例有效，这个引用计数会被临时增加。

【The optional returned reference is initially a weak reference, meaning it has a reference count of 0. Typically this reference count would be incremented temporarily during async operations that require the instance to remain valid.】

⚠️注意：可选返回的引用（如果获得）应仅在 finalize 回调调用时通过 napi_delete_reference 删除。如果在此之前删除，可能永远不会调用 finalize 回调。因此，在获取引用时，还需要一个 finalize 回调，以确保引用能够正确释放。

【Caution: The optional returned reference (if obtained) should be deleted via napi_delete_reference ONLY in response to the finalize callback invocation. If it is deleted before then, then the finalize callback may never be invoked. Therefore, when obtaining a reference a finalize callback is also required in order to enable correct disposal of the reference.】

终结器回调可能会被延迟，这会留下一个窗口期，在此期间对象已经被垃圾回收（弱引用无效），但终结器尚未被调用。在对 napi_wrap() 返回的弱引用使用 napi_get_reference_value() 时，你仍然应该处理空结果。

【Finalizer callbacks may be deferred, leaving a window where the object has been garbage collected (and the weak reference is invalid) but the finalizer hasn't been called yet. When using napi_get_reference_value() on weak references returned by napi_wrap(), you should still handle an empty result.】

在同一个对象上第二次调用 napi_wrap() 会返回错误。要将另一个本地实例与该对象关联，请先使用 napi_remove_wrap()。

【Calling napi_wrap() a second time on an object will return an error. To associate another native instance with the object, use napi_remove_wrap() first.】