• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 使用JSVM-API接口进行array相关开发
2<!--Kit: NDK Development-->
3<!--Subsystem: arkcompiler-->
4<!--Owner: @yuanxiaogou; @string_sz-->
5<!--Designer: @knightaoko-->
6<!--Tester: @test_lzz-->
7<!--Adviser: @fang-jinxu-->
8
9## 简介
10
11使用JSVM-API接口进行数组（array）相关开发时，在JSVM模块中可以调用相关接口直接操作和处理JavaScript中的数组。
12
13## 基本概念
14
15使用 JSVM-API 接口进行数组（array）相关开发时，涉及的基本概念主要包括数组的创建、访问、修改、遍历以及与数组相关的操作。这些概念对于理解在 JSVM 模块中与 JavaScript 数组交互非常重要。以下是一些关键概念：
16
17- **数组的创建**：若在 JSVM 模块中需要创建新的 JavaScript 数组时，可以使用提供的 OH_JSVM_CreateArray 接口创建数组，将传递给 JavaScript 层。
18- **数组相关操作**：在 JSVM 模块中通过对应的接口获取 JavaScript 数组的长度、检索指定索引处的元素、设置指定索引的元素值，从而实现 JSVM 模块与 JavaScript 数组的交互。
19- **TypedArray**：JavaScript 中的 TypedArray 是一种类数组数据视图，用于描述二进制数据。它可以视为指定元素类型的类数组数据视图，TypedArray 没有直接构造器，但是可以通过其子类构造器构造创建。子类包括：Int8Array、Uint8Array、Uint8ClampedArray、Int16Array、Int32Array等。
20- **ArrayBuffer**：ArrayBuffer 是固定长度的二进制数据缓冲区。
21- **DataView**：DataView 是 JavaScript 中的一种视图，是可以从 ArrayBuffer 对象中读写多种数值类型的底层接口。
22
23
24## 接口说明
25
26| 接口                         | 功能说明                                   |
27| ---------------------------- | ------------------------------------------ |
28|OH_JSVM_CreateArray | 创建一个新的 JavaScript 数组对象 |
29|OH_JSVM_CreateArrayWithLength | 创建一个指定长度的 JavaScript 数组对象 |
30|OH_JSVM_CreateTypedarray | 在现有的ArrayBuffer上创建JavaScript TypedArray对象，TypedArray对象提供类似类数组的视图，每个元素具有相同的二进制标量数据类型。注意(length * size_of_element) + byte_offset 不得超过传入数组的大小（以字节为单位），否则会引发RangeError异常。|
31|OH_JSVM_CreateDataview | 在现有的 ArrayBuffer 上创建一个 JavaScript DataView 对象，DataView 对象在底层数据缓冲区上提供类似数组的视图，该 ArrayBuffer 允许有不同大小和类型的元素。要求 byte_length + byte_offset 小于或等于传入数组的字节大小，否则会引发 RangeError 异常。|
32|OH_JSVM_GetArrayLength | 返回 Array 对象的长度 |
33|OH_JSVM_GetTypedarrayInfo | 获取 TypedArray（类型化数组）对象的信息 |
34|OH_JSVM_GetDataviewInfo | 获取 DataView 对象的信息 |
35|OH_JSVM_IsArray | 判断一个 JavaScript 对象是否为 Array 类型对象|
36|OH_JSVM_SetElement | 在给定对象的指定索引处设置元素 |
37|OH_JSVM_GetElement | 获取给定对象指定索引处的元素 |
38|OH_JSVM_HasElement | 若给定对象的指定索引处拥有属性，获取该元素 |
39|OH_JSVM_DeleteElement | 尝试删除给定对象的指定索引处的元素 |
40|OH_JSVM_IsDataview | 判断一个 JavaScript 对象是否为 DataView 类型对象 |
41|OH_JSVM_IsTypedarray | 判断一个 JavaScript 对象是否为 TypedArray 类型对象 |
42
43## 使用示例
44
45JSVM-API 接口开发流程参考[使用 JSVM-API 实现 JS 与 C/C++ 语言交互开发流程](use-jsvm-process.md)，本文仅对接口对应 C++ 相关代码进行展示。
46
47### OH_JSVM_CreateArray
48
49创建一个新的 JavaScript 数组对象。
50
51cpp 部分代码：
52
53```cpp
54// hello.cpp
55#include "napi/native_api.h"
56#include "ark_runtime/jsvm.h"
57#include <hilog/log.h>
58// CreateArray注册回调
59static int DIFF_VALUE_FIVE = 5;
60// OH_JSVM_CreateArray的样例方法
61static JSVM_Value CreateArray(JSVM_Env env, JSVM_CallbackInfo info)
62{
63    // 创建一个空数组
64    JSVM_Value array = nullptr;
65    JSVM_Status status = OH_JSVM_CreateArray(env, &array);
66    if (status != JSVM_OK) {
67        OH_LOG_ERROR(LOG_APP, "JSVM CreateArray fail");
68        return nullptr;
69    } else {
70        OH_LOG_INFO(LOG_APP, "JSVM CreateArray success");
71    }
72    // 对创建的数组进行赋值
73    for (int i = 0; i < DIFF_VALUE_FIVE; i++) {
74        JSVM_Value element;
75        JSVM_CALL(OH_JSVM_CreateInt32(env, i, &element));
76        JSVM_CALL(OH_JSVM_SetElement(env, array, i, element));
77    }
78    return array;
79}
80static JSVM_CallbackStruct param[] = {
81    {.data = nullptr, .callback = CreateArray},
82};
83static JSVM_CallbackStruct *method = param;
84// CreateArray方法别名，供JS调用
85static JSVM_PropertyDescriptor descriptor[] = {
86    {"createArray", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
87};
88// 样例测试js
89const char *srcCallNative = R"JS(
90  function testCreateArray() {
91    return createArray();
92  }
93  testCreateArray();
94)JS";
95```
96<!-- @[oh_jsvm_create_array](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/createarray/src/main/cpp/hello.cpp) -->
97
98预计的输出结果：
99```
100JSVM CreateArray success
101```
102### OH_JSVM_CreateArrayWithLength
103
104创建一个指定长度的 JavaScript 数组对象。
105
106cpp 部分代码：
107
108```cpp
109// hello.cpp
110#include "napi/native_api.h"
111#include "ark_runtime/jsvm.h"
112#include <hilog/log.h>
113// OH_JSVM_CreateArrayWithLength的样例方法
114static JSVM_Value CreateArrayWithLength(JSVM_Env env, JSVM_CallbackInfo info)
115{
116    size_t argc = 1;
117    JSVM_Value argv[1] = {nullptr};
118    JSVM_Value result = nullptr;
119    // 解析传递的参数OH_JSVM_GetCbInfo
120    OH_JSVM_GetCbInfo(env, info, &argc, argv, nullptr, nullptr);
121    // 获取传递的数组长度
122    int32_t length = 0;
123    OH_JSVM_GetValueInt32(env, argv[0], &length);
124    // 使用OH_JSVM_CreateArrayWithLength创建传递固定长度的数组
125    JSVM_Status status = OH_JSVM_CreateArrayWithLength(env, length, &result);
126    if (status == JSVM_OK) {
127        // 给创建的数组设置值
128        for (int32_t i = 0; i < length; i++) {
129            JSVM_Value value;
130            JSVM_CALL(OH_JSVM_CreateInt32(env, i, &value));
131            JSVM_CALL(OH_JSVM_SetElement(env, result, i, value));
132        }
133        OH_LOG_INFO(LOG_APP, "JSVM CreateArrayWithLength success");
134    } else {
135        OH_LOG_ERROR(LOG_APP, "JSVM CreateArrayWithLength fail");
136    }
137    return result;
138}
139// CreateArrayWithLength注册回调
140static JSVM_CallbackStruct param[] = {
141    {.data = nullptr, .callback = CreateArrayWithLength},
142};
143static JSVM_CallbackStruct *method = param;
144// CreateArrayWithLength方法别名，供JS调用
145static JSVM_PropertyDescriptor descriptor[] = {
146    {"createArrayWithLength", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
147};
148// 样例测试js
149const char *srcCallNative = R"JS(
150let num = 7;
151function testCreateArrayWithLength(num){
152    return createArrayWithLength(num);
153}
154testCreateArrayWithLength(num);
155)JS";
156```
157<!-- @[oh_jsvm_create_array_with_length](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/createarraywithlength/src/main/cpp/hello.cpp) -->
158
159预计的输出结果：
160```
161JSVM CreateArrayWithLength success
162```
163### OH_JSVM_CreateTypedarray
164
165在现有的 ArrayBuffer上 创建一个 JavaScript TypedArray 对象,TypedArray 对象在底层数据缓冲区上提供类似数组的视图，其中每个元素都具有相同的底层二进制标量数据类型。
166
167cpp 部分代码：
168
169```cpp
170// hello.cpp
171#include "napi/native_api.h"
172#include "ark_runtime/jsvm.h"
173#include <hilog/log.h>
174// OH_JSVM_CreateTypedarray的样例方法
175static int DIFF_VALUE_THREE = 3;
176static JSVM_Value CreateTypedArray(JSVM_Env env, JSVM_CallbackInfo info)
177{
178    size_t argc = 1;
179    JSVM_Value args[1] = {nullptr};
180    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
181    int32_t typeNum = 0;
182    OH_JSVM_GetValueInt32(env, args[0], &typeNum);
183    JSVM_TypedarrayType arrayType;
184    // 用于存储每个元素的大小
185    size_t elementSize = 0;
186    // 转换为JSVM_TypedarrayType类型
187    arrayType = static_cast<JSVM_TypedarrayType>(typeNum);
188    switch (typeNum) {
189        case JSVM_INT8_ARRAY:
190        case JSVM_UINT8_ARRAY:
191        case JSVM_UINT8_CLAMPED_ARRAY:
192            elementSize = sizeof(int8_t);
193            break;
194        case JSVM_INT16_ARRAY:
195        case JSVM_UINT16_ARRAY:
196            elementSize = sizeof(int16_t);
197            break;
198        case JSVM_INT32_ARRAY:
199        case JSVM_UINT32_ARRAY:
200            elementSize = sizeof(int32_t);
201            break;
202        case JSVM_FLOAT32_ARRAY:
203            elementSize = sizeof(float);
204            break;
205        case JSVM_FLOAT64_ARRAY:
206            elementSize = sizeof(double);
207            break;
208        case JSVM_BIGINT64_ARRAY:
209        case JSVM_BIGUINT64_ARRAY:
210            elementSize = sizeof(int64_t);
211            break;
212        default:
213            // 默认创建JSVM_INT8_ARRAY类型
214            arrayType = JSVM_INT8_ARRAY;
215            elementSize = sizeof(int8_t);
216            break;
217    }
218    size_t length = DIFF_VALUE_THREE;
219    JSVM_Value arrayBuffer = nullptr;
220    JSVM_Value typedArray = nullptr;
221    void *data;
222    // 创建一个ArrayBuffer
223    OH_JSVM_CreateArraybuffer(env, length * elementSize, (void **)&data, &arrayBuffer);
224    // 根据给定类型创建TypedArray
225    JSVM_Status status = OH_JSVM_CreateTypedarray(env, arrayType, length, arrayBuffer, 0, &typedArray);
226    if (status != JSVM_OK) {
227        OH_LOG_ERROR(LOG_APP, "JSVM CreateTypedArray fail");
228    } else {
229        OH_LOG_INFO(LOG_APP, "JSVM CreateTypedArray success");
230    }
231    return typedArray;
232}
233// CreateTypedArray注册回调
234static JSVM_CallbackStruct param[] = {
235    {.data = nullptr, .callback = CreateTypedArray},
236};
237static JSVM_CallbackStruct *method = param;
238// CreateTypedArray方法别名，供JS调用
239static JSVM_PropertyDescriptor descriptor[] = {
240    {"createTypedArray", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
241};
242// 样例测试js
243const char *srcCallNative = R"JS(
244const type = {
245    INT8_ARRAY: 0,
246    UINT8_ARRAY: 1,
247    UINT8_CLAMPED_ARRAY: 2,
248    INT16_ARRAY: 3,
249    UINT16_ARRAY: 4,
250    INT32_ARRAY: 5,
251    UINT32_ARRAY: 6,
252    FLOAT32_ARRAY: 7,
253    FLOAT64_ARRAY: 8,
254    BIGINT64_ARRAY: 9,
255    BIGUINT64_ARRAY: 10
256};
257createTypedArray(type.INT8_ARRAY);
258createTypedArray(type.INT32_ARRAY);
259)JS";
260```
261<!-- @[oh_jsvm_create_typedarray](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/createtypedarray/src/main/cpp/hello.cpp) -->
262
263预计的输出结果：
264```
265JSVM CreateTypedArray success
266JSVM CreateTypedArray success
267```
268### OH_JSVM_CreateDataview
269
270在现有的 ArrayBuffer 上创建一个 JavaScript DataView 对象，DataView 对象在底层数据缓冲区上提供类似数组的视图。
271
272cpp 部分代码：
273
274```cpp
275static int DIFF_VALUE_FOUR = 4;
276static int DIFF_VALUE_TWELVE = 12;
277// OH_JSVM_CreateDataview的样例方法
278static JSVM_Value CreateDataView(JSVM_Env env, JSVM_CallbackInfo info)
279{
280    // 获取js侧传入的两个参数
281    size_t argc = 2;
282    JSVM_Value args[2] = {nullptr};
283    JSVM_Value arrayBuffer = nullptr;
284    JSVM_Value result = nullptr;
285    // DataView的字节长度
286    size_t byteLength = DIFF_VALUE_TWELVE;
287    // 字节偏移量
288    size_t byteOffset = DIFF_VALUE_FOUR;
289    // 获取回调函数的参数信息
290    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
291    // 将参数转换为对象类型
292    OH_JSVM_CoerceToObject(env, args[0], &arrayBuffer);
293    // 创建一个数据视图对象，并指定字节长度和字节偏移量
294    JSVM_Status status = OH_JSVM_CreateDataview(env, byteLength, arrayBuffer, byteOffset, &result);
295    // 获取DataView的指针和长度信息
296    uint8_t *data = nullptr;
297    // 为DataView赋值
298    int32_t infoType = 0;
299    OH_JSVM_GetValueInt32(env, args[1], &infoType);
300    size_t returnLength = 0;
301    JSVM_Value returnArrayBuffer = nullptr;
302    size_t returnOffset = 0;
303    enum InfoType { BYTE_LENGTH, ARRAY_BUFFER, BYTE_OFFSET };
304    // 获取dataview信息
305    OH_JSVM_GetDataviewInfo(env, result, &returnLength, (void **)&data, &returnArrayBuffer, &returnOffset);
306    JSVM_Value returnResult = nullptr;
307    switch (infoType) {
308        case BYTE_LENGTH:
309            JSVM_Value len;
310            JSVM_CALL(OH_JSVM_CreateInt32(env, returnLength, &len));
311            returnResult = len;
312            if (status != JSVM_OK) {
313                OH_LOG_ERROR(LOG_APP, "JSVM CreateDataView fail");
314            } else {
315                OH_LOG_INFO(LOG_APP, "JSVM CreateDataView success, returnLength: %{public}d", returnLength);
316            }
317            break;
318        case ARRAY_BUFFER:
319            {
320                bool isArraybuffer = false;
321                JSVM_CALL(OH_JSVM_IsArraybuffer(env, returnArrayBuffer, &isArraybuffer));
322                JSVM_Value isArray;
323                OH_JSVM_GetBoolean(env, isArraybuffer, &isArray);
324                returnResult = isArray;
325                if (status != JSVM_OK) {
326                    OH_LOG_ERROR(LOG_APP, "JSVM CreateDataView fail");
327                } else {
328                    OH_LOG_INFO(LOG_APP, "JSVM CreateDataView success, isArraybuffer: %{public}d", isArraybuffer);
329                }
330                break;
331            }
332        case BYTE_OFFSET:
333            JSVM_Value offset;
334            JSVM_CALL(OH_JSVM_CreateInt32(env, returnOffset, &offset));
335            returnResult = offset;
336            if (status != JSVM_OK) {
337                OH_LOG_ERROR(LOG_APP, "JSVM CreateDataView fail");
338            } else {
339                OH_LOG_INFO(LOG_APP, "JSVM CreateDataView success, returnOffset: %{public}d", returnOffset);
340            }
341            break;
342        default:
343            break;
344    }
345    return returnResult;
346}
347// CreateDataView注册回调
348static JSVM_CallbackStruct param[] = {
349    {.data = nullptr, .callback = CreateDataView},
350};
351static JSVM_CallbackStruct *method = param;
352// CreateDataView方法别名，供JS调用
353static JSVM_PropertyDescriptor descriptor[] = {
354    {"createDataView", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
355};
356// 样例测试js
357const char *srcCallNative = R"JS(
358 let BYTE_LENGTH = 0;
359 createDataView(new ArrayBuffer(16), BYTE_LENGTH);
360 let IS_ARRAYBUFFER = 1;
361 createDataView(new ArrayBuffer(16), IS_ARRAYBUFFER);
362 let BYTE_OFFSET = 2;
363 createDataView(new ArrayBuffer(16), BYTE_OFFSET);
364)JS";
365```
366<!-- @[oh_jsvm_create_dataview](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/createdataview/src/main/cpp/hello.cpp) -->
367
368预计的输出结果：
369```
370CreateDataView success, returnLength: 12
371JSVM CreateDataView success, isArraybuffer: 1
372JSVM CreateDataView success, returnOffset: 4
373```
374### OH_JSVM_GetArrayLength
375
376返回 Array 对象的长度。
377
378cpp 部分代码：
379
380```cpp
381// hello.cpp
382#include "napi/native_api.h"
383#include "ark_runtime/jsvm.h"
384#include <hilog/log.h>
385// OH_JSVM_GetArrayLength的样例方法
386static JSVM_Value GetArrayLength(JSVM_Env env, JSVM_CallbackInfo info)
387{
388    size_t argc = 1;
389    JSVM_Value args[1] = {nullptr};
390    JSVM_Value result = nullptr;
391    // 这里要对length进行初始化
392    uint32_t length = 0;
393    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
394    // 检查参数是否为数组
395    bool isArray = false;
396    OH_JSVM_IsArray(env, args[0], &isArray);
397    if (!isArray) {
398        OH_LOG_INFO(LOG_APP, "JSVM Argument must be an array");
399        return nullptr;
400    }
401    /*
402     * 当成功获取数组长度时，length会被赋值成实际JSArray的长度，接口返回JSVM_OK状态码；
403     * 当args[0]不是一个JSArray类型。例如，当args[0]是一个proxy对象时，无法获取长度。
404     * 此时，length维持原值不变，接口返回JSVM_ARRAY_EXPECTED状态码。
405     */
406    JSVM_Status status = OH_JSVM_GetArrayLength(env, args[0], &length);
407    if (status == JSVM_OK) {
408        // 创建返回值
409        JSVM_CALL(OH_JSVM_CreateInt32(env, length, &result));
410        OH_LOG_INFO(LOG_APP, "JSVM length: %{public}d", length);
411    }
412    return result;
413}
414// GetArrayLength注册回调
415static JSVM_CallbackStruct param[] = {
416    {.data = nullptr, .callback = GetArrayLength},
417};
418static JSVM_CallbackStruct *method = param;
419// GetArrayLength方法别名，供JS调用
420static JSVM_PropertyDescriptor descriptor[] = {
421    {"getArrayLength", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
422};
423// 样例测试js
424const char *srcCallNative = R"JS(
425let data = [0, 1, 2, 3, 4, 5];
426getArrayLength(data);
427)JS";
428```
429<!-- @[oh_jsvm_get_array_length](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/getarraylength/src/main/cpp/hello.cpp) -->
430
431预计的输出结果：
432```
433JSVM length: 6
434```
435### OH_JSVM_GetTypedarrayInfo
436
437获取 TypedArray（类型化数组）对象的信息。
438
439cpp 部分代码：
440
441```cpp
442// hello.cpp
443#include "napi/native_api.h"
444#include "ark_runtime/jsvm.h"
445#include <hilog/log.h>
446// OH_JSVM_GetTypedarrayInfo的样例方法
447static JSVM_Value GetTypedArrayInfo(JSVM_Env env, JSVM_CallbackInfo info)
448{
449    // 获取并解析参数，第一个参数为需要获得的信息的TypedArray类型数据，第二个参数为需要获得的信息类型的枚举值
450    size_t argc = 2;
451    JSVM_Value args[2] = {nullptr};
452    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
453
454    // 将第二个参数转为int32类型便于比较
455    int32_t infoTypeParam = 0;
456    OH_JSVM_GetValueInt32(env, args[1], &infoTypeParam);
457    // 定义枚举类型与ArkTS侧枚举类型infoType顺序含义一致
458    enum InfoType { INFO_TYPE, INFO_LENGTH, INFO_ARRAY_BUFFER, INFO_BYTE_OFFSET };
459    void *data;
460    JSVM_TypedarrayType type;
461    size_t byteOffset = 0;
462    size_t length = 0;
463    JSVM_Value arrayBuffer = nullptr;
464    // 调用接口OH_JSVM_GetTypedarrayInfo获得TypedArray类型数据的信息
465    JSVM_Status status = OH_JSVM_GetTypedarrayInfo(env, args[0], &type, &length, &data, &arrayBuffer, &byteOffset);
466    JSVM_Value result = nullptr;
467    // 根据属性名，返回TypedArray对应的属性值
468    switch (infoTypeParam) {
469        case INFO_TYPE:
470            // 如果传入的参数是int8类型的TypedArray数据，它的类型（type）为JSVM_INT8_ARRAY
471            JSVM_Value int8_type;
472            OH_JSVM_GetBoolean(env, type == JSVM_INT8_ARRAY, &int8_type);
473            result = int8_type;
474            if (status != JSVM_OK) {
475                OH_LOG_ERROR(LOG_APP, "JSVM GetTypedArrayInfo fail");
476            } else {
477                OH_LOG_INFO(
478                    LOG_APP, "JSVM GetTypedArrayInfo success, JSVM_INT8_ARRAY: %{public}d", type == JSVM_INT8_ARRAY);
479            }
480            break;
481        case INFO_LENGTH:
482            // TypedArray中的元素数
483            JSVM_Value jsvmLength;
484            JSVM_CALL(OH_JSVM_CreateInt32(env, length, &jsvmLength));
485            result = jsvmLength;
486            if (status != JSVM_OK) {
487                OH_LOG_ERROR(LOG_APP, "JSVM GetTypedArrayInfo fail");
488            } else {
489                OH_LOG_INFO(LOG_APP, "JSVM GetTypedArrayInfo success, length: %{public}d", length);
490            }
491            break;
492        case INFO_BYTE_OFFSET:
493            // TypedArray数组的第一个元素所在的基础原生数组中的字节偏移量
494            JSVM_Value jsvmOffset;
495            JSVM_CALL(OH_JSVM_CreateInt32(env, byteOffset, &jsvmOffset));
496            result = jsvmOffset;
497            if (status != JSVM_OK) {
498                OH_LOG_ERROR(LOG_APP, "JSVM GetTypedArrayInfo fail");
499            } else {
500                OH_LOG_INFO(LOG_APP, "JSVM GetTypedArrayInfo success, byteOffset: %{public}d", byteOffset);
501            }
502            break;
503        case INFO_ARRAY_BUFFER:
504            {
505                // TypedArray下的ArrayBuffer
506                bool isArrayBuffer = false;
507                JSVM_CALL(OH_JSVM_IsArraybuffer(env, arrayBuffer, &isArrayBuffer));
508                JSVM_Value isArray;
509                OH_JSVM_GetBoolean(env, isArrayBuffer, &isArray);
510                result = isArray;
511                if (status != JSVM_OK) {
512                    OH_LOG_ERROR(LOG_APP, "JSVM GetTypedArrayInfo fail");
513                } else {
514                    OH_LOG_INFO(LOG_APP, "JSVM GetTypedArrayInfo success, isArrayBuffer: %{public}d", isArrayBuffer);
515                }
516                break;
517            }
518        default:
519            break;
520    }
521    return result;
522}
523// GetTypedArrayInfo注册回调
524static JSVM_CallbackStruct param[] = {
525    {.data = nullptr, .callback = GetTypedArrayInfo},
526};
527static JSVM_CallbackStruct *method = param;
528// GetTypedArrayInfo方法别名，供JS调用
529static JSVM_PropertyDescriptor descriptor[] = {
530    {"getTypedArrayInfo", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
531};
532// 样例测试js
533const char *srcCallNative = R"JS(
534// is JSVM_INT8_ARRAY
535getTypedArrayInfo(new Int8Array(3), 0);
536// length
537getTypedArrayInfo(new Int8Array(5), 1);
538// is_arraybuffer
539getTypedArrayInfo(new Int8Array(5), 2);
540// byteoffset
541getTypedArrayInfo(new Int8Array(1), 3);
542)JS";
543```
544<!-- @[oh_jsvm_get_typedarray_info](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/gettypedarrayinfo/src/main/cpp/hello.cpp) -->
545
546预计的输出结果：
547```
548JSVM GetTypedArrayInfo success, JSVM_INT8_ARRAY: 1
549JSVM GetTypedArrayInfo success, length: 5
550JSVM GetTypedArrayInfo success, isArrayBuffer: 1
551JSVM GetTypedArrayInfo success, byteOffset: 0
552```
553### OH_JSVM_GetDataviewInfo
554
555获取 Dataview 对象的信息。
556
557cpp 部分代码：
558
559```cpp
560// hello.cpp
561#include "napi/native_api.h"
562#include "ark_runtime/jsvm.h"
563#include <hilog/log.h>
564// OH_JSVM_GetDataviewInfo的样例方法
565static JSVM_Value GetDataViewInfo(JSVM_Env env, JSVM_CallbackInfo info)
566{
567    // 获取并解析参数，第一个参数为需要获得的信息的DataView类型数据，第二个参数为需要获得的信息类型的枚举值
568    size_t argc = 2;
569    JSVM_Value args[2] = {nullptr};
570    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
571    // 将第二个参数转为int32类型的数字
572    int32_t infoType = 0;
573    OH_JSVM_GetValueInt32(env, args[1], &infoType);
574    size_t byteLength = 0;
575    void *data;
576    JSVM_Value arrayBuffer = nullptr;
577    size_t byteOffset = 0;
578    // 定义枚举类型与ArkTS侧枚举类型infoType顺序含义一致
579    enum infoTypeEnum { BYTE_LENGTH, ARRAY_BUFFER, BYTE_OFFSET };
580    // 获取dataview信息
581    JSVM_Status status = OH_JSVM_GetDataviewInfo(env, args[0], &byteLength, &data, &arrayBuffer, &byteOffset);
582    JSVM_Value result = nullptr;
583    switch (infoType) {
584        case BYTE_LENGTH:
585            // 返回查询DataView的长度
586            JSVM_Value len;
587            JSVM_CALL(OH_JSVM_CreateInt32(env, byteLength, &len));
588            result = len;
589            if (status != JSVM_OK) {
590                OH_LOG_ERROR(LOG_APP, "JSVM GetDataViewInfo fail");
591            } else {
592                OH_LOG_INFO(LOG_APP, "JSVM GetDataViewInfo success, byteLength: %{public}d", byteLength);
593            }
594            break;
595        case ARRAY_BUFFER:
596            {
597                // 判断DataView的Info里的arraybuffer是否为arraybuffer
598                bool isArrayBuffer = false;
599                JSVM_CALL(OH_JSVM_IsArraybuffer(env, arrayBuffer, &isArrayBuffer));
600                JSVM_Value isArray;
601                OH_JSVM_GetBoolean(env, isArrayBuffer, &isArray);
602                result = isArray;
603                if (status != JSVM_OK) {
604                    OH_LOG_ERROR(LOG_APP, "JSVM GetDataViewInfo fail");
605                } else {
606                    OH_LOG_INFO(LOG_APP, "JSVM GetDataViewInfo success, isArrayBuffer: %{public}d", isArrayBuffer);
607                }
608                break;
609            }
610        case BYTE_OFFSET:
611            // 返回查询DataView的偏移量
612            JSVM_Value offset;
613            JSVM_CALL(OH_JSVM_CreateInt32(env, byteOffset, &offset));
614            result = offset;
615            if (status != JSVM_OK) {
616                OH_LOG_ERROR(LOG_APP, "JSVM GetDataViewInfo fail");
617            } else {
618                OH_LOG_INFO(LOG_APP, "JSVM GetDataViewInfo success, byteOffset: %{public}d", byteOffset);
619            }
620            break;
621        default:
622            break;
623    }
624    return result;
625}
626// GetDataViewInfo注册回调
627static JSVM_CallbackStruct param[] = {
628    {.data = nullptr, .callback = GetDataViewInfo},
629};
630static JSVM_CallbackStruct *method = param;
631// GetDataViewInfo方法别名，供JS调用
632static JSVM_PropertyDescriptor descriptor[] = {
633    {"getDataViewInfo", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
634};
635// 样例测试js
636const char *srcCallNative = R"JS(
637// bytelength
638getDataViewInfo(new DataView(new Int8Array([2,5]).buffer), 0);
639// is arraybuffer
640let data = 'a';
641let isarraybuffer = 1;
642getDataViewInfo(data, isarraybuffer);
643// is arraybuffer
644data = new DataView(new Int8Array([2,5,3]).buffer);
645isarraybuffer = 1;
646getDataViewInfo(data, isarraybuffer);
647// byte_offset
648data = new DataView(new Int8Array([2,5,3]).buffer);
649isarraybuffer = 2;
650getDataViewInfo(data, isarraybuffer);
651)JS";
652```
653<!-- @[oh_jsvm_get_dataview_info](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/getdataviewinfo/src/main/cpp/hello.cpp) -->
654
655预计的输出结果：
656```
657JSVM GetDataViewInfo success, byteLength: 2
658JSVM GetDataViewInfo fail
659JSVM GetDataViewInfo success, isArrayBuffer: 1
660JSVM GetDataViewInfo success, byteOffset: 0
661```
662### OH_JSVM_IsArray
663
664判断一个 JavaScript 对象是否为 Array 类型对象。
665
666cpp 部分代码：
667
668```cpp
669// hello.cpp
670#include "napi/native_api.h"
671#include "ark_runtime/jsvm.h"
672#include <hilog/log.h>
673// OH_JSVM_IsArray的样例方法
674static JSVM_Value IsArray(JSVM_Env env, JSVM_CallbackInfo info)
675{
676    size_t argc = 1;
677    JSVM_Value args[1] = {nullptr};
678    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
679    bool result = false;
680    JSVM_Status status = OH_JSVM_IsArray(env, args[0], &result);
681    JSVM_Value returnValue = nullptr;
682    JSVM_CALL(OH_JSVM_GetBoolean(env, result, &returnValue));
683    if (status != JSVM_OK) {
684        OH_LOG_ERROR(LOG_APP, "JSVM IsArray fail");
685    } else {
686        OH_LOG_INFO(LOG_APP, "JSVM IsArray success, IsArray: %{public}d", result);
687    }
688    return returnValue;
689}
690// IsArray注册回调
691static JSVM_CallbackStruct param[] = {
692    {.data = nullptr, .callback = IsArray},
693};
694static JSVM_CallbackStruct *method = param;
695// IsArray方法别名，TS侧调用
696static JSVM_PropertyDescriptor descriptor[] = {
697    {"isArray", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
698};
699// 样例测试js
700const char *srcCallNative = R"JS(
701let data = [1, 2, 3, 4, 5];
702isArray(data);
703)JS";
704```
705<!-- @[oh_jsvm_is_array](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/isarray/src/main/cpp/hello.cpp) -->
706
707预计的输出结果：
708```
709JSVM IsArray success, IsArray: 1
710```
711### OH_JSVM_SetElement
712
713在给定对象的指定索引处设置元素。
714
715cpp 部分代码：
716
717```cpp
718// hello.cpp
719#include "napi/native_api.h"
720#include "ark_runtime/jsvm.h"
721#include <hilog/log.h>
722// OH_JSVM_SetElement的样例方法
723static int DIFF_VALUE_THREE = 3;
724static JSVM_Value SetElement(JSVM_Env env, JSVM_CallbackInfo info)
725{
726    size_t argc = DIFF_VALUE_THREE;
727    JSVM_Value args[3] = {nullptr};
728    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
729    int32_t index = 0;
730    OH_JSVM_GetValueInt32(env, args[1], &index);
731    JSVM_Status status = OH_JSVM_SetElement(env, args[0], index, args[2]);
732    if (status != JSVM_OK) {
733        OH_LOG_ERROR(LOG_APP, "JSVM SetElement fail");
734    } else {
735        OH_LOG_INFO(LOG_APP, "JSVM SetElement success");
736    }
737    return args[0];
738}
739// SetElement注册回调
740static JSVM_CallbackStruct param[] = {
741    {.data = nullptr, .callback = SetElement},
742};
743static JSVM_CallbackStruct *method = param;
744// SetElement方法别名，供JS调用
745static JSVM_PropertyDescriptor descriptor[] = {
746    {"setElement", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
747};
748// 样例测试js
749const char *srcCallNative = R"JS(
750let data = [1, 2, 3, 4, 5];
751setElement(data, 3, undefined);
752)JS";
753```
754<!-- @[oh_jsvm_set_element](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/setelement/src/main/cpp/hello.cpp) -->
755
756预计的输出结果：
757```
758JSVM SetElement success
759```
760### OH_JSVM_GetElement
761
762获取给定对象指定索引处的元素。
763
764cpp 部分代码：
765
766```cpp
767// hello.cpp
768#include "napi/native_api.h"
769#include "ark_runtime/jsvm.h"
770#include <hilog/log.h>
771// OH_JSVM_GetElement的样例方法
772static JSVM_Value GetElement(JSVM_Env env, JSVM_CallbackInfo info) {
773    // 获取js侧传入的两个参数
774    size_t argc = 2;
775    JSVM_Value args[2] = {nullptr};
776    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
777    // 获取请求元素的索引值
778    uint32_t index = 0;
779    OH_JSVM_GetValueUint32(env, args[1], &index);
780    // 获取请求索引位置的元素值并存储在result中
781    JSVM_Value result = nullptr;
782    JSVM_Status status = OH_JSVM_GetElement(env, args[0], index, &result);
783    if (status != JSVM_OK) {
784        OH_LOG_ERROR(LOG_APP, "JSVM GetElement fail");
785    } else {
786        OH_LOG_INFO(LOG_APP, "JSVM GetElement success");
787    }
788    return result;
789}
790// GetElement注册回调
791static JSVM_CallbackStruct param[] = {
792    {.data = nullptr, .callback = GetElement},
793};
794static JSVM_CallbackStruct *method = param;
795// GetElement方法别名，供JS调用
796static JSVM_PropertyDescriptor descriptor[] = {
797    {"getElement", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
798};
799// 样例测试js
800const char *srcCallNative = R"JS(
801let arr = [10, 'hello', null, true];
802getElement(arr, 3);
803)JS";
804```
805<!-- @[oh_jsvm_get_element](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/getelement/src/main/cpp/hello.cpp) -->
806
807预计的输出结果：
808```
809JSVM GetElement success
810```
811### OH_JSVM_HasElement
812
813若给定对象的指定索引处拥有属性，获取元素。
814
815cpp 部分代码：
816
817```cpp
818// hello.cpp
819#include "napi/native_api.h"
820#include "ark_runtime/jsvm.h"
821#include <hilog/log.h>
822// OH_JSVM_HasElement的样例方法
823static JSVM_Value HasElement(JSVM_Env env, JSVM_CallbackInfo info) {
824    // 获取js侧传入的两个参数
825    size_t argc = 2;
826    JSVM_Value args[2] = {nullptr};
827    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
828    // 获取要判断的元素的索引
829    uint32_t index = 0;
830    OH_JSVM_GetValueUint32(env, args[1], &index);
831    // 判断指定索引位置的元素是否存在
832    bool hasElement = true;
833    JSVM_Status status = OH_JSVM_HasElement(env, args[0], index, &hasElement);
834    // 将boolean结果转换为JSVM_Value并返回
835    JSVM_Value result = nullptr;
836    if (status != JSVM_OK) {
837        OH_LOG_ERROR(LOG_APP, "JSVM hasElement fail");
838    } else {
839        OH_JSVM_GetBoolean(env, hasElement, &result);
840        OH_LOG_INFO(LOG_APP, "JSVM hasElement: %{public}d", hasElement);
841    }
842    return result;
843}
844// HasElement注册回调
845static JSVM_CallbackStruct param[] = {
846    {.data = nullptr, .callback = HasElement},
847};
848static JSVM_CallbackStruct *method = param;
849// HasElement方法别名，供JS调用
850static JSVM_PropertyDescriptor descriptor[] = {
851    {"hasElement", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
852};
853// 样例测试js
854const char *srcCallNative = R"JS(
855let arr = [10, 'hello', null, true];
856hasElement(arr, 0);
857hasElement(arr, 4);
858)JS";
859```
860<!-- @[oh_jsvm_has_element](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/haselement/src/main/cpp/hello.cpp) -->
861
862预计的输出结果：
863```
864JSVM hasElement: 1
865JSVM hasElement: 0
866```
867### OH_JSVM_DeleteElement
868
869尝试删除给定对象的指定索引处的元素。
870
871cpp 部分代码：
872
873```cpp
874// hello.cpp
875#include "napi/native_api.h"
876#include "ark_runtime/jsvm.h"
877#include <hilog/log.h>
878// OH_JSVM_DeleteElement的样例方法
879static JSVM_Value DeleteElement(JSVM_Env env, JSVM_CallbackInfo info) {
880    // 获取js侧传入的两个参数
881    size_t argc = 2;
882    JSVM_Value args[2] = {nullptr};
883    JSVM_CALL(OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr));
884    // 获取要删除的元素的索引
885    uint32_t index = 0;
886    JSVM_CALL(OH_JSVM_GetValueUint32(env, args[1], &index));
887    // 尝试删除请求索引位置的元素
888    bool deleted = true;
889    JSVM_Status status = OH_JSVM_DeleteElement(env, args[0], index, &deleted);
890    // 将boolean结果转换为JSVM_Value并返回
891    JSVM_Value result = nullptr;
892    if (status != JSVM_OK) {
893        OH_LOG_ERROR(LOG_APP, "JSVM DeleteElement fail");
894    } else {
895        OH_JSVM_GetBoolean(env, deleted, &result);
896        OH_LOG_INFO(LOG_APP, "JSVM DeleteElement: %{public}d", deleted);
897    }
898    return result;
899}
900// DeleteElement注册回调
901static JSVM_CallbackStruct param[] = {
902    {.data = nullptr, .callback = DeleteElement},
903};
904static JSVM_CallbackStruct *method = param;
905// DeleteElement方法别名，供JS调用
906static JSVM_PropertyDescriptor descriptor[] = {
907    {"deleteElement", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
908};
909// 样例测试js
910const char *srcCallNative = R"JS(
911let arr = [10, 'hello', null, true];
912deleteElement(arr, 0);
913)JS";
914```
915<!-- @[oh_jsvm_delete_element](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/deleteelement/src/main/cpp/hello.cpp) -->
916
917预计的输出结果：
918```
919JSVM DeleteElement: 1
920```
921### OH_JSVM_IsDataview
922
923判断一个 JavaScript 对象是否为 Dataview 类型对象。
924
925cpp 部分代码：
926
927```cpp
928// hello.cpp
929#include "napi/native_api.h"
930#include "ark_runtime/jsvm.h"
931#include <hilog/log.h>
932// OH_JSVM_IsDataview的样例方法
933static JSVM_Value IsDataView(JSVM_Env env, JSVM_CallbackInfo info) {
934    size_t argc = 1;
935    JSVM_Value args[1] = {nullptr};
936    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
937    // 调用OH_JSVM_IsDataview接口判断给定入参是否为DataView数据。
938    bool result = false;
939    JSVM_Status status = OH_JSVM_IsDataview(env, args[0], &result);
940    JSVM_Value isDataView = nullptr;
941    OH_JSVM_GetBoolean(env, result, &isDataView);
942    if (status != JSVM_OK) {
943        OH_LOG_ERROR(LOG_APP, "JSVM IsDataView fail");
944    } else {
945        OH_LOG_INFO(LOG_APP, "JSVM IsDataView: %{public}d", result);
946    }
947    return isDataView;
948}
949// IsDataView注册回调
950static JSVM_CallbackStruct param[] = {
951    {.data = nullptr, .callback = IsDataView},
952};
953static JSVM_CallbackStruct *method = param;
954// IsDataView方法别名，TS侧调用
955static JSVM_PropertyDescriptor descriptor[] = {
956    {"isDataView", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
957};
958// 样例测试js
959const char *srcCallNative = R"JS(
960let buffer = new ArrayBuffer(16);
961let dataView = new DataView(buffer);
962isDataView(dataView);
963)JS";
964```
965<!-- @[oh_jsvm_is_dataview](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/isdataview/src/main/cpp/hello.cpp) -->
966
967预计的输出结果：
968```
969JSVM IsDataView: 1
970```
971### OH_JSVM_IsTypedarray
972
973判断一个 JavaScript 对象是否为 TypedArray 类型对象。
974
975cpp 部分代码：
976
977```cpp
978// hello.cpp
979#include "napi/native_api.h"
980#include "ark_runtime/jsvm.h"
981#include <hilog/log.h>
982// OH_JSVM_IsTypedarray的样例方法
983static JSVM_Value IsTypedarray(JSVM_Env env, JSVM_CallbackInfo info) {
984    size_t argc = 1;
985    JSVM_Value args[1] = {nullptr};
986    OH_JSVM_GetCbInfo(env, info, &argc, args, nullptr, nullptr);
987    bool result = false;
988    JSVM_Status status = OH_JSVM_IsTypedarray(env, args[0], &result);
989    JSVM_Value isTypedArray = nullptr;
990    OH_JSVM_GetBoolean(env, result, &isTypedArray);
991    if (status != JSVM_OK) {
992        OH_LOG_ERROR(LOG_APP, "JSVM IsTypedarray fail");
993    } else {
994        OH_LOG_INFO(LOG_APP, "JSVM IsTypedarray: %{public}d", result);
995    }
996    return isTypedArray;
997}
998// IsTypedarray注册回调
999static JSVM_CallbackStruct param[] = {
1000    {.data = nullptr, .callback = IsTypedarray},
1001};
1002static JSVM_CallbackStruct *method = param;
1003// IsTypedarray方法别名，TS侧调用
1004static JSVM_PropertyDescriptor descriptor[] = {
1005    {"isTypedarray", nullptr, method++, nullptr, nullptr, nullptr, JSVM_DEFAULT},
1006};
1007// 样例测试js
1008const char *srcCallNative = R"JS(
1009isTypedarray(new Uint16Array([1, 2, 3, 4]));
1010)JS";
1011```
1012<!-- @[oh_jsvm_is_typedarray](https://gitcode.com/openharmony/applications_app_samples/blob/master/code/DocsSample/ArkTS/JSVMAPI/JsvmUsageGuide/JsvmAboutArray/istypedarray/src/main/cpp/hello.cpp) -->
1013
1014预计的输出结果：
1015```
1016JSVM IsTypedarray: 1
1017```