1# Working with Arrays Using Node-API 2 3## Introduction 4 5Node-API provides APIs for directly managing ArkTS arrays. 6 7## Basic Concepts 8 9Node-API can be used to create, access, modify, and traverse arrays. Before using Node-API, it's helpful if you understand the following concepts: 10 11- Array creation: You can use **api_create_array** to create an array and pass it to the ArkTS layer. 12- Array-related operations: You can use the APIs provides by the Node-API module to obtain the length of an ArkTS array, retrieve the element at the specified index, and set the element value at the specified index. 13- **TypedArray**: A **TypedArray** object in ArkTS is an array-like view of an underlying binary data buffer. It can be simply understood as an array of elements of the specified type. There is no constructor for **TypedArray** objects, but its child class constructor can be used to construct **TypedArray** data. The child classes of **TypedArray** include **Int8Array**, **Uint8Array**, **Uint8ClampedArray**, **Int16Array**, and **Int32Array**. 14- **DataView**: **DataView** is an ArkTS view that allows a variety of number types to be read and written in an **ArrayBuffer** object. 15- **ArrayBuffer**: **ArrayBuffer** is a data struct used to represent a binary data buffer of fixed length. 16 17## Available APIs 18 19The following table describes the APIs for managing ArkTS arrays. 20| API| Description| 21| -------- | -------- | 22| napi_create_array | Creates an ArkTS array.| 23| napi_create_array_with_length | Creates an ArkTS array of the specified length.| 24| napi_get_array_length | Obtains the length of an ArkTS array.| 25| napi_is_array | Checks whether the given **napi_value** is an array.| 26| napi_set_element | Sets an element at the specified index in the given ArkTS array.| 27| napi_get_element | Obtains the element at the specified index in the given ArkTS array.| 28| napi_has_element | Checks whether the element at the specified index exists.| 29| napi_delete_element | Deletes the element at the specified index of the given ArkTS array.| 30| napi_create_typedarray | Creates an ArkTS **TypedArray** object of the specified type, such as **Uint8Array** or **Int32Array**. You can use this API to convert a native value into a **TypedArray** object for performant data processing. | 31| napi_is_typedarray | Checks whether the given **napi_value** is a **TypedArray** object.| 32| napi_get_typedarray_info | Obtains the properties of a **TypedArray** object.| 33| napi_create_dataview | Creates a **DataView** object, which allows access to binary data.| 34| napi_is_dataview | Checks whether the given **napi_value** is a **DataView** object in ArkTS.| 35| napi_get_dataview_info | Obtains the properties of a **DataView** object.| 36 37## Example 38 39If you are just starting out with Node-API, see [Node-API Development Process](use-napi-process.md). The following demonstrates only the C++ and ArkTS code for array management APIs. 40 41### napi_create_array 42 43Call **napi_create_array** to create an ArkTS array. 44 45CPP code: 46 47```cpp 48#include "napi/native_api.h" 49 50static napi_value CreateArray(napi_env env, napi_callback_info info) 51{ 52 // Create an empty array. 53 napi_value jsArray = nullptr; 54 napi_create_array(env, &jsArray); 55 // Assign a value to the created array. 56 for (int i = 0; i < 5; i++) { 57 napi_value element; 58 napi_create_int32(env, i, &element); 59 napi_set_element(env, jsArray, i, element); 60 } 61 // Return the created array. 62 return jsArray; 63} 64``` 65 66API declaration: 67 68```ts 69// index.d.ts 70export const createArray: () => number[]; 71``` 72 73ArkTS code: 74 75```ts 76import hilog from '@ohos.hilog' 77import testNapi from 'libentry.so' 78 79hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_array:%{public}s', JSON.stringify(testNapi.createArray())); 80``` 81 82### napi_create_array_with_length 83 84Call **napi_create_array_with_length** to create an ArkTS array of the specified length. 85 86CPP code: 87 88```cpp 89#include "napi/native_api.h" 90 91static napi_value CreateArrayWithLength(napi_env env, napi_callback_info info) 92{ 93 // Obtain the parameters passed from ArkTS. 94 size_t argc = 1; 95 napi_value argv[1] = {nullptr}; 96 napi_value jsArray = nullptr; 97 napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr); 98 // Obtain the array length passed. 99 int32_t length = 0; 100 napi_get_value_int32(env, argv[0], &length); 101 // Use napi_create_array_with_length to create an array of the specified length. 102 napi_create_array_with_length(env, length, &jsArray); 103 // Return the array. 104 return jsArray; 105} 106``` 107 108API declaration: 109 110```ts 111// index.d.ts 112export const createArrayWithLength: (length: number) => void[]; 113``` 114 115ArkTS code: 116 117```ts 118import hilog from '@ohos.hilog' 119import testNapi from 'libentry.so' 120 121let array = testNapi.createArrayWithLength(6); 122hilog.info(0x0000, 'testTag', 'Test Node-API napi_create_array_with_length:%{public}d', array.length); 123``` 124 125### napi_get_array_length 126 127Call **napi_get_array_length** to obtain the length of an array. 128 129CPP code: 130 131```cpp 132#include "napi/native_api.h" 133 134static napi_value GetArrayLength(napi_env env, napi_callback_info info) 135{ 136 // Obtain the parameters passed from ArkTS. 137 size_t argc = 1; 138 napi_value args[1] = {nullptr}; 139 napi_value result; 140 uint32_t length; 141 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 142 // Check whether the parameter is an array. 143 bool is_array; 144 napi_is_array(env, args[0], &is_array); 145 if (!is_array) { 146 napi_throw_type_error(env, nullptr, "Argument must be an array"); 147 return nullptr; 148 } 149 napi_get_array_length(env, args[0], &length); 150 // Create a return value. 151 napi_create_uint32(env, length, &result); 152 return result; 153} 154``` 155 156API declaration: 157 158```ts 159// index.d.ts 160export const getArrayLength: (arr: Array<any>) => number | void; 161``` 162 163ArkTS code: 164 165```ts 166import hilog from '@ohos.hilog' 167import testNapi from 'libentry.so' 168 169const arr = [0, 1, 2, 3, 4, 5]; 170hilog.info(0x0000, 'testTag', 'Test Node-API get_array_length:%{public}d', testNapi.getArrayLength(arr)); 171``` 172 173### napi_is_array 174 175Call **napi_is_array** to check whether the given ArkTS value is an array. 176 177CPP code: 178 179```cpp 180#include "napi/native_api.h" 181 182static napi_value IsArray(napi_env env, napi_callback_info info) 183{ 184 // Obtain the parameters passed from ArkTS. 185 size_t argc = 1; 186 napi_value args[1] = {nullptr}; 187 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 188 // Call napi_is_array to check whether the input parameter is an array. 189 bool result; 190 napi_status status; 191 status = napi_is_array(env, args[0], &result); 192 if (status != napi_ok) { 193 napi_throw_error(env, nullptr, "Node-API napi_is_array fail"); 194 return nullptr; 195 } 196 // Convert the result to napi_value and return it. 197 napi_value returnValue; 198 napi_get_boolean(env, result, &returnValue); 199 200 return returnValue; 201} 202``` 203 204API declaration: 205 206```ts 207// index.d.ts 208export const isArray: <T>(data: Array<T> | T) => boolean | void; 209``` 210 211ArkTS code: 212 213```ts 214import hilog from '@ohos.hilog' 215import testNapi from 'libentry.so' 216try { 217 let value = new Array<number>(1); 218 let data = "123"; 219 hilog.info(0x0000, 'testTag', 'Test Node-API napi_is_array: %{public}s', testNapi.isArray<number>(value)); 220 hilog.info(0x0000, 'testTag', 'Test Node-API napi_is_array: %{public}s', testNapi.isArray<string>(data)); 221} catch (error) { 222 hilog.error(0x0000, 'testTag', 'Test Node-API napi_is_array error: %{public}s', error.message); 223} 224``` 225 226### napi_set_element 227 228Call **napi_set_element** to set an element at the specified index in an ArkTS array. 229For the object that uses the index value as the key, you can use **napi_set_element** to set the property value. 230 231CPP code: 232 233```cpp 234#include "napi/native_api.h" 235 236static napi_value NapiSetElement(napi_env env, napi_callback_info info) 237{ 238 // Obtain the parameters passed from ArkTS. 239 size_t argc = 3; 240 napi_value args[3] = {nullptr}; 241 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 242 // Check whether the first parameter is an array. 243 bool isArr = false; 244 napi_is_array(env, args[0], &isArr); 245 if (!isArr) { 246 napi_throw_type_error(env, nullptr, "Argument should be an object of type array"); 247 return nullptr; 248 } 249 // Obtain the index of the element to be set. 250 double index = 0; 251 napi_get_value_double(env, args[1], &index); 252 // Set the input value at the specified index of the array. 253 napi_set_element(env, args[0], static_cast<uint32_t>(index), args[2]); 254 255 return nullptr; 256} 257``` 258 259API declaration: 260 261```ts 262export const napiSetElement: <T>(arr: Array<T>, index: number, value: T) => void; 263``` 264 265ArkTS code: 266 267```ts 268import hilog from '@ohos.hilog' 269import testNapi from 'libentry.so' 270let arr = [10, 20, 30]; 271testNapi.napiSetElement<number | string>(arr, 1, 'newElement'); 272testNapi.napiSetElement<number | string>(arr, 2, 50); 273hilog.info(0x0000, 'testTag', 'Test Node-API napi_set_element arr: %{public}s', arr.toString()); 274hilog.info(0x0000, 'testTag', 'Test Node-API napi_set_element arr[3]: %{public}s', arr[3]); 275interface MyObject { 276 first: number; 277 second: number; 278} 279let obj: MyObject = { 280 first: 1, 281 second: 2 282}; 283testNapi.napiSetElement<number | string | Object>(arr, 4, obj); 284let objAsString = JSON.stringify(arr[4]); 285hilog.info(0x0000, 'testTag', 'Test Node-API napi_set_element arr[4]: %{public}s', objAsString); 286``` 287 288### napi_get_element 289 290Call **napi_get_element** to obtain the element at the specified index in an ArkTS array. The index must be within the valid range of the array. Otherwise, **undefined** will be returned. 291 292CPP code: 293 294```cpp 295#include "napi/native_api.h" 296 297static napi_value NapiGetElement(napi_env env, napi_callback_info info) 298{ 299 // Obtain the parameters passed from ArkTS. 300 size_t argc = 2; 301 napi_value args[2] = {nullptr}; 302 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 303 // Obtain the index value of the element. 304 uint32_t index; 305 napi_get_value_uint32(env, args[1], &index); 306 // Obtain the element value at the index and store it in result. 307 napi_value result; 308 napi_get_element(env, args[0], index, &result); 309 310 return result; 311} 312``` 313 314API declaration: 315 316```ts 317// index.d.ts 318export const napiGetElement: <T>(arr: Array<T>, index: number) => number | string | Object | boolean | undefined; 319``` 320 321ArkTS code: 322 323```ts 324import hilog from '@ohos.hilog' 325import testNapi from 'libentry.so' 326 327interface MyObject { 328 first: number; 329 second: number; 330} 331let obj: MyObject = { 332 first: 1, 333 second: 2 334}; 335let arr = [10, 'hello', null, obj]; 336hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_element arr[0]: %{public}d', testNapi.napiGetElement<number | string | null | Object>(arr, 0)); 337hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_element arr[1]: %{public}s', testNapi.napiGetElement<number | string | null | Object>(arr, 1)); 338hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_element arr[2]: %{public}s', testNapi.napiGetElement<number | string | null | Object>(arr, 2)); 339hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_element arr[3]: %{public}s', testNapi.napiGetElement<number | string | null | Object>(arr, 3)); 340hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_element arr[4]: %{public}s', JSON.stringify(testNapi.napiGetElement(arr, 4))); 341hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_element arr[null]: %{public}s', testNapi.napiGetElement<number | string | null | Object>(arr, 5)); 342``` 343 344### napi_has_element 345 346Call **napi_has_element** to check whether an ArkTS array has the element at the specified index. If the specified index exceeds the valid range of the array, **false** will be returned, which indicates that the element does not exist. 347 348CPP code: 349 350```cpp 351#include "napi/native_api.h" 352 353static napi_value NapiHasElement(napi_env env, napi_callback_info info) 354{ 355 // Obtain the parameters passed from ArkTS. 356 size_t argc = 2; 357 napi_value args[2] = {nullptr}; 358 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 359 // Obtain the index of the element to be checked. 360 uint32_t index; 361 napi_get_value_uint32(env, args[1], &index); 362 // Check whether the element exists based on the given index. 363 bool hasElement = true; 364 napi_has_element(env, args[0], index, &hasElement); 365 // Convert the bool value to napi_value and return it. 366 napi_value result; 367 napi_get_boolean(env, hasElement, &result); 368 return result; 369} 370``` 371 372API declaration: 373 374```ts 375// index.d.ts 376export const napiHasElement: <T>(arr: Array<T>, index: number) => boolean; 377``` 378 379ArkTS code: 380 381```ts 382import hilog from '@ohos.hilog' 383import testNapi from 'libentry.so' 384 385let arr = [10, 'hello', null, 'world']; 386hilog.info(0x0000, 'testTag', 'Test Node-API napi_has_element arr[0]: %{public}s', testNapi.napiHasElement<number | string | null>(arr, 0)); 387hilog.info(0x0000, 'testTag', 'Test Node-API napi_has_element arr[7]: %{public}s', testNapi.napiHasElement<number | string | null>(arr, 7)); 388``` 389 390### napi_delete_element 391 392Call **napi_delete_element** to delete the element at the specified index from an ArkTS array. 393 394CPP code: 395 396```cpp 397#include "napi/native_api.h" 398 399static napi_value NapiDeleteElement(napi_env env, napi_callback_info info) 400{ 401 // Obtain the parameters passed from ArkTS. 402 size_t argc = 2; 403 napi_value args[2] = {nullptr}; 404 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 405 // Obtain the index of the element to delete. 406 uint32_t index; 407 napi_get_value_uint32(env, args[1], &index); 408 // Delete the element at the specified index. 409 bool deleted = true; 410 napi_delete_element(env, args[0], index, &deleted); 411 // Convert the bool value to napi_value and return it. 412 napi_value result; 413 napi_get_boolean(env, deleted, &result); 414 return result; 415} 416``` 417 418API declaration: 419 420```ts 421// index.d.ts 422export const napiDeleteElement: <T>(arr: Array<T>, index: number) => boolean; 423``` 424 425ArkTS code: 426 427```ts 428// Import napiHasElement and napiGetElement. 429import hilog from '@ohos.hilog' 430import testNapi from 'libentry.so' 431 432let arr = [10, 'hello', null, 'world']; 433hilog.info(0x0000, 'testTag', 'Test Node-API napi_has_element arr[0]: %{public}s', testNapi.napiHasElement<number | string | null>(arr, 0)); 434hilog.info(0x0000, 'testTag', 'Test Node-API napi_delete_element arr[0]: %{public}s', testNapi.napiDeleteElement<number | string | null>(arr, 0)); 435hilog.info(0x0000, 'testTag', 'Test Node-API napi_has_element deleted arr[0]: %{public}s', testNapi.napiHasElement<number | string | null>(arr, 0)); 436hilog.info(0x0000, 'testTag', 'Test Node-API napi_get_element arr[0]: %{public}d', testNapi.napiGetElement<number | string | null>(arr, 0)); 437``` 438 439### napi_create_typedarray 440 441Call **napi_create_typedarray** to create an ArkTS **TypedArray** object of the specified type from an existing **ArrayBuffer** object. 442 443CPP code: 444 445```cpp 446#include "napi/native_api.h" 447 448static napi_value CreateTypedArray(napi_env env, napi_callback_info info) 449{ 450 // Obtain the parameters passed from ArkTS. 451 size_t argc = 1; 452 napi_value args[1] = {nullptr}; 453 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 454 int32_t typeNum = 0; 455 napi_get_value_int32(env, args[0], &typeNum); 456 napi_typedarray_type arrayType; 457 // Set the element size. 458 size_t elementSize = 0; 459 // Determine the type of the array to create based on the type value passed. 460 arrayType = static_cast<napi_typedarray_type>(typeNum); 461 switch (typeNum) { 462 case napi_int8_array: 463 case napi_uint8_array: 464 case napi_uint8_clamped_array: 465 elementSize = sizeof(int8_t); 466 break; 467 case napi_int16_array: 468 case napi_uint16_array: 469 elementSize = sizeof(int16_t); 470 break; 471 case napi_int32_array: 472 case napi_uint32_array: 473 elementSize = sizeof(int32_t); 474 break; 475 case napi_float32_array: 476 elementSize = sizeof(float); 477 break; 478 case napi_float64_array: 479 elementSize = sizeof(double); 480 break; 481 case napi_bigint64_array: 482 case napi_biguint64_array: 483 elementSize = sizeof(int64_t); 484 break; 485 default: 486 // By default, an array of the napi_int8_array type is created. 487 arrayType = napi_int8_array; 488 elementSize = sizeof(int8_t); 489 break; 490 } 491 size_t length = 3; 492 napi_value arrayBuffer = nullptr; 493 napi_value typedArray = nullptr; 494 void *data; 495 // Create an ArrayBuffer object. 496 napi_create_arraybuffer(env, length * elementSize, (void **)&data, &arrayBuffer); 497 // Create a TypedArray object of the specified type. 498 napi_create_typedarray(env, arrayType, length, arrayBuffer, 0, &typedArray); 499 return typedArray; 500} 501``` 502 503API declaration: 504 505```ts 506// index.d.ts 507export const enum TypedArrayTypes { 508 INT8_ARRAY = 0, 509 UINT8_ARRAY, 510 UINT8_CLAMPED_ARRAY, 511 INT16_ARRAY, 512 UINT16_ARRAY, 513 INT32_ARRAY, 514 UINT32_ARRAY, 515 FLOAT32_ARRAY, 516 FLOAT64_ARRAY, 517 BIGINT64_ARRAY, 518 BIGuINT64_ARRAY, 519} 520export const createTypedArray: <T>(type: TypedArrayTypes) => T; 521``` 522 523ArkTS code: 524 525```ts 526import hilog from '@ohos.hilog' 527import testNapi from 'libentry.so' 528 529// Pass the type of the array to create. 530let typedArray = testNapi.createTypedArray<Int8Array>(testNapi.TypedArrayTypes["INT8_ARRAY"]); 531if (typedArray instanceof Int8Array) { 532 hilog.info(0x0000, 'testTag', ' Node-API napi_create_typedarray: Int8Array'); 533} 534let uint8Array = testNapi.createTypedArray<Uint8Array>(testNapi.TypedArrayTypes["UINT8_ARRAY"]); 535if (uint8Array instanceof Uint8Array) { 536 hilog.info(0x0000, 'testTag', ' Node-API napi_create_typedarray: Uint8Array'); 537} 538``` 539 540Modify the module initialization in **use-napi-process.md** as follows: 541 542```cpp 543#include <string> 544 545EXTERN_C_START 546static napi_value Init(napi_env env, napi_value exports) 547{ 548 // The defined TypedArray type is used by ArkTS to store typedArrayTypes. For details about the example, see createTypedArray() on ArkTS. 549 napi_value typedArrayTypes; 550 napi_create_object(env, &typedArrayTypes); 551 napi_value typeIndex; 552 std::string typeKeys[] = { 553 "INT8_ARRAY", "UINT8_ARRAY", "UINT8_CLAMPED_ARRAY", "INT16_ARRAY", "UINT16_ARRAY", "INT32_ARRAY", 554 "UINT32_ARRAY", "FLOAT32_ARRAY", "FLOAT64_ARRAY", "BIGINT64_ARRAY", "BIGUINT64_ARRAY", 555 }; 556 for (int32_t i = 0; i < sizeof(typeKeys) / sizeof(typeKeys[0]); i++) { 557 napi_create_int32(env, i, &typeIndex); 558 napi_set_named_property(env, typedArrayTypes, typeKeys[i].c_str(), typeIndex); 559 } 560 napi_property_descriptor desc[] = { 561 {"createTypedArray", nullptr, CreateTypedArray, nullptr, nullptr, nullptr, napi_default, nullptr}, 562 {"TypedArrayTypes", nullptr, nullptr, nullptr, nullptr, typedArrayTypes, napi_default, nullptr} 563 }; 564 napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 565 return exports; 566} 567EXTERN_C_END 568 569``` 570 571### napi_is_typedarray 572 573Call **napi_is_typedarray** to check whether the **napi_value** given from ArkTS is a **TypedArray** object. 574 575CPP code: 576 577```cpp 578#include "napi/native_api.h" 579 580static napi_value IsTypedarray(napi_env env, napi_callback_info info) 581{ 582 // Obtain the parameters passed from ArkTS. 583 size_t argc = 1; 584 napi_value args[1] = {nullptr}; 585 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 586 // Call napi_is_typedarray to check whether the input parameter type is TypedArray. 587 bool result = false; 588 napi_status status; 589 status = napi_is_typedarray(env, args[0], &result); 590 if (status != napi_ok) { 591 napi_throw_error(env, nullptr, "Node-API napi_is_typedarray fail"); 592 return nullptr; 593 } 594 // Convert the result to napi_value and return it. 595 napi_value returnValue = nullptr; 596 napi_get_boolean(env, result, &returnValue); 597 598 return returnValue; 599} 600``` 601 602API declaration: 603 604```ts 605// index.d.ts 606export const isTypedarray: (data: Object) => boolean | void; 607``` 608 609ArkTS code: 610 611```ts 612import hilog from '@ohos.hilog' 613import testNapi from 'libentry.so' 614try { 615 let value = new Uint8Array([1, 2, 3, 4]); 616 let data = "123"; 617 hilog.info(0x0000, 'testTag', 'Test Node-API napi_is_typedarray: %{public}s', testNapi.isTypedarray(value)); 618 hilog.info(0x0000, 'testTag', 'Test Node-API napi_is_typedarray: %{public}s', testNapi.isTypedarray(data)); 619} catch (error) { 620 hilog.error(0x0000, 'testTag', 'Test Node-API napi_is_typedarray error: %{public}s', error.message); 621} 622``` 623 624### napi_get_typedarray_info 625 626Call **napi_get_typedarray_info** to obtain properties of a **TypedArray** object. 627 628CPP code: 629 630```cpp 631#include "napi/native_api.h" 632 633static napi_value GetTypedarrayInfo(napi_env env, napi_callback_info info) 634{ 635 // Obtain and parse the parameters passed from ArkTS. The first parameter is the TypedArray type of the property to obtain, and the second parameter is the enums of the property type to obtain. 636 size_t argc = 2; 637 napi_value args[2] = {nullptr}; 638 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 639 // Convert the second parameter to the int32 type for comparison. 640 int32_t infoTypeParam; 641 napi_get_value_int32(env, args[1], &infoTypeParam); 642 // Define the InfoType enums in the same sequence as those in ArkTS. 643 enum InfoType { INFO_TYPE = 1, INFO_LENGTH, INFO_ARRAY_BUFFER, INFO_BYTE_OFFSET }; 644 void *data; 645 napi_typedarray_type type; 646 size_t byteOffset, length; 647 napi_value arraybuffer; 648 // Call napi_get_typedarray_info to obtain TypedArray information. 649 napi_get_typedarray_info(env, args[0], &type, &length, &data, &arraybuffer, &byteOffset); 650 napi_value result; 651 // Return the property value based on the property name. 652 switch (infoTypeParam) { 653 case INFO_TYPE: 654 // If the input parameter is TypedArray data of the int8 type, the value type is napi_int8_array. 655 napi_value int8_type; 656 napi_get_boolean(env, type == napi_int8_array, &int8_type); 657 result = int8_type; 658 break; 659 case INFO_LENGTH: 660 // Number of elements in the TypedArray object. 661 napi_value napiLength; 662 napi_create_int32(env, length, &napiLength); 663 result = napiLength; 664 break; 665 case INFO_BYTE_OFFSET: 666 // Byte offset of the first TypedArray element in the native array. 667 napi_value napiByteOffset; 668 napi_create_int32(env, byteOffset, &napiByteOffset); 669 result = napiByteOffset; 670 break; 671 case INFO_ARRAY_BUFFER: 672 // ArrayBuffer under TypedArray. 673 result = arraybuffer; 674 break; 675 default: 676 break; 677 } 678 return result; 679} 680``` 681 682API declaration: 683 684```ts 685// index.d.ts 686export const getTypedarrayInfo: <T>(typeArray: T, infoType: number) => ArrayBuffer | number | boolean; 687``` 688 689ArkTS code: 690 691```ts 692import hilog from '@ohos.hilog' 693import testNapi from 'libentry.so' 694 695// Pass in the TypedArray type. TypedArray is a class array data view used to describe binary data. It does not have a constructor and can be constructed from its child class. 696// The child classes of TypedArray include Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, and Int32Array. 697let int8Array = new Int8Array([15, 7]); 698// Define the InfoType enums, which are the properties of TypedArray. 699enum InfoType { 700 TYPE = 1, // Type of the TypedArray. 701 LENGTH = 2, // Length of the input TypedArray. 702 ARRAY_BUFFER = 3, // ArrayBuffer under TypedArray. 703 BYTE_OFFSET = 4 // Offset of the first ArrayBuffer element in the native array. 704}; 705let arrbuff = testNapi.getTypedarrayInfo(int8Array, InfoType.ARRAY_BUFFER) as ArrayBuffer; 706// Convert arrbuffer to an array. 707let arr = new Array(new Int8Array(arrbuff)); 708hilog.info(0x0000, 'Node-API', 'get_typedarray_info_arraybuffer: %{public}s', arr.toString()); 709hilog.info(0x0000, 'Node-API', 'get_typedarray_info_isIn8Array: %{public}s', testNapi.getTypedarrayInfo(int8Array, InfoType.TYPE).toString()); 710hilog.info(0x0000, 'Node-API', 'get_typedarray_info_length: %{public}d', testNapi.getTypedarrayInfo(int8Array, InfoType.LENGTH)); 711hilog.info(0x0000, 'Node-API', 'get_typedarray_info_byte_offset: %{public}d', testNapi.getTypedarrayInfo(int8Array, InfoType.BYTE_OFFSET)); 712``` 713 714### napi_create_dataview 715 716Call **napi_create_dataview** to create a **DataView** object to facilitate access and operation of binary data. You need to specify a buffer pointing to the binary data and the number of bytes included. 717 718CPP code: 719 720```cpp 721#include "napi/native_api.h" 722 723static napi_value CreateDataView(napi_env env, napi_callback_info info) 724{ 725 // Obtain the parameters passed from ArkTS. 726 size_t argc = 1; 727 napi_value args[1] = {nullptr}; 728 napi_value arraybuffer = nullptr; 729 napi_value result = nullptr; 730 // Byte length of DataView. 731 size_t byteLength = 12; 732 // Offset of the byte. 733 size_t byteOffset = 4; 734 // Obtain the parameters of the callback. 735 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 736 // Convert the parameter into the object type. 737 napi_coerce_to_object(env, args[0], &arraybuffer); 738 // Create a DataView object with the specified byte length and offset. 739 napi_status status = napi_create_dataview(env, byteLength, arraybuffer, byteOffset, &result); 740 if (status != napi_ok) { 741 // Throw an error indicating that the DataView fails to be created. 742 napi_throw_error(env, nullptr, "Failed to create DataView"); 743 return nullptr; 744 } 745 // Obtain the pointer to the DataView object and the length. 746 uint8_t *data = nullptr; 747 size_t length = 0; 748 napi_get_dataview_info(env, result, &length, (void **)&data, nullptr, nullptr); 749 // Assign values to DataView. 750 for (size_t i = 0; i < length; i++) { 751 data[i] = static_cast<uint8_t>(i + 1); 752 } 753 return result; 754} 755``` 756 757API declaration: 758 759```ts 760// index.d.ts 761export const createDataView: (arraybuffer:ArrayBuffer) => DataView | void; 762``` 763 764ArkTS code: 765 766```ts 767import hilog from '@ohos.hilog' 768import testNapi from 'libentry.so' 769 770const arrayBuffer = new ArrayBuffer(16); 771const dataView = testNapi.createDataView(arrayBuffer) as DataView; 772hilog.info(0x0000, 'testTag', 'Test Node-API dataView: %{public}d', dataView.byteLength); 773hilog.info(0x0000, 'testTag','Test Node-API dataView first data: %{public}d', dataView.getInt8(0)); 774``` 775 776### napi_is_dataview 777 778Call **napi_is_dataview** to check whether the **napi_value** given from ArkTS is a **DataView** object. 779 780CPP code: 781 782```cpp 783#include "napi/native_api.h" 784 785static napi_value IsDataView(napi_env env, napi_callback_info info) 786{ 787 // Obtain the parameters passed from ArkTS. 788 size_t argc = 1; 789 napi_value args[1] = {nullptr}; 790 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 791 792 // Call napi_is_dataview to check whether the input parameter is a DataView object. 793 bool result; 794 napi_status status; 795 status = napi_is_dataview(env, args[0], &result); 796 if (status != napi_ok) { 797 napi_throw_error(env, nullptr, "Node-API napi_is_dataview fail"); 798 return nullptr; 799 } 800 // Convert the result to napi_value and return it. 801 napi_value returnValue; 802 napi_get_boolean(env, result, &returnValue); 803 804 return returnValue; 805} 806``` 807 808API declaration: 809 810```ts 811// index.d.ts 812export const isDataView: (date: DataView | string) => boolean | void; 813``` 814 815ArkTS code: 816 817```ts 818import hilog from '@ohos.hilog' 819import testNapi from 'libentry.so' 820try { 821 let buffer = new ArrayBuffer(16); 822 let dataView = new DataView(buffer); 823 let data = "123"; 824 hilog.info(0x0000, 'testTag', 'Test Node-API napi_is_dataview: %{public}s', testNapi.isDataView(dataView)); 825 hilog.info(0x0000, 'testTag', 'Test Node-API napi_is_dataview: %{public}s', testNapi.isDataView(data)); 826} catch (error) { 827 hilog.error(0x0000, 'testTag', 'Test Node-API napi_is_dataview error: %{public}s', error.message); 828} 829``` 830 831### napi_get_dataview_info 832 833Call **napi_get_dataview_info** to obtain properties of a **DataView** object. 834 835CPP code: 836 837```cpp 838#include "napi/native_api.h" 839 840static napi_value GetDataViewInfo(napi_env env, napi_callback_info info) 841{ 842 // Obtain the parameters passed from ArkTS. 843 size_t argc = 2; 844 napi_value args[2] = {nullptr}; 845 napi_get_cb_info(env, info, &argc, args, nullptr, nullptr); 846 // Convert the second parameter to an int32 number. 847 int32_t infoType; 848 napi_get_value_int32(env, args[1], &infoType); 849 size_t byteLength; 850 void *data; 851 napi_value arrayBuffer; 852 size_t byteOffset; 853 // Define the InfoType enums in the same sequence as those in ArkTS. 854 enum InfoType { BYTE_LENGTH = 0, ARRAY_BUFFER, BYTE_OFFSET }; 855 // Obtain DataView information. 856 napi_get_dataview_info(env, args[0], &byteLength, &data, &arrayBuffer, &byteOffset); 857 napi_value result; 858 switch (infoType) { 859 case BYTE_LENGTH: 860 // Return the number of bytes of the DataView object. 861 napi_value napiByteLength; 862 napi_create_int32(env, byteLength, &napiByteLength); 863 result = napiByteLength; 864 break; 865 case ARRAY_BUFFER: 866 // Return the ArrayBuffer of the DataView object. 867 result = arrayBuffer; 868 break; 869 case BYTE_OFFSET: 870 // Return the byte offset of the DataView object. 871 napi_value napiByteOffset; 872 napi_create_int32(env, byteOffset, &napiByteOffset); 873 result = napiByteOffset; 874 break; 875 default: 876 break; 877 } 878 return result; 879} 880``` 881 882API declaration: 883 884```ts 885// index.d.ts 886export const getDataViewInfo: (dataView: DataView, infoType: number) => ArrayBuffer | number; 887``` 888 889ArkTS code: 890 891```ts 892import hilog from '@ohos.hilog' 893import testNapi from 'libentry.so' 894 895// Create an ArrayBuffer object. 896let arrayBuffer = new Int8Array([2, 5]).buffer; 897// Use arrayBuffer to create a DataView object. 898let dataView = new DataView(arrayBuffer); 899// Define an enum type. 900enum InfoType { 901 BYTE_LENGTH = 0, 902 ARRAY_BUFFER = 1, 903 BYTE_OFFSET = 2, 904}; 905// Pass in the parameter of DataView to obtain the number of bytes in DataView. 906hilog.info(0x0000, 'Node-API', 'get_dataview_info_bytelength %{public}d', testNapi.getDataViewInfo(dataView, InfoType.BYTE_LENGTH)); 907// Pass in the parameter of DataView to obtain the ArrayBuffer of DataView. 908let arrbuff = testNapi.getDataViewInfo(dataView, InfoType.ARRAY_BUFFER) as ArrayBuffer; 909// Convert arraybuffer to an array. 910let arr = Array.from(new Int8Array(arrbuff)); 911hilog.info(0x0000, 'Node-API', 'get_dataview_info_arraybuffer %{public}s', arr.toString()); 912// Pass in the parameter of DataView to obtain the byte offset in the data buffer of DataView. 913hilog.info(0x0000, 'Node-API', 'get_dataview_info_byteoffset %{public}d', testNapi.getDataViewInfo(dataView, InfoType.BYTE_OFFSET)); 914``` 915 916To print logs in the native CPP, add the following information to the **CMakeLists.txt** file and add the header file by using **#include "hilog/log.h"**. 917 918```text 919// CMakeLists.txt 920add_definitions( "-DLOG_DOMAIN=0xd0d0" ) 921add_definitions( "-DLOG_TAG=\"testTag\"" ) 922target_link_libraries(entry PUBLIC libhilog_ndk.z.so) 923``` 924