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] env: The environment that the API is invoked under.

• [in] js_object：将成为原生对象封装器的 JavaScript 对象。

  ¥[in] js_object: The JavaScript object that will be the wrapper for the native object.

• [in] native_object：将封装在 JavaScript 对象中的原生实例。

  ¥[in] native_object: The native instance that will be wrapped in the JavaScript object.

• [in] finalize_cb：可选的原生回调，可用于在 JavaScript 对象准备好进行垃圾回收时释放原生实例。napi_finalize 提供了更多详细信息。

  ¥[in] finalize_cb: Optional native callback that can be used to free the native instance when the JavaScript object is ready for garbage-collection. napi_finalize provides more details.

• [in] finalize_hint：传递给完成回调的可选上下文提示。

  ¥[in] finalize_hint: Optional contextual hint that is passed to the finalize callback.

• [out] result：对封装对象的可选引用。

  ¥[out] result: Optional reference to the wrapped object.

如果 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.)

通常在封装类实例时，应该提供一个终结回调，它只是删除作为终结回调的 data 参数接收的原生实例。

¥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.

警告：可选的返回引用（如果获得）应仅通过 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.