使用 JavaScript 属性

【Working with JavaScript properties】

Node-API 提供了一组用于获取和设置 JavaScript 对象属性的 API。

【Node-API exposes a set of APIs to get and set properties on JavaScript objects.】

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 编码字符串
• 整数索引：由 uint32_t 表示的索引值
• JavaScript 值：在 Node-API 中，这些由 napi_value 表示。这可以是表示 string、number 或 symbol 的 napi_value。

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; 拷贝