【HarmonyOS NEXT】鸿蒙线程安全容器集collections.Array

导入模块

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

ISendable

type ISendable = lang.ISendable

ISendable是所有Sendable类型（除null和undefined）的父类型。自身没有任何必须的方法和属性。

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

系统能力： SystemCapability.Utils.Lang

类型	说明
lang.ISendable	所有Sendable类型的父类型。

collections.ConcatArray

表示可以进行连接的类似数组的对象。该接口扩展了ISendable接口。

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

• T：Type，支持Sendable的数据类型。

属性

系统能力： SystemCapability.Utils.Lang

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

join

join(separator?: string): string

将ConcatArray的所有元素连接成一个字符串，元素之间可以用指定的分隔符分隔。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
separator	string	否	用于分隔ConcatArray元素的字符串。如果省略，则使用逗号分隔。

返回值：

类型	说明
string	包含所有ConcatArray元素连接成的字符串。如果ConcatArray为空，则返回空字符串。

错误码：

错误码ID	错误信息
401	Parameter error. Invalid separator.

示例：

let concatArray : collections.ConcatArray<string> = new collections.Array<string>('a', 'b', 'c');
let joinedString = concatArray.join('-'); // 返回 "a-b-c"

slice

slice(start?: number, end?: number): ConcatArray<T>

返回一个新的ConcatArray，该ConcatArray是原始ConcatArray的切片。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
start	number	否	开始索引。如果start < 0，则会从start + array.length位置开始。默认值为0。
end	number	否	结束索引（不包括该元素）。如果end < 0，则会到end + array.length位置结束。默认为ArkTS Array的长度。

返回值：

类型	说明
ConcatArray<T>	包含原始ConcatArray切片的新ConcatArray。

错误码：

错误码ID	错误信息
401	Parameter error. Invalid start or end parameters.

示例：

let concatArray : collections.ConcatArray<number> = new collections.Array<number>(1, 2, 3, 4, 5);
let slicedArray = concatArray.slice(1, 3); // 返回[2, 3]，原Array保持不变

collections.Array

一种线性数据结构，底层基于数组实现，可以在ArkTS上并发实例间传递。

当需要在ArkTS上并发实例间传递Array时，可以通过传递Array引用提升传递性能。

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

• T：Type，支持Sendable的数据类型。

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

属性

系统能力： SystemCapability.Utils.Lang

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

constructor

构造函数

constructor()

创建一个ArkTS Array的构造函数。

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

系统能力： SystemCapability.Utils.Lang

错误码：

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

示例：

1. let array = new collections.Array<number>();

constructor

constructor(first: T, ...left: T[])

ArkTS Array的构造函数，通过开发者提供的元素进行初始化。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
first	T	是	初始化ArkTS Array的第一个元素。
left	T[]	否	初始化ArkTS Array的剩余元素。

错误码：

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

示例：

let array = new collections.Array<number>(1, 2, 3, 4);

create

static create<T>(arrayLength: number, initialValue: T): Array<T>

生成一个固定长度的Array，其中，每个元素的初始值为initialValue。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
arrayLength	number	是	用于构造ArkTS Array的长度。
initialValue	T	是	用于填充ArkTS Array的值。

返回值：

类型	说明
Array<T>	新创建的ArkTS Array实例。

错误码：

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

示例：

let array = collections.Array.create<number>(3, 10); // [10, 10, 10]

from

static from<T>(arrayLike: ArrayLike<T>): Array<T>

从一个实现了ArrayLike接口的对象创建一个新的ArkTS Array。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
arrayLike	ArrayLike<T>	是	用于构造ArkTS Array的对象。

返回值：

类型	说明
Array<T>	新创建的ArkTS Array实例。

错误码：

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

示例：

// 正例
let array : Array<string> = ['str1', 'str2', 'str3']; // 原生Array<T>，T是Sendable数据类型。
let sendableArray = collections.Array.from<string>(array); // 返回Sendable Array<T>

// 反例
let array : Array<Array<string>> = [['str1', 'str2', 'str3'], ['str4', 'str5', 'str6'], ['str7', 'str8', 'str9']]; // 原生Array<T>，T是非Sendable数据类型。
let sendableArray = collections.Array.from<Array<string>>(array); // 打印异常信息：Parameter error.Only accept sendable value

pop

pop(): T | undefined

从ArkTS Array中移除并返回最后一个元素。如果Array为空，则返回undefined，且Array不发生变化。

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

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
T | undefined	从Array中移除的元素；如果Array为空，则返回undefined。

错误码：

错误码ID	错误信息
10200011	The pop method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3);
let lastElement = array.pop(); // 返回3，Array变为[1, 2]

push

push(...items: T[]): number

在ArkTS Array的末尾添加一个或多个元素，并返回新的Array长度。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
items	T[]	是	要添加到Array末尾的一个或多个元素。

返回值：

类型	说明
number	返回新Array的长度。

错误码：

错误码ID	错误信息
10200011	The push method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3);
let length = array.push(4, 5); // 返回5，Array变为[1, 2, 3, 4, 5]

join

join(separator?: string): string

将ArkTS Array的所有元素连接成一个字符串，元素之间可以用指定的分隔符分隔。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
separator	string	否	用于分隔Array元素的字符串。如果省略，则使用逗号分隔。

返回值：

类型	说明
string	包含所有Array元素连接成的字符串。如果Array为空，则返回空字符串。

错误码：

错误码ID	错误信息
10200011	The join method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<string>('a', 'b', 'c');
let joinedString = array.join('-'); // 返回 "a-b-c"

shift

shift(): T | undefined

从ArkTS Array中移除并返回第一个元素。如果Array为空，则返回undefined，且Array不发生变化。

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

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
T | undefined	从Array中移除的元素；如果Array为空，则返回undefined。

错误码：

错误码ID	错误信息
10200011	The shift method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3);
let firstElement = array.shift(); // 返回1，Array变为[2, 3]

unshift

unshift(...items: T[]): number

在ArkTS Array的首端插入一个或多个元素，并返回新的Array长度。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
items	T[]	是	要插入到Array首端的元素。

返回值：

类型	说明
number	新Array的长度。

错误码：

错误码ID	错误信息
10200011	The unshift method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3);
let newLength = array.unshift(0); // 返回4，Array变为[0, 1, 2, 3]

slice

slice(start?: number, end?: number): Array<T>

返回一个新的Array，该Array是原始ArkTS Array的切片。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
start	number	否	开始索引。如果start < 0，则会从start + array.length位置开始。默认值为0。
end	number	否	结束索引（不包括该元素）。如果end < 0，则会到end + array.length位置结束。默认为ArkTS Array的长度。

返回值：

类型	说明
Array<T>	包含原始Array切片的新Array。

错误码：

错误码ID	错误信息
10200011	The slice method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3, 4, 5);
let slicedArray = array.slice(1, 3); // 返回[2, 3]，Array保持不变

sort

sort(compareFn?: (a: T, b: T) => number): Array<T>

对ArkTS Array进行排序，并返回排序后的Array。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
compareFn	(a: T, b: T) => number	否	用于确定元素顺序的函数。默认使用升序排序。

返回值：

类型	说明
Array<T>	排序后的Array。

错误码：

错误码ID	错误信息
10200011	The sort method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 3, 5, 4, 2);
array.sort((a: number, b: number) => a - b); // [1, 2, 3, 4, 5]
array.sort((a: number, b: number) => b - a); // [5, 4, 3, 2, 1]

indexOf

indexOf(searchElement: T, fromIndex?: number): number

返回在ArkTS Array中搜索元素首次出现的索引，如果不存在则返回-1。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
searchElement	T	是	要搜索的值。
fromIndex	number	否	开始搜索的索引。默认值为0。

返回值：

类型	说明
number	搜索元素首次出现的索引；如果不存在，则返回-1。

错误码：

错误码ID	错误信息
10200011	The indexOf method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<string>('a', 'b', 'c');
let index = array.indexOf('b'); // 返回1，因为'b'在索引1的位置

forEach

forEach(callbackFn: (value: T, index: number, array: Array<T>) => void): void

对Array中的每个元素执行提供的回调函数。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
callbackFn	(value: T, index: number, array: Array<T>) => void	是	用于对每个元素执行的回调函数。

错误码：

错误码ID	错误信息
10200011	The forEach method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<string>('a', 'b', 'c');
array.forEach((value, index, array) => {
console.info(`Element ${value} at index ${index}`);
});

map

map<U>(callbackFn: (value: T, index: number, array: Array<T>) => U): Array<U>

对Array中的每个元素执行提供的回调函数，并返回一个新的Array，该Array包含回调函数的结果。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
callbackFn	(value: T, index: number, array: Array<T>) => U	是	用于对每个元素执行的回调函数。

返回值：

类型	说明
Array<U>	包含回调函数结果的新Array。

错误码：

错误码ID	错误信息
10200011	The map method cannot be bound.
10200201	Concurrent modification error.

示例：

// 此处将原始Array中的每个字符串元素转换为大写形式，并返回一个新Array，其中包含转换后的字符串
let array = new collections.Array<string>('a', 'b', 'c');
let mappedArray = array.map((value, index, array) => {
return value.toUpperCase(); // 将每个字符串元素转换为大写
});
console.info("" + mappedArray); // 输出: ['A', 'B', 'C']

filter

filter(predicate: (value: T, index: number, array: Array<T>) => boolean): Array<T>

返回一个新Array，其中包含通过指定回调函数测试的所有元素。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
predicate	(value: T, index: number, array: Array<T>) => boolean	是	一个接受三个参数的函数，用于测试每个元素是否应该包含在新Array中。

返回值：

类型	说明
Array<T>	包含通过测试的元素的新Array。

错误码：

错误码ID	错误信息
10200011	The filter method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3, 4, 5);
let filteredArray = array.filter((value : number) => value % 2 === 0); // 返回[2, 4]，只包含偶数

reduce

reduce(callbackFn: (previousValue: T, currentValue: T, currentIndex: number, array: Array<T>) => T): T

对Array中的每个元素执行回调函数，将其结果作为累加值，并返回最终的结果。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
callbackFn	(previousValue: T, currentValue: T, currentIndex: number, array: Array<T>) => T	是	一个接受四个参数的函数，用于对每个元素执行操作，并将结果作为累加值传递给下一个元素。

返回值：

类型	说明
T	回调函数执行后的最终结果。

错误码：

错误码ID	错误信息
10200011	The reduce method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3, 4, 5);
let reducedValue = array.reduce((accumulator, value) => accumulator + value); // 返回15，累加所有元素

reduce

reduce<U>(callbackFn: (previousValue: U, currentValue: T, currentIndex: number, array: Array<T>) => U, initialValue: U): U

与 reduce方法类似，但它接受一个初始值作为第二个参数，用于在Array遍历开始前初始化累加器。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
callbackFn	callbackFn: (previousValue: U, currentValue: T, currentIndex: number, array: Array<T>) => U	是	一个接受四个参数的函数，用于对每个元素执行操作，并将结果作为累加值传递给下一个元素。
initialValue	U	是	用于初始化累加器的值。

返回值：

类型	说明
U	回调函数执行后的最终结果。

错误码：

错误码ID	错误信息
10200011	The reduce method cannot be bound.
10200201	Concurrent modification error.

示例：

// 此处使用一个初始值为0的累加器，并将其与Array中的每个元素相加，最终返回累加后的总和
let array = new collections.Array(1, 2, 3, 4, 5);
let reducedValue = array.reduce<number>((accumulator: number, value: number) => accumulator + value, 0); // 返回15，累加所有元素，初始值为0

at

at(index: number): T | undefined

返回Array中指定索引位置的元素。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
index	number	是	要返回的Array元素的索引（从零开始），取值为整数。负数索引从Array末尾开始计数，如果index < 0，则会访问index + array.length位置的元素。

返回值：

类型	说明
T | undefined	返回指定索引处的元素；如果索引超出范围或无效，则返回undefined。

错误码：

错误码ID	错误信息
10200011	The at method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3, 4, 5);
let elementAtIndex = array.at(2); // 返回3，因为索引是从0开始的

entries

entries(): IterableIterator<[number, T]>

返回一个新的可迭代对象，该对象包含Array中每个元素的键值对。

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

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
IterableIterator<[number, T]>	包含Array中每个元素的键值对的迭代器。

错误码：

错误码ID	错误信息
10200011	The entries method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3, 4, 5);
let iterator = array.entries();
console.info(iterator.next().value); // 输出：[0, 1]，第一个元素的键值对

keys

keys(): IterableIterator<number>

返回一个新的可迭代对象，该对象包含Array中每个元素的键。

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

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
IterableIterator<number>	包含Array中每个元素的键的可迭代迭代器。

错误码：

错误码ID	错误信息
10200011	The keys method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3, 4, 5);
let iterator = array.keys();
for (const key of iterator) {
console.info("" + key); // 依次输出 0,1,2,3,4
}

values

values(): IterableIterator<T>

返回一个新的可迭代对象，该对象包含Array中每个元素的值。

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

系统能力： SystemCapability.Utils.Lang

返回值：

类型	说明
IterableIterator<T>	包含Array中每个元素的值的可迭代迭代器。

错误码：

错误码ID	错误信息
10200011	The values method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3, 4, 5);
let iterator = array.values();
for(const value of iterator) {
console.info("" + value); // 依次输出 1,2,3,4,5
}

find

find(predicate: (value: T, index: number, obj: Array<T>) => boolean): T | undefined

返回Array中第一个满足指定测试函数的元素的值，如果所有元素都不满足，则返回undefined。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
predicate	(value: T, index: number, obj: Array<T>) => boolean	是	一个接受三个参数的函数，用于测试每个元素是否满足条件。

返回值：

类型	说明
T | undefined	第一个满足条件的元素的值；如果所有元素都不满足条件，则返回undefined。

错误码：

错误码ID	错误信息
10200011	The find method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3, 4, 5);
let foundValue = array.find((value: number) => value % 2 === 0); // 返回2，第一个偶数元素

includes

includes(searchElement: T, fromIndex?: number): boolean

判断Array是否包含指定的元素，并返回一个布尔值。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
searchElement	T	是	要搜索的元素。
fromIndex	number	否	开始搜索的索引。默认值为0。

返回值：

类型	说明
boolean	如果Array包含指定的元素，则返回true；否则返回false。

错误码：

错误码ID	错误信息
10200011	The includes method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3, 4, 5);
let includesResult = array.includes(3); // 返回true，因为Array中包含3

findIndex

findIndex(predicate: (value: T, index: number, obj: Array<T>) => boolean): number

返回Array中第一个满足指定测试函数的元素的索引，如果所有元素都不满足，则返回-1。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
predicate	(value: T, index: number, obj: Array<T>) => boolean	是	一个接受三个参数的函数，用于测试每个元素是否满足条件。

返回值：

类型	说明
number	第一个满足条件的元素的索引；如果所有元素都不满足条件，则返回-1。

错误码：

错误码ID	错误信息
10200011	The findIndex method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array<number>(1, 2, 3, 4, 5);
let foundIndex = array.findIndex((value: number) => value % 2 === 0); // 返回1，因为2是第一个偶数元素

fill

fill(value: T, start?: number, end?: number): Array<T>

使用指定的值填充Array中指定范围的所有元素。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
value	T	是	要填充的值。
start	number	否	开始填充的索引。默认值为0。
end	number	否	结束填充的索引。如果省略，则填充到Array的最后一个元素。

返回值：

类型	说明
Array<T>	填充后的Array。

错误码：

错误码ID	错误信息
10200011	The fill method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array(1, 2, 3, 4, 5);
array.fill(0, 1, 3); // 返回[1, 0, 0, 4, 5]，因为1到3的索引范围内的元素被替换为0

shrinkTo

shrinkTo(arrayLength: number): void

使Array收缩到指定长度。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
arrayLength	number	是	Array的新长度。如果arrayLength >= array.length，则Array不变。

错误码：

错误码ID	错误信息
10200011	The shrinkTo method cannot be bound.
10200201	Concurrent modification error.

示例：

let array1 = new collections.Array(1, 2, 3, 4, 5);
array1.shrinkTo(1); // array内容变为：[1]

let array2 = new collections.Array(1, 2, 3, 4, 5);
array2.shrinkTo(10); // array内容不变

extendTo

extendTo(arrayLength: number, initialValue: T): void

使Array扩展到指定长度，扩展的部分使用给定值填充。

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

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
arrayLength	number	是	Array的新长度。如果arrayLength <= array.length，则Array不变。
initialValue	T	是	扩展的部分的填充值。

错误码：

错误码ID	错误信息
10200011	The extendTo method cannot be bound.
10200201	Concurrent modification error.

示例：

let array1 = new collections.Array(1, 2, 3);
array1.extendTo(5, 10); // array内容变为：[1, 2, 3, 10, 10]

let array2 = new collections.Array(1, 2, 3);
array2.extendTo(1, 10); // array内容不变

concat

concat(...items: ConcatArray<T>[]): Array<T>

拼接两个或多个数组。

系统能力： SystemCapability.Utils.Lang

参数：

参数名	类型	必填	说明
items	ConcatArray<T>[]	是	拼接两个或多个数组。

返回值：

类型	说明
Array<T>	拼接后的数组。

错误码：

错误码ID	错误信息
401	Parameter error. Not a valid array.
10200011	The concat method cannot be bound.
10200201	Concurrent modification error.

示例：

let array = new collections.Array(1, 2, 3);
let array1 = new collections.Array(4, 5, 6);
let array2 = new collections.Array(7, 8, 9);

let concatArray = array.concat(array1, array2); // concatArray的内容为：[1, 2, 3, 4, 5, 6, 7, 8, 9]