napi_create_function


napi_status napi_create_function(napi_env env,
                                 const char* utf8name,
                                 size_t length,
                                 napi_callback cb,
                                 void* data,
                                 napi_value* result); 
  • [in] env:调用 API 的环境。

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

  • [in] utf8Name:编码为 UTF8 的函数的可选名称。这在 JavaScript 中是可见的,作为新函数对象的 name 属性。

    ¥[in] utf8Name: Optional name of the function encoded as UTF8. This is visible within JavaScript as the new function object's name property.

  • [in] lengthutf8name 的长度(以字节为单位)或 NAPI_AUTO_LENGTH(如果以 null 结尾)。

    ¥[in] length: The length of the utf8name in bytes, or NAPI_AUTO_LENGTH if it is null-terminated.

  • [in] cb:调用此函数对象时应调用的原生函数。napi_callback 提供了更多详细信息。

    ¥[in] cb: The native function which should be called when this function object is invoked. napi_callback provides more details.

  • [in] data:用户提供的数据上下文。这将在稍后调用时传回函数。

    ¥[in] data: User-provided data context. This will be passed back into the function when invoked later.

  • [out] resultnapi_value 表示新创建函数的 JavaScript 函数对象。

    ¥[out] result: napi_value representing the JavaScript function object for the newly created function.

如果 API 成功,则返回 napi_ok

¥Returns napi_ok if the API succeeded.

此 API 允许插件作者以原生代码创建函数对象。这是允许从 JavaScript 调用加载项的原生代码的主要机制。

¥This API allows an add-on author to create a function object in native code. This is the primary mechanism to allow calling into the add-on's native code from JavaScript.

在此调用之后,新创建的函数不会自动从脚本中可见。相反,必须在 JavaScript 可见的任何对象上显式设置属性,以便可以从脚本访问该函数。

¥The newly created function is not automatically visible from script after this call. Instead, a property must be explicitly set on any object that is visible to JavaScript, in order for the function to be accessible from script.

为了将函数公开为附加模块导出的一部分,请在导出对象上设置新创建的函数。示例模块可能如下所示:

¥In order to expose a function as part of the add-on's module exports, set the newly created function on the exports object. A sample module might look as follows:

napi_value SayHello(napi_env env, napi_callback_info info) {
  printf("Hello\n");
  return NULL;
}

napi_value Init(napi_env env, napi_value exports) {
  napi_status status;

  napi_value fn;
  status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);
  if (status != napi_ok) return NULL;

  status = napi_set_named_property(env, exports, "sayHello", fn);
  if (status != napi_ok) return NULL;

  return exports;
}

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init) 

鉴于以上代码,可以从 JavaScript 中使用附加组件,如下所示:

¥Given the above code, the add-on can be used from JavaScript as follows:

const myaddon = require('./addon');
myaddon.sayHello(); 

传递给 require() 的字符串是 binding.gyp 中负责创建 .node 文件的目标的名称。

¥The string passed to require() is the name of the target in binding.gyp responsible for creating the .node file.

通过 data 参数传递给此 API 的任何非 NULL 数据都可以与生成的 JavaScript 函数(在 result 参数中返回)相关联,并在通过传递 JavaScript 函数和数据对函数进行垃圾回收时释放 到 napi_add_finalizer

¥Any non-NULL data which is passed to this API via the data parameter can be associated with the resulting JavaScript function (which is returned in the result parameter) and freed whenever the function is garbage-collected by passing both the JavaScript function and the data to napi_add_finalizer.

JavaScript Function 在 ECMAScript 语言规范的 第 19.2 节 中描述。

¥JavaScript Functions are described in Section 19.2 of the ECMAScript Language Specification.