openharmony 鸿蒙 arkts-collections-introduction

2025-06-12 浏览 (1)

共享容器

ArkTS容器集

ArkTS共享容器（@arkts.collections (ArkTS容器集)）是一种在并发实例间共享传输的容器类，可以用于并发场景下的高性能数据传递。功能与Ecmascript262规范定义的容器类似，但仍然有部分差异，具体可见共享容器与原生API方法的行为差异对比。

ArkTS共享容器在多个并发实例间传递时，默认采用引用传递，允许多个并发实例操作同一个容器实例。此外，还支持拷贝传递，即每个并发实例拥有一个独立的ArkTS容器实例。

ArkTS共享容器不是线程安全的，内部使用了fail-fast（快速失败）机制，即当检测到多个并发实例同时对容器进行结构性修改时，会触发异常。因此，在多线程场景下修改容器内属性时，开发者需要使用ArkTS提供的异步锁机制保证ArkTS容器的安全访问。

ArkTS共享容器包含如下几种：Array、Map、Set、TypedArray（Int8Array、Uint8Array、Int16Array、Uint16Array、Int32Array、Uint32Array、Uint8ClampedArray、Float32Array）、ArrayBuffer等，具体可见@arkts.collections (ArkTS容器集)。

容器集使用示例如下：

import { ArkTSUtils, collections, taskpool } from '@kit.ArkTS';

@Concurrent
async function add(arr: collections.Array<number>, lock: ArkTSUtils.locks.AsyncLock) {
 await lock.lockAsync(() => {  // 如果不添加异步锁，任务会因为数据竞争冲突，导致抛异常失败
   arr[0]++;
 })
}

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    RelativeContainer() {
      Text(this.message)
        .id('HelloWorld')
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
        .alignRules({
          center: { anchor: '__container__', align: VerticalAlign.Center },
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
        })
        .onClick(() => {
          let taskGroup = new taskpool.TaskGroup();
          let lock = new ArkTSUtils.locks.AsyncLock();
          let arr = collections.Array.create<number>(1, 0);
          let count = 1000;
          while (count--) {
            taskGroup.addTask(add, arr, lock);
          }
          taskpool.execute(taskGroup).then(() => {
            console.info(`Return success: ${arr[0]} === ${count}`);
          }).catch((e: Error) => {
            console.error("Return error.");
          })
        })
    }
    .height('100%')
    .width('100%')
  }
}

共享容器与原生API方法的行为差异对比

ArkTS提供了Sendable数据相关的共享容器集，接口行为与原生API存在部分差异，具体可见下文对比。

说明：

ArkTS共享容器的类型与Ecmascript262规范定义的原生容器的类型不同，因此使用原生容器Array的isArray()方法判断collections.Array实例对象会返回false。

ArkTS共享容器跨线程传递采用引用传递方式，与原生容器相比效率更高，如果开发者需要跨线程传输的数据量很大，建议使用ArkTS共享容器。

Array

支持原生容器Array通过collections.Array.from方法转换为ArkTS Array容器；支持通过原生容器Array的from方法将ArkTS Array容器转换为原生容器Array。

原生API方法ArkTS容器集方法是否有行为差异在ArkTS容器中的差异表现
length: numberreadonly length: number是为了防止undefined扩散，不允许设置length。
new(arrayLength ?: number): any[]static create(arrayLength: number, initialValue: T): Array是为了防止undefined扩散，构造函数中必须提供一个初始值。
new <T>(arrayLength: number): T[]constructor()否/
new <T>(...items: T[]): T[]constructor(first: T, ...left: T[])是为了防止undefined扩散，构造函数中必须提供一个初始值，继承场景下，无法调用该函数进行对象构造。
from<T>(arrayLike: ArrayLike<T>): T[]static from<T>(arrayLike: ArrayLike<T>): Array<T>否/
from<T, U>(iterable: Iterable<T> |ArrayLike<T>, mapfn: (v: T, k: number) => U, thisArg?: any): U[]static from<U, T>(arrayLike: ArrayLike<U> |Iterable<U>, mapFn: ArrayFromMapFn<U, T>): Array<T>否/
pop(): T |undefinedpop(): T |undefined是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
push(...items: T[]): numberpush(...items: T[]): number是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
concat(...items: ConcatArray<T>[]): T[]concat(...items: ConcatArray<T>[]): Array<T>是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
concat(...items: (T |ConcatArray<T>)[]): T[]concat(...items: ConcatArray<T>[]): Array<T>是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
join(separator?: string): stringjoin(separator?: string): string否/
shift(): T |undefinedshift(): T |undefined是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
slice(start?: number, end?: number): T[]slice(start?: number, end?: number): Array<T>否/
sort(compareFn?: (a: T, b: T) => number): thissort(compareFn?: (a: T, b: T) => number): Array<T>是1. 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
2. 继承场景下，无法获得实际类型的返回值。
unshift(...items: T[]): numberunshift(...items: T[]): number是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
indexOf(searchElement: T, fromIndex?: number): numberindexOf(searchElement: T, fromIndex?: number): number否/
forEach(callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any): voidforEach(callbackFn: (value: T, index: number, array: Array<T>) => void): void是ArkTS不支持this，因此不支持thisArg参数。
map<U>(callbackfn: (value: T, index: number, array: T[]) => U, thisArg?: any): U[]map<U>(callbackFn: (value: T, index: number, array: Array<T>) => U): Array<U>是ArkTS不支持this，因此不支持thisArg参数。
filter(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): T[]filter(predicate: (value: T, index: number, array: Array<T>) => boolean): Array<T>是ArkTS不支持this，因此不支持thisArg参数。
reduce(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): Treduce(callbackFn: (previousValue: T, currentValue: T, currentIndex: number, array: Array<T>) => T): T否/
reduce<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): Ureduce<U>(callbackFn: (previousValue: U, currentValue: T, currentIndex: number, array: Array<T>) => U, initialValue: U): U否/
[n: number]: T[index: number]: T是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
findIndex(predicate: (value: T, index: number, obj: T[]) => unknown, thisArg?: any): numberfindIndex(predicate: (value: T, index: number, obj: Array<T>) => boolean): number是ArkTS不支持this，因此不支持thisArg参数。
fill(value: T, start?: number, end?: number): thisfill(value: T, start?: number, end?: number): Array<T>是1. 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
2. 继承场景下，无法获得实际类型的返回值。
entries(): IterableIterator<[number, T]>entries(): IterableIterator<[number, T]>否/
keys(): IterableIterator<number>keys(): IterableIterator<number>否/
values(): IterableIterator<T>values(): IterableIterator<T>否/
includes(searchElement: T, fromIndex?: number): booleanincludes(searchElement: T, fromIndex?: number): boolean否/
at(index: number): T |undefinedat(index: number): T |undefined否/
isArray(arg: any): arg is any[]static isArray(value: Object |undefined |null): boolean是仅判断是否为ArkTS的Array实例，对原生容器Array返回false。
of<T>(...items: T[]): T[]static of<T>(...items: T[]): Array<T>否/
copyWithin(target: number, start: number, end?: number): thiscopyWithin(target: number, start: number, end?: number): Array<T>是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
lastIndexOf(searchElement: T, fromIndex?: number): numberlastIndexOf(searchElement: T, fromIndex?: number): number是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
some(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): booleansome(predicate: ArrayPredicateFn<T, Array<T>>): boolean是1. 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
2.ArkTS不支持this，因此不支持thisArg参数。
reduceRight(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): TreduceRight(callbackFn: ArrayReduceCallback<T, T, Array<T>>): T是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
reduceRight<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): UreduceRight<U = T>(callbackFn: ArrayReduceCallback<U, T, Array<T>>, initialValue: U): U是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
reverse(): T[]reverse(): Array<T>是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
toString(): stringtoString(): string是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
find(predicate: (value: T, index: number, obj: T[]) => unknown, thisArg?: any): T |undefinedfind(predicate: (value: T, index: number, obj: Array<T>) => boolean): T |undefined是1. 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
2. ArkTS不支持this，因此不支持thisArg参数。
splice(start: number, deleteCount: number, ...items: T[]): T[]splice(start: number, deleteCount: number, ...items: T[]): Array<T>是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。
every(predicate: (value: T, index: number, array: T[]) => unknown, thisArg?: any): booleanevery(predicate: ArrayPredicateFn<T, Array<T>>): boolean是ArkTS不支持this，因此不支持thisArg参数。
toLocaleString(): stringtoLocaleString(): string是不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。

ArrayBuffer

原生API方法ArkTS容器集方法是否有行为差异在ArkTS容器中的差异表现
readonly byteLength: numberreadonly byteLength: number否/
slice(begin: number, end?: number): ArrayBufferslice(begin: number, end?: number): ArrayBuffer否/
new(byteLength: number): ArrayBufferconstructor(byteLength: number)否/

TypedArray（以Int8Array为例）

支持原生容器TypedArray通过collections.TypedArray.from方法转换为ArkTS TypedArray容器；支持通过原生容器TypedArray的from方法将ArkTS TypedArray容器转换为原生容器TypedArray。

原生API方法ArkTS容器集方法是否有行为差异在ArkTS容器中的差异表现
readonly buffer: ArrayBufferLikereadonly buffer: ArrayBuffer否/
readonly byteLength: numberreadonly byteLength: number否/
readonly byteOffset: numberreadonly byteOffset: number否/
readonly length: numberreadonly length: number否/
readonly BYTES_PER_ELEMENT: numberstatic readonly BYTES_PER_ELEMENT: number否/
copyWithin(target: number, start: number, end?: number): thiscopyWithin(target: number, start: number, end?: number): Int8Array是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
every(predicate: (value: number, index: number, array: Int8Array) => unknown, thisArg?: any): booleanevery(predicate: TypedArrayPredicateFn<number, Int8Array>): boolean是1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
2. ArkTS不支持this，因此不支持thisArg参数。
fill(value: number, start?: number, end?: number): thisfill(value: number, start?: number, end?: number): Int8Array是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
filter(predicate: (value: number, index: number, array: Int8Array) => any, thisArg?: any): Int8Arrayfilter(predicate: TypedArrayPredicateFn<number, Int8Array>): Int8Array是1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
2. ArkTS不支持this，因此不支持thisArg参数。
find(predicate: (value: number, index: number, obj: Int8Array) => boolean, thisArg?: any): number |undefinedfind(predicate: TypedArrayPredicateFn<number, Int8Array>): number |undefined是1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
2. ArkTS不支持this，因此不支持thisArg参数。
findIndex(predicate: (value: number, index: number, obj: Int8Array) => boolean, thisArg?: any): numberfindIndex(predicate: TypedArrayPredicateFn<number, Int8Array>): number是ArkTS不支持this，因此不支持thisArg参数。
forEach(callbackfn: (value: number, index: number, array: Int8Array) => void, thisArg?: any): voidforEach(callbackFn: (value: number, index: number, array: Int8Array) => void): void是1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
2. ArkTS不支持this，因此不支持thisArg参数。
indexOf(searchElement: number, fromIndex?: number): numberindexOf(searchElement: number, fromIndex?: number): number否/
join(separator?: string): stringjoin(separator?: string): string否/
map(callbackfn: (value: number, index: number, array: Int8Array) => number, thisArg?: any): Int8Arraymap(callbackFn: TypedArrayForEachCallback<number, Int8Array>): Int8Array是1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
2. ArkTS不支持this，因此不支持thisArg参数。
reduce(callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Int8Array) => number): numberreduce(callbackFn: TypedArrayReduceCallback<number, number, Int8Array>): number否/
reduce(callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Int8Array) => number, initialValue: number): numberreduce(callbackFn: TypedArrayReduceCallback<number, number, Int8Array>, initialValue: number): number否/
reduce<U>(callbackfn: (previousValue: U, currentValue: number, currentIndex: number, array: Int8Array) => U, initialValue: U): Ureduce<U>(callbackFn: TypedArrayReduceCallback<U, number, Int8Array>, initialValue: U): U否/
reverse(): Int8Arrayreverse(): Int8Array否/
set(array: ArrayLike<number>, offset?: number): voidset(array: ArrayLike<number>, offset?: number): void是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
slice(start?: number, end?: number): Int8Arrayslice(start?: number, end?: number): Int8Array否/
some(predicate: (value: number, index: number, array: Int8Array) => unknown, thisArg?: any): booleansome(predicate: TypedArrayPredicateFn<number, Int8Array>): boolean是ArkTS不支持this，因此不支持thisArg参数。
sort(compareFn?: (a: number, b: number) => number): thissort(compareFn?: TypedArrayCompareFn<number>): Int8Array是1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
2. 继承场景下，无法获得实际类型的返回值。
subarray(begin?: number, end?: number): Int8Arraysubarray(begin?: number, end?: number): Int8Array是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
[index: number]: number[index: number]: number是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
entries(): IterableIterator<[number, number]>entries(): IterableIterator<[number, number]>否/
keys(): IterableIterator<number>keys(): IterableIterator<number>否/
values(): IterableIterator<number>values(): IterableIterator<number>否/
includes(searchElement: number, fromIndex?: number): booleanincludes(searchElement: number, fromIndex?: number): boolean否/
at(index: number): number |undefinedat(index: number): number |undefined否/
new(length: number): Int8Arrayconstructor(length: number)否/
new(array: ArrayLike<number> |ArrayBufferLike): Int8Arrayconstructor(array: ArrayLike<number> |ArrayBuffer)否/
new(buffer: ArrayBufferLike, byteOffset?: number, length?: number): Int8Arrayconstructor(buffer: ArrayBuffer, byteOffset?: number, length?: number)否/
from(arrayLike: ArrayLike<number>): Int8Arraystatic from(arrayLike: ArrayLike<number>): Int8Array否/
from<T>(arrayLike: ArrayLike<T>, mapfn: (v: T, k: number) => number, thisArg?: any): Int8Arraystatic from<T>(arrayLike: ArrayLike<T>, mapFn: TypedArrayFromMapFn<T, number>): Int8Array是ArkTS不支持this，因此不支持thisArg参数。
from(arrayLike: Iterable<number>, mapfn?: (v: number, k: number) => number, thisArg?: any): Int8Arraystatic from(arrayLike: Iterable<number>, mapFn?: TypedArrayFromMapFn<number, number>): Int8Array是ArkTS不支持this，因此不支持thisArg参数。
of(...items: number[]): Int8Arraystatic of(...items: number[]): Int8Array否/
toString(): stringtoString(): string是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
toLocaleString(): stringtoLocaleString(): string是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
lastIndexOf(searchElement: number, fromIndex?: number): numberlastIndexOf(searchElement: number, fromIndex?: number): number是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
reduceRight(callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Int8Array) => number): numberreduceRight(callbackFn: TypedArrayReduceCallback<number, number, Int8Array>): number是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
reduceRight<U>(callbackfn: (previousValue: U, currentValue: number, currentIndex: number, array: Int8Array) => U, initialValue: U): UreduceRight<U = number>(callbackFn: TypedArrayReduceCallback<U, number, Int8Array>, initialValue: U): U是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。

Map

原生API方法ArkTS容器集方法是否有行为差异在ArkTS容器中的差异表现
readonly size: numberreadonly size: number是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
clear(): voidclear(): void是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
delete(key: K): booleandelete(key: K): boolean是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): voidforEach(callbackFn: (value: V, key: K, map: Map<K, V>) => void): void是1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
2. ArkTS不支持this，因此不支持thisArg参数。
get(key: K): V |undefinedget(key: K): V |undefined是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
has(key: K): booleanhas(key: K): boolean是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
set(key: K, value: V): thisset(key: K, value: V): Map<K, V>是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
entries(): IterableIterator<[K, V]>entries(): IterableIterator<[K, V]>否/
keys(): IterableIterator<K>keys(): IterableIterator<K>否/
values(): IterableIterator<V>values(): IterableIterator<V>否/
new <K, V>(entries?: readonly (readonly [K, V])[] |null): Map<K, V>constructor(entries?: readonly (readonly [K, V])[] |null)是构造时传入的k,v键值不能是非Sendable数据，否则编译会报错。

Set

原生API方法ArkTS容器集方法是否有行为差异在ArkTS容器中的差异表现
readonly size: numberreadonly size: number是Sendable类和接口中不允许使用计算属性名称(arkts-sendable-compated-prop-name)。
add(value: T): thisadd(value: T): Set<T>是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
clear(): voidclear(): void是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
delete(value: T): booleandelete(value: T): boolean是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
forEach(callbackfn: (value: T, value2: T, set: Set<T>) => void, thisArg?: any): voidforEach(callbackFn: (value: T, value2: T, set: Set<T>) => void): void是1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
2. ArkTS不支持this，因此不支持thisArg参数。
has(value: T): booleanhas(value: T): boolean是不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。
entries(): IterableIterator<[T, T]>entries(): IterableIterator<[T, T]>否/
keys(): IterableIterator<T>keys(): IterableIterator<T>否/
values(): IterableIterator<T>values(): IterableIterator<T>是Sendable类和接口中不允许使用计算属性名称(arkts-sendable-compated-prop-name)。
new <T = any>(values?: readonly T[] |null): Set<T>constructor(values?: readonly T[] |null)是构造时传入的数据必须是Sendable类型，否则编译会报错。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkTS（方舟编程语言）

harmony 鸿蒙在build-profile.json5中配置arkOptions

harmony 鸿蒙异步锁

harmony 鸿蒙方舟字节码文件格式

harmony 鸿蒙方舟字节码函数命名规则

harmony 鸿蒙方舟字节码基本原理

harmony 鸿蒙方舟字节码概述

harmony 鸿蒙异步等待

harmony 鸿蒙ArkTS跨语言交互

harmony 鸿蒙动态加载

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/pXEzRJ