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