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