使用 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
表示。这可以是代表string
、number
或symbol
的napi_value
。¥JavaScript value: these are represented in Node-API by
napi_value
. This can be anapi_value
representing astring
,number
, orsymbol
.
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;