1# @ohos.util.ArrayList (线性容器ArrayList) 2 3>  **说明：** 4> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 5 6ArrayList是一种线性数据结构，底层基于数组实现。ArrayList会根据实际需要动态调整容量，每次扩容增加50%。 7 8ArrayList和[Vector](js-apis-vector.md)相似，都是基于数组实现。它们都可以动态调整容量，但Vector每次扩容增加1倍。 9 10ArrayList和[LinkedList](js-apis-linkedlist.md)相比，ArrayList的随机访问效率更高。但由于ArrayList的增删操作会影响数组内其他元素的移动，LinkedList的增加和删除操作效率更高。 11 12**推荐使用场景：** 当需要频繁读取集合中的元素时，推荐使用ArrayList。 13 14文档中存在泛型的使用,涉及以下泛型标记符:<br> 15- T: Type, 类 16 17## 导入模块 18 19```ts 20import ArrayList from '@ohos.util.ArrayList'; 21``` 22 23## ArrayList 24 25### 属性 26 27**系统能力：** SystemCapability.Utils.Lang 28 29| 名称 | 类型 | 可读 | 可写 | 说明 | 30| -------- | -------- | -------- | -------- | -------- | 31| length | number | 是 | 否 | ArrayList的元素个数。 | 32 33 34### constructor 35 36constructor() 37 38ArrayList的构造函数。 39 40**系统能力：** SystemCapability.Utils.Lang 41 42**错误码：** 43 44以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 45 46| 错误码ID | 错误信息 | 47| -------- | -------- | 48| 10200012 | The ArrayList's constructor cannot be directly invoked. | 49 50**示例：** 51 52```ts 53let arrayList = new ArrayList(); 54``` 55 56 57### add 58 59add(element: T): boolean 60 61在ArrayList尾部插入元素。 62 63**系统能力：** SystemCapability.Utils.Lang 64 65**参数：** 66 67| 参数名 | 类型 | 必填 | 说明 | 68| -------- | -------- | -------- | -------- | 69| element | T | 是 | 待插入的元素。 | 70 71**返回值：** 72 73| 类型 | 说明 | 74| -------- | -------- | 75| boolean | 插入成功返回true，失败返回false。 | 76 77**错误码：** 78 79以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 80 81| 错误码ID | 错误信息 | 82| -------- | -------- | 83| 10200011 | The add method cannot be bound. | 84 85**示例：** 86 87```ts 88let arrayList = new ArrayList(); 89let result = arrayList.add("a"); 90let result1 = arrayList.add(1); 91let b = [1, 2, 3]; 92let result2 = arrayList.add(b); 93let c = {name: "Dylon", age: "13"}; 94let result3 = arrayList.add(c); 95let result4 = arrayList.add(false); 96``` 97 98### insert 99 100insert(element: T, index: number): void 101 102在长度范围内任意位置插入指定元素。 103 104**系统能力：** SystemCapability.Utils.Lang 105 106**参数：** 107 108| 参数名 | 类型 | 必填 | 说明 | 109| -------- | -------- | -------- | -------- | 110| element | T | 是 | 被插入的元素。 | 111| index | number | 是 | 被插入的位置索引。 | 112 113**错误码：** 114 115以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 116 117| 错误码ID | 错误信息 | 118| -------- | -------- | 119| 10200011 | The insert method cannot be bound. | 120| 10200001 | The value of index is out of range. | 121 122**示例：** 123 124```ts 125let arrayList = new ArrayList(); 126arrayList.insert("A", 0); 127arrayList.insert(0, 1); 128arrayList.insert(true, 2); 129``` 130 131### has 132 133has(element: T): boolean 134 135判断此ArrayList中是否含有该指定元素。 136 137**系统能力：** SystemCapability.Utils.Lang 138 139**参数：** 140 141| 参数名 | 类型 | 必填 | 说明 | 142| -------- | -------- | -------- | -------- | 143| element | T | 是 | 指定元素。 | 144 145**返回值：** 146 147| 类型 | 说明 | 148| -------- | -------- | 149| boolean | 返回true表示包含指定元素，否则返回false。 | 150 151**错误码：** 152 153以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 154 155| 错误码ID | 错误信息 | 156| -------- | -------- | 157| 10200011 | The has method cannot be bound. | 158 159**示例：** 160 161```ts 162let arrayList = new ArrayList(); 163let result = arrayList.has("squirrel"); 164arrayList.add("squirrel"); 165let result1 = arrayList.has("squirrel"); 166``` 167 168### getIndexOf 169 170getIndexOf(element: T): number 171 172返回指定元素第一次出现时的下标值，查找失败返回-1。 173 174**系统能力：** SystemCapability.Utils.Lang 175 176**参数：** 177 178| 参数名 | 类型 | 必填 | 说明 | 179| -------- | -------- | -------- | -------- | 180| element | T | 是 | 指定元素。 | 181 182**返回值：** 183 184| 类型 | 说明 | 185| -------- | -------- | 186| number | 返回指定元素第一次出现时的下标值，查找失败返回-1。 | 187 188**错误码：** 189 190以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 191 192| 错误码ID | 错误信息 | 193| -------- | -------- | 194| 10200011 | The getIndexOf method cannot be bound. | 195 196**示例：** 197 198```ts 199let arrayList = new ArrayList(); 200arrayList.add(2); 201arrayList.add(4); 202arrayList.add(5); 203arrayList.add(2); 204arrayList.add(1); 205arrayList.add(2); 206arrayList.add(4); 207let result = arrayList.getIndexOf(2); 208``` 209 210### getLastIndexOf 211 212getLastIndexOf(element: T): number 213 214返回指定元素最后一次出现时的下标值，查找失败返回-1。 215 216**系统能力：** SystemCapability.Utils.Lang 217 218**参数：** 219 220| 参数名 | 类型 | 必填 | 说明 | 221| -------- | -------- | -------- | -------- | 222| element | T | 是 | 指定元素。 | 223 224**返回值：** 225 226| 类型 | 说明 | 227| -------- | -------- | 228| number | 返回指定元素最后一次出现时的下标值，查找失败返回-1。 | 229 230**错误码：** 231 232以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 233 234| 错误码ID | 错误信息 | 235| -------- | -------- | 236| 10200011 | The getLastIndexOf method cannot be bound. | 237 238**示例：** 239 240```ts 241let arrayList = new ArrayList(); 242arrayList.add(2); 243arrayList.add(4); 244arrayList.add(5); 245arrayList.add(2); 246arrayList.add(1); 247arrayList.add(2); 248arrayList.add(4); 249let result = arrayList.getLastIndexOf(2); 250``` 251 252### removeByIndex 253 254removeByIndex(index: number): T 255 256根据元素的下标值查找元素，返回元素后将其删除。 257 258**系统能力：** SystemCapability.Utils.Lang 259 260**参数：** 261 262| 参数名 | 类型 | 必填 | 说明 | 263| -------- | -------- | -------- | -------- | 264| index | number | 是 | 指定元素的下标值。 | 265 266**返回值：** 267 268| 类型 | 说明 | 269| -------- | -------- | 270| T | 返回删除的元素。 | 271 272**错误码：** 273 274以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 275 276| 错误码ID | 错误信息 | 277| -------- | -------- | 278| 10200011 | The removeByIndex method cannot be bound. | 279| 10200001 | The value of index is out of range. | 280 281**示例：** 282 283```ts 284let arrayList = new ArrayList(); 285arrayList.add(2); 286arrayList.add(4); 287arrayList.add(5); 288arrayList.add(2); 289arrayList.add(4); 290let result = arrayList.removeByIndex(2); 291``` 292 293### remove 294 295remove(element: T): boolean 296 297删除查找到的第一个指定的元素。 298 299**系统能力：** SystemCapability.Utils.Lang 300 301**参数：** 302 303| 参数名 | 类型 | 必填 | 说明 | 304| -------- | -------- | -------- | -------- | 305| element | T | 是 | 指定元素。 | 306 307**返回值：** 308 309| 类型 | 说明 | 310| -------- | -------- | 311| boolean | 删除成功返回true，失败返回false。 | 312 313**错误码：** 314 315以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 316 317| 错误码ID | 错误信息 | 318| -------- | -------- | 319| 10200011 | The remove method cannot be bound. | 320 321**示例：** 322 323```ts 324let arrayList = new ArrayList(); 325arrayList.add(2); 326arrayList.add(4); 327arrayList.add(5); 328arrayList.add(4); 329let result = arrayList.remove(2); 330``` 331 332### removeByRange 333 334removeByRange(fromIndex: number, toIndex: number): void 335 336从一段范围内删除元素，包括起始值但不包括终止值。 337 338**系统能力：** SystemCapability.Utils.Lang 339 340**参数：** 341 342| 参数名 | 类型 | 必填 | 说明 | 343| -------- | -------- | -------- | -------- | 344| fromIndex | number | 是 | 起始下标。 | 345| toIndex | number | 是 | 终止下标。 | 346 347**错误码：** 348 349以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 350 351| 错误码ID | 错误信息 | 352| -------- | -------- | 353| 10200011 | The removeByRange method cannot be bound. | 354| 10200001 | The value of fromIndex or toIndex is out of range. | 355 356**示例：** 357 358```ts 359let arrayList = new ArrayList(); 360arrayList.add(2); 361arrayList.add(4); 362arrayList.add(5); 363arrayList.add(4); 364arrayList.removeByRange(2, 4); 365``` 366 367### replaceAllElements 368 369replaceAllElements(callbackFn: (value: T, index?: number, arrlist?: ArrayList<T>) => T, 370thisArg?: Object): void 371 372用户操作ArrayList中的元素，用操作后的元素替换原元素并返回操作后的元素。 373 374**系统能力：** SystemCapability.Utils.Lang 375 376**参数：** 377 378| 参数名 | 类型 | 必填 | 说明 | 379| -------- | -------- | -------- | -------- | 380| callbackFn | function | 是 | 回调函数。 | 381| thisArg | Object | 否 | callbackfn被调用时用作this值。 | 382 383callbackfn的参数说明： 384 385| 参数名 | 类型 | 必填 | 说明 | 386| -------- | -------- | -------- | -------- | 387| value | T | 是 | 当前遍历到的元素。 | 388| index | number | 否 | 当前遍历到的下标值。 | 389| arrlist | ArrayList<T> | 否 | 当前调用replaceAllElements方法的实例对象。 | 390 391**错误码：** 392 393以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 394 395| 错误码ID | 错误信息 | 396| -------- | -------- | 397| 10200011 | The replaceAllElements method cannot be bound. | 398 399**示例：** 400 401```ts 402let arrayList = new ArrayList(); 403arrayList.add(2); 404arrayList.add(4); 405arrayList.add(5); 406arrayList.add(4); 407arrayList.replaceAllElements((value) => { 408 // 用户操作逻辑根据实际场景进行添加。 409 return value; 410}); 411``` 412 413### forEach 414 415forEach(callbackFn: (value: T, index?: number, arrlist?: ArrayList<T>) => void, 416thisArg?: Object): void 417 418通过回调函数来遍历ArrayList实例对象上的元素以及元素对应的下标。 419 420**系统能力：** SystemCapability.Utils.Lang 421 422**参数：** 423 424| 参数名 | 类型 | 必填 | 说明 | 425| -------- | -------- | -------- | -------- | 426| callbackFn | function | 是 | 回调函数。 | 427| thisArg | Object | 否 | callbackfn被调用时用作this值。 | 428 429callbackfn的参数说明： 430 431| 参数名 | 类型 | 必填 | 说明 | 432| -------- | -------- | -------- | -------- | 433| value | T | 是 | 当前遍历到的元素。 | 434| index | number | 否 | 当前遍历到的下标值。 | 435| arrlist | ArrayList<T> | 否 | 当前调用forEach方法的实例对象。 | 436 437**错误码：** 438 439以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 440 441| 错误码ID | 错误信息 | 442| -------- | -------- | 443| 10200011 | The forEach method cannot be bound. | 444 445**示例：** 446 447```ts 448let arrayList = new ArrayList(); 449arrayList.add(2); 450arrayList.add(4); 451arrayList.add(5); 452arrayList.add(4); 453arrayList.forEach((value, index) => { 454 console.log("value:" + value, "index:" + index); 455}); 456``` 457 458### sort 459 460sort(comparator?: (firstValue: T, secondValue: T) => number): void 461 462对ArrayList中的元素排序。 463 464**系统能力：** SystemCapability.Utils.Lang 465 466**参数：** 467 468| 参数名 | 类型 | 必填 | 说明 | 469| -------- | -------- | -------- | -------- | 470| comparator | function | 否 | 回调函数。 | 471 472comparator的参数说明： 473 474| 参数名 | 类型 | 必填 | 说明 | 475| -------- | -------- | -------- | -------- | 476| firstValue | T | 是 | 前一项元素。 | 477| secondValue | T | 是 | 后一项元素。 | 478 479**错误码：** 480 481以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 482 483| 错误码ID | 错误信息 | 484| -------- | -------- | 485| 10200011 | The sort method cannot be bound. | 486 487**示例：** 488 489```ts 490let arrayList = new ArrayList(); 491arrayList.add(2); 492arrayList.add(4); 493arrayList.add(5); 494arrayList.add(4); 495arrayList.sort((a: number, b: number) => a - b); 496arrayList.sort((a: number, b: number) => b - a); 497arrayList.sort(); 498``` 499 500### subArrayList 501 502subArrayList(fromIndex: number, toIndex: number): ArrayList<T> 503 504根据下标截取ArrayList中的一段元素，并返回这一段ArrayList实例，包括起始值但不包括终止值。 505 506**系统能力：** SystemCapability.Utils.Lang 507 508**参数：** 509 510| 参数名 | 类型 | 必填 | 说明 | 511| -------- | -------- | -------- | -------- | 512| fromIndex | number | 是 | 起始下标。 | 513| toIndex | number | 是 | 终止下标。 | 514 515**返回值：** 516 517| 类型 | 说明 | 518| -------- | -------- | 519| ArrayList<T> | 返回ArrayList对象实例。 | 520 521**错误码：** 522 523以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 524 525| 错误码ID | 错误信息 | 526| -------- | -------- | 527| 10200011 | The subArrayList method cannot be bound. | 528| 10200001 | The value of fromIndex or toIndex is out of range. | 529 530**示例：** 531 532```ts 533let arrayList = new ArrayList(); 534arrayList.add(2); 535arrayList.add(4); 536arrayList.add(5); 537arrayList.add(4); 538let result1 = arrayList.subArrayList(2, 4); 539let result2 = arrayList.subArrayList(4, 3); 540let result3 = arrayList.subArrayList(2, 6); 541``` 542 543### clear 544 545clear(): void 546 547清除ArrayList中的所有元素，并把length置为0。 548 549**系统能力：** SystemCapability.Utils.Lang 550 551**错误码：** 552 553以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 554 555| 错误码ID | 错误信息 | 556| -------- | -------- | 557| 10200011 | The clear method cannot be bound. | 558 559**示例：** 560 561```ts 562let arrayList = new ArrayList(); 563arrayList.add(2); 564arrayList.add(4); 565arrayList.add(5); 566arrayList.add(4); 567arrayList.clear(); 568``` 569 570### clone 571 572clone(): ArrayList<T> 573 574克隆一个与ArrayList相同的实例，并返回克隆后的实例。修改克隆后的实例并不会影响原实例。 575 576**系统能力：** SystemCapability.Utils.Lang 577 578 579**返回值：** 580 581| 类型 | 说明 | 582| -------- | -------- | 583| ArrayList<T> | 返回ArrayList对象实例。 | 584 585**错误码：** 586 587以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 588 589| 错误码ID | 错误信息 | 590| -------- | -------- | 591| 10200011 | The clone method cannot be bound. | 592 593**示例：** 594 595```ts 596let arrayList = new ArrayList(); 597arrayList.add(2); 598arrayList.add(4); 599arrayList.add(5); 600arrayList.add(4); 601let result = arrayList.clone(); 602``` 603 604### getCapacity 605 606getCapacity(): number 607 608获取当前实例的容量大小。 609 610**系统能力：** SystemCapability.Utils.Lang 611 612**返回值：** 613 614| 类型 | 说明 | 615| -------- | -------- | 616| number | 返回arraylist的容量大小。 | 617 618**错误码：** 619 620以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 621 622| 错误码ID | 错误信息 | 623| -------- | -------- | 624| 10200011 | The getCapacity method cannot be bound. | 625 626**示例：** 627 628```ts 629let arrayList = new ArrayList(); 630arrayList.add(2); 631arrayList.add(4); 632arrayList.add(5); 633arrayList.add(4); 634let result = arrayList.getCapacity(); 635``` 636 637### convertToArray 638 639convertToArray(): Array<T> 640 641把当前ArrayList实例转换成数组，并返回转换后的数组。 642 643**系统能力：** SystemCapability.Utils.Lang 644 645**返回值：** 646 647| 类型 | 说明 | 648| -------- | -------- | 649| Array<T> | 返回数组类型。 | 650 651**错误码：** 652 653以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 654 655| 错误码ID | 错误信息 | 656| -------- | -------- | 657| 10200011 | The convertToArray method cannot be bound. | 658 659**示例：** 660 661```ts 662let arrayList = new ArrayList(); 663arrayList.add(2); 664arrayList.add(4); 665arrayList.add(5); 666arrayList.add(4); 667let result = arrayList.convertToArray(); 668``` 669 670### isEmpty 671 672isEmpty(): boolean 673 674判断该ArrayList是否为空。 675 676**系统能力：** SystemCapability.Utils.Lang 677 678**返回值：** 679 680| 类型 | 说明 | 681| -------- | -------- | 682| boolean | 为空返回true，不为空返回false。 | 683 684**错误码：** 685 686以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 687 688| 错误码ID | 错误信息 | 689| -------- | -------- | 690| 10200011 | The isEmpty method cannot be bound. | 691 692**示例：** 693 694```ts 695let arrayList = new ArrayList(); 696arrayList.add(2); 697arrayList.add(4); 698arrayList.add(5); 699arrayList.add(4); 700let result = arrayList.isEmpty(); 701``` 702 703### increaseCapacityTo 704 705increaseCapacityTo(newCapacity: number): void 706 707如果传入的新容量大于或等于ArrayList中的元素个数，将容量变更为新容量。 708 709**系统能力：** SystemCapability.Utils.Lang 710 711**参数：** 712 713| 参数名 | 类型 | 必填 | 说明 | 714| -------- | -------- | -------- | -------- | 715| newCapacity | number | 是 | 新容量。 | 716 717**错误码：** 718 719以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 720 721| 错误码ID | 错误信息 | 722| -------- | -------- | 723| 10200011 | The increaseCapacityTo method cannot be bound. | 724 725**示例：** 726 727```ts 728let arrayList = new ArrayList(); 729arrayList.add(2); 730arrayList.add(4); 731arrayList.add(5); 732arrayList.add(4); 733arrayList.increaseCapacityTo(2); 734arrayList.increaseCapacityTo(8); 735``` 736 737### trimToCurrentLength 738 739trimToCurrentLength(): void 740 741把容量限制为当前的length大小。 742 743**系统能力：** SystemCapability.Utils.Lang 744 745**错误码：** 746 747以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 748 749| 错误码ID | 错误信息 | 750| -------- | -------- | 751| 10200011 | The trimToCurrentLength method cannot be bound. | 752 753**示例：** 754 755```ts 756let arrayList = new ArrayList(); 757arrayList.add(2); 758arrayList.add(4); 759arrayList.add(5); 760arrayList.add(4); 761arrayList.trimToCurrentLength(); 762``` 763 764### [Symbol.iterator] 765 766[Symbol.iterator]\(): IterableIterator<T> 767 768返回一个迭代器，迭代器的每一项都是一个 JavaScript 对象，并返回该对象。 769 770**系统能力：** SystemCapability.Utils.Lang 771 772**返回值：** 773 774| 类型 | 说明 | 775| -------- | -------- | 776| IterableIterator<T> | 返回一个迭代器。 | 777 778**错误码：** 779 780以下错误码的详细介绍请参见[语言基础类库错误码](../errorcodes/errorcode-utils.md)。 781 782| 错误码ID | 错误信息 | 783| -------- | -------- | 784| 10200011 | The Symbol.iterator method cannot be bound. | 785 786**示例：** 787 788```ts 789let arrayList = new ArrayList(); 790arrayList.add(2); 791arrayList.add(4); 792arrayList.add(5); 793arrayList.add(4); 794 795// 使用方法一： 796for (let item of arrayList) { 797 console.log(`value:${item}`); 798} 799 800// 使用方法二： 801let iter = arrayList[Symbol.iterator](); 802let temp = iter.next().value; 803while(temp != undefined) { 804 console.log(`value:${temp}`); 805 temp = iter.next().value; 806} 807```
