@ohos.util.ArrayList (线性容器ArrayList)

ArrayList是一种线性数据结构，底层基于数组实现。ArrayList会根据实际需要动态调整容量，每次扩容增加50%。

ArrayList和LinkedList相比，ArrayList的随机访问效率更高。但由于ArrayList的增删操作可能需要对数组内其他元素进行移动，LinkedList的增加和删除操作效率更高。

推荐使用场景： 当需要频繁读取集合中的元素时，推荐使用ArrayList。

文档中使用了泛型，涉及以下泛型标记符：

T：Type，类

本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

容器类使用静态语言实现，限制了存储位置和属性，不支持自定义属性和方法。

导入模块

import { ArrayList } from '@kit.ArkTS';

ArrayList

属性

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

名称	类型	只读	可选	说明
length	number	是	否	ArrayList的元素个数。

constructor

constructor()

ArrayList的构造函数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200012	The ArrayList's constructor cannot be directly invoked.

示例：

let arrayList = new ArrayList<string | number>();

add

add(element: T): boolean

在ArrayList尾部插入元素。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
element	T	是	待插入的元素。

返回值：

类型	说明
boolean	插入成功返回true，失败返回false。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The add method cannot be bound.

示例：

class C1 {
  name: string = ""
  age: string = ""
}
let arrayList = new ArrayList<string | number | boolean | Array<number> | C1>();
arrayList.add("a");
arrayList.add(1);
let b = [1, 2, 3];
arrayList.add(b);
let c : C1 = {name: "Dylan", age: "13"}
let result1 = arrayList.add(c);
let result2 = arrayList.add(false);
console.info("result1:", result1);  // result1: true
console.info("result2:", result2);  // result2: true
console.info("length:", arrayList.length);  // length: 5

insert

insert(element: T, index: number): void

在长度范围内指定位置index插入元素element。如果index超出范围，则插入失败。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
element	T	是	被插入的元素。
index	number	是	被插入的位置索引。需要小于等于int32_max即2147483647。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200001	The value of index is out of range.
10200011	The insert method cannot be bound.

示例：

let arrayList = new ArrayList<number | string | boolean>();
arrayList.insert("A", 0);
arrayList.insert(0, 1);
arrayList.insert(true, 2);
console.info("length:", arrayList.length);  // length: 3

has

has(element: T): boolean

判断此ArrayList中是否包含该指定元素。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
element	T	是	指定元素。

返回值：

类型	说明
boolean	返回true表示包含指定元素，否则返回false。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The has method cannot be bound.

示例：

let arrayList = new ArrayList<string>();
arrayList.add("squirrel");
let result: boolean = arrayList.has("squirrel");
console.info("result:", result);  // result: true

getIndexOf

getIndexOf(element: T): number

返回指定元素第一次出现的下标，查找失败返回-1。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
element	T	是	指定元素。

返回值：

类型	说明
number	返回指定元素第一次出现时的下标值，查找失败返回-1。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The getIndexOf method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(2);
arrayList.add(1);
arrayList.add(2);
arrayList.add(4);
let result: number = arrayList.getIndexOf(2);
console.info("result = ", result); // result = 0

getLastIndexOf

getLastIndexOf(element: T): number

返回指定元素最后一次出现的下标，查找失败返回-1。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
element	T	是	指定元素。

返回值：

类型	说明
number	返回指定元素最后一次出现时的下标值，查找失败返回-1。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The getLastIndexOf method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(2);
arrayList.add(1);
arrayList.add(2);
arrayList.add(4);
let result: number = arrayList.getLastIndexOf(2);
console.info("result = ", result); // result = 5

removeByIndex

removeByIndex(index: number): T

根据元素的下标值查找元素，返回元素后将其删除。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
index	number	是	指定元素的下标值。需要小于等于int32_max即2147483647。

返回值：

类型	说明
T	返回删除的元素。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200001	The value of "index" is out of range.
10200011	The removeByIndex method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(2);
arrayList.add(4);
let result: number = arrayList.removeByIndex(2);
console.info("result = ", result); // result = 5

remove

remove(element: T): boolean

删除查找到的第一个指定元素。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
element	T	是	指定元素。

返回值：

类型	说明
boolean	删除成功返回true，失败返回false。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The remove method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
let result: boolean = arrayList.remove(2);
console.info("result = ", result); // result =  true

removeByRange

removeByRange(fromIndex: number, toIndex: number): void

删除指定范围内的元素，区间包含fromIndex，但不包含toIndex，即左闭右开区间[fromIndex, toIndex)。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
fromIndex	number	是	起始下标。
toIndex	number	是	终止下标。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200001	The value of fromIndex or toIndex is out of range.
10200011	The removeByRange method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
arrayList.removeByRange(2, 4);

replaceAllElements

replaceAllElements(callbackFn: (value: T, index?: number, arrlist?: ArrayList<T>) => T, thisArg?: Object): void

用户操作ArrayList中的元素，用操作后的元素替换原元素并返回操作后的元素。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
callbackFn	function	是	回调函数。
thisArg	Object	否	callbackFn被调用时用作this值，默认值为当前实例对象。

callbackFn的参数说明：

参数名	类型	必填	说明
value	T	是	当前遍历到的元素。
index	number	否	当前遍历到的下标值，默认值为0。
arrlist	ArrayList<T>	否	当前调用replaceAllElements方法的实例对象，默认值为当前实例对象。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
10200011	The replaceAllElements method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
arrayList.replaceAllElements((value: number): number => {
  // 用户操作逻辑根据实际场景进行添加。
  return value;
});

forEach

forEach(callbackFn: (value: T, index?: number, arrlist?: ArrayList<T>) => void, thisArg?: Object): void

在遍历ArrayList实例对象的过程中，对每个元素执行回调函数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
callbackFn	function	是	回调函数。
thisArg	Object	否	callbackFn被调用时用作this值，默认值为undefined。

callbackFn的参数说明：

参数名	类型	必填	说明
value	T	是	当前遍历到的元素。
index	number	否	当前遍历到的下标值，默认值为0。
arrlist	ArrayList<T>	否	当前调用forEach方法的实例对象，默认值为当前实例对象。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
10200011	The forEach method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
arrayList.forEach((value: number, index?: number) => {
  console.info("value:" + value, "index:" + index);
});
// value:2 index:0
// value:4 index:1
// value:5 index:2
// value:4 index:3

sort

sort(comparator?: ArrayListComparatorFn<T>): void

根据指定比较器所定义的顺序，对ArrayList中的元素进行排序。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
comparator	ArrayListComparatorFn<T>	否	回调函数，默认为升序排序的回调函数。 API version23开始发生兼容性变更，在API version22及之前的版本其类型为：(firstValue: T, secondValue: T) => number。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Incorrect parameter types; 2. Parameter verification failed.
10200011	The sort method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
arrayList.sort((a: number, b: number) => a - b);
arrayList.sort((a: number, b: number) => b - a);
arrayList.sort();

subArrayList

subArrayList(fromIndex: number, toIndex: number): ArrayList<T>

根据下标截取ArrayList中的一段元素，并返回这一段ArrayList实例，区间包含fromIndex，但不包含toIndex，即左闭右开区间[fromIndex, toIndex)。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
fromIndex	number	是	起始下标。
toIndex	number	是	终止下标。

返回值：

类型	说明
ArrayList<T>	返回ArrayList对象实例。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
10200001	The value of fromIndex or toIndex is out of range.
10200011	The subArrayList method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
let result: ArrayList<number> = arrayList.subArrayList(2, 4);
console.info("result = ", result.length); // result = 2

clear

clear(): void

清除ArrayList中的所有元素，并把length置为0。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The clear method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
arrayList.clear();

clone

clone(): ArrayList<T>

克隆一个与ArrayList相同的实例，并返回克隆后的实例。修改克隆后的实例并不会影响原实例。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
ArrayList<T>	返回ArrayList对象实例。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The clone method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
let result:  ArrayList<number> = arrayList.clone();
console.info("result = ", result.length); // result = 4

getCapacity

getCapacity(): number

获取当前实例的容量大小。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
number	获取当前实例的容量大小。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The getCapacity method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
let result: number = arrayList.getCapacity();
console.info("result = ", result); // result = 10

convertToArray

convertToArray(): Array<T>

把当前ArrayList实例转换成数组，并返回转换后的数组。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
Array<T>	返回数组类型。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The convertToArray method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
let result: Array<number> = arrayList.convertToArray();
console.info("result = ", result); // result =  2,4,5,4

isEmpty

isEmpty(): boolean

判断该ArrayList是否为空。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
boolean	为空返回true，不为空返回false。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The isEmpty method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
let result: boolean = arrayList.isEmpty();
console.info("result = ", result); // result =  false

index: number12+

获取指定索引值对应位置的元素。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
index	number	是	元素的位置索引。需要小于等于int32_max即2147483647。

返回值：

类型	说明
T	容器中对应索引值为index的元素。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error.
10200001	The value of index is out of range.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
let result: number = arrayList[2];
console.info("result = ", result); // result =  5

increaseCapacityTo

increaseCapacityTo(newCapacity: number): void

如果传入的新容量大于或等于ArrayList中的元素个数，将容量变更为新容量。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
newCapacity	number	是	新容量。

错误码：

以下错误码的详细介绍请参见通用错误码和语言基础类库错误码。

错误码ID	错误信息
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
10200011	The increaseCapacityTo method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
arrayList.increaseCapacityTo(2);
arrayList.increaseCapacityTo(8);
console.info("result = ", arrayList.length); // result = 4

trimToCurrentLength

trimToCurrentLength(): void

释放ArrayList中预留的空间，把容量调整为当前的元素个数。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The trimToCurrentLength method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);
arrayList.trimToCurrentLength();
console.info("result = ", arrayList.length); // result = 4

[Symbol.iterator]

Symbol.iterator: IterableIterator<T>

返回一个迭代器，每一项都是一个JavaScript对象。

元服务API： 从API version 12开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
IterableIterator<T>	返回一个迭代器。

错误码：

以下错误码的详细介绍请参见语言基础类库错误码。

错误码ID	错误信息
10200011	The Symbol.iterator method cannot be bound.

示例：

let arrayList = new ArrayList<number>();
arrayList.add(2);
arrayList.add(4);
arrayList.add(5);
arrayList.add(4);

// 使用方法一：
for (let value of arrayList) {
  console.info("value:", value);
}
// value: 2
// value: 4
// value: 5
// value: 4

// 使用方法二：
let iter = arrayList[Symbol.iterator]();
let temp: IteratorResult<number> = iter.next();
while(!temp.done) {
  console.info("value:", temp.value);
  temp = iter.next();
}
// value: 2
// value: 4
// value: 5
// value: 4

ArrayListComparatorFn<T>23+

type ArrayListComparatorFn<T> = (firstValue: T, secondValue: T) => number

ArrayList中sort方法的回调函数。

元服务API： 从API version 23开始，该接口支持在元服务中使用。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
firstValue	T	是	需要排序的前一项元素。
secondValue	T	是	需要排序的后一项元素。

返回值：

类型	说明
number	通过回调函数返回的值，ArrayList能够根据自定义的比较规则维护元素的顺序。

导入模块​

ArrayList​

属性​

constructor​

add​

insert​

has​

getIndexOf​

getLastIndexOf​

removeByIndex​

remove​

removeByRange​

replaceAllElements​

forEach​

sort​

subArrayList​

clear​

clone​

getCapacity​

convertToArray​

isEmpty​

index: number12+​

increaseCapacityTo​

trimToCurrentLength​

[Symbol.iterator]​

ArrayListComparatorFn<T>23+​

导入模块

ArrayList

属性

constructor

add

insert

has

getIndexOf

getLastIndexOf

removeByIndex

remove

removeByRange

replaceAllElements

forEach

sort

subArrayList

clear

clone

getCapacity

convertToArray

isEmpty

index: number12+

increaseCapacityTo

trimToCurrentLength

[Symbol.iterator]

ArrayListComparatorFn<T>23+