使用 JavaScript 属性


¥Working with JavaScript properties

Node-API 公开了一组 API 来获取和设置 JavaScript 对象的属性。其中一些类型记录在 ECMAScript 语言规范第 7 节 下。

¥Node-API exposes a set of APIs to get and set properties on JavaScript objects. Some of these types are documented under Section 7 of the ECMAScript Language Specification.

JavaScript 中的属性表示为键和值的元组。从根本上说,Node-API 中的所有属性键都可以用以下形式之一表示:

¥Properties in JavaScript are represented as a tuple of a key and a value. Fundamentally, all property keys in Node-API can be represented in one of the following forms:

  • 命名:一个简单的 UTF8 编码字符串

    ¥Named: a simple UTF8-encoded string

  • 整数索引:由 uint32_t 表示的索引值

    ¥Integer-Indexed: an index value represented by uint32_t

  • JavaScript 值:这些在 Node-API 中由 napi_value 表示。这可以是代表 stringnumbersymbolnapi_value

    ¥JavaScript value: these are represented in Node-API by napi_value. This can be a napi_value representing a string, number, or symbol.

Node-API 值由类型 napi_value 表示。任何需要 JavaScript 值的 Node-API 调用都采用 napi_value。但是,调用者有责任确保所讨论的 napi_value 是 API 期望的 JavaScript 类型。

¥Node-API values are represented by the type napi_value. Any Node-API call that requires a JavaScript value takes in a napi_value. However, it's the caller's responsibility to make sure that the napi_value in question is of the JavaScript type expected by the API.

本节中记录的 API 提供了一个简单的接口来获取和设置 napi_value 表示的任意 JavaScript 对象的属性。

¥The APIs documented in this section provide a simple interface to get and set properties on arbitrary JavaScript objects represented by napi_value.

例如,考虑以下 JavaScript 代码片段:

¥For instance, consider the following JavaScript code snippet:

const obj = {};
obj.myProp = 123; 

可以通过以下代码段使用 Node-API 值来完成等效操作:

¥The equivalent can be done using Node-API values with the following snippet:

napi_status status = napi_generic_failure;

// const obj = {}
napi_value obj, value;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;

// Create a napi_value for 123
status = napi_create_int32(env, 123, &value);
if (status != napi_ok) return status;

// obj.myProp = 123
status = napi_set_named_property(env, obj, "myProp", value);
if (status != napi_ok) return status; 

可以以类似的方式设置索引属性。考虑以下 JavaScript 片段:

¥Indexed properties can be set in a similar manner. Consider the following JavaScript snippet:

const arr = [];
arr[123] = 'hello'; 

可以通过以下代码段使用 Node-API 值来完成等效操作:

¥The equivalent can be done using Node-API values with the following snippet:

napi_status status = napi_generic_failure;

// const arr = [];
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;

// Create a napi_value for 'hello'
status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &value);
if (status != napi_ok) return status;

// arr[123] = 'hello';
status = napi_set_element(env, arr, 123, value);
if (status != napi_ok) return status; 

可以使用本节中描述的 API 检索属性。考虑以下 JavaScript 片段:

¥Properties can be retrieved using the APIs described in this section. Consider the following JavaScript snippet:

const arr = [];
const value = arr[123]; 

以下是 Node-API 对应物的大致等价物:

¥The following is the approximate equivalent of the Node-API counterpart:

napi_status status = napi_generic_failure;

// const arr = []
napi_value arr, value;
status = napi_create_array(env, &arr);
if (status != napi_ok) return status;

// const value = arr[123]
status = napi_get_element(env, arr, 123, &value);
if (status != napi_ok) return status; 

最后,出于性能原因,还可以在一个对象上定义多个属性。考虑以下 JavaScript:

¥Finally, multiple properties can also be defined on an object for performance reasons. Consider the following JavaScript:

const obj = {};
Object.defineProperties(obj, {
  'foo': { value: 123, writable: true, configurable: true, enumerable: true },
  'bar': { value: 456, writable: true, configurable: true, enumerable: true },
}); 

以下是 Node-API 对应物的大致等价物:

¥The following is the approximate equivalent of the Node-API counterpart:

napi_status status = napi_status_generic_failure;

// const obj = {};
napi_value obj;
status = napi_create_object(env, &obj);
if (status != napi_ok) return status;

// Create napi_values for 123 and 456
napi_value fooValue, barValue;
status = napi_create_int32(env, 123, &fooValue);
if (status != napi_ok) return status;
status = napi_create_int32(env, 456, &barValue);
if (status != napi_ok) return status;

// Set the properties
napi_property_descriptor descriptors[] = {
  { "foo", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },
  { "bar", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }
}
status = napi_define_properties(env,
                                obj,
                                sizeof(descriptors) / sizeof(descriptors[0]),
                                descriptors);
if (status != napi_ok) return status;