1# 共享容器 2 3## ArkTS容器集 4 5ArkTS共享容器（[@arkts.collections (ArkTS容器集)](../reference/apis-arkts/js-apis-arkts-collections.md)）是一种在并发任务间共享传输的容器类，可以用于并发场景下的高性能数据传递。功能与Ecmascript262规范定义的容器类似，但仍然有部分差异，具体可见[共享容器与原生API方法的行为差异对比](#共享容器与原生api方法的行为差异对比)。 6 7ArkTS共享容器在多个并发任务间传递时，默认采用引用传递，允许多个并发任务操作同一个容器实例。此外，还支持拷贝传递，即每个并发任务拥有一个独立的ArkTS容器实例。 8 9ArkTS共享容器不是线程安全的，内部使用了fail-fast（快速失败）机制，即当检测到多个并发实例同时对容器进行结构性修改时，会触发异常。因此，在容器内修改属性的场景下，开发者需要使用ArkTS提供的[异步锁](arkts-async-lock-introduction.md)机制保证ArkTS容器的安全访问。 10 11ArkTS共享容器包含如下几种：[Array](../reference/apis-arkts/js-apis-arkts-collections.md#collectionsarray)、[Map](../reference/apis-arkts/js-apis-arkts-collections.md#collectionsmap)、[Set](../reference/apis-arkts/js-apis-arkts-collections.md#collectionsset)、[TypedArray](../reference/apis-arkts/js-apis-arkts-collections.md#collectionstypedarray)（Int8Array、Uint8Array、Int16Array、Uint16Array、Int32Array、Uint32Array、Uint8ClampedArray、Float32Array）、[ArrayBuffer](../reference/apis-arkts/js-apis-arkts-collections.md#collectionsarraybuffer)等，具体可见[@arkts.collections (ArkTS容器集)](../reference/apis-arkts/js-apis-arkts-collections.md)。 12 13容器集使用示例如下： 14 15```ts 16import { ArkTSUtils, collections, taskpool } from '@kit.ArkTS'; 17 18@Concurrent 19async function add(arr: collections.Array<number>, lock: ArkTSUtils.locks.AsyncLock) { 20 await lock.lockAsync(() => { // 如果不添加异步锁，任务会因为数据竞争冲突，导致抛异常失败 21 arr[0]++; 22 }) 23} 24 25@Entry 26@Component 27struct Index { 28 @State message: string = 'Hello World'; 29 30 build() { 31 RelativeContainer() { 32 Text(this.message) 33 .id('HelloWorld') 34 .fontSize(50) 35 .fontWeight(FontWeight.Bold) 36 .alignRules({ 37 center: { anchor: '__container__', align: VerticalAlign.Center }, 38 middle: { anchor: '__container__', align: HorizontalAlign.Center } 39 }) 40 .onClick(() => { 41 let taskGroup = new taskpool.TaskGroup(); 42 let lock = new ArkTSUtils.locks.AsyncLock(); 43 let arr = collections.Array.create<number>(1, 0); 44 let count = 1000; 45 while (count--) { 46 taskGroup.addTask(add, arr, lock); 47 } 48 taskpool.execute(taskGroup).then(() => { 49 console.info(`Return success: ${arr[0]} === ${count}`); 50 }).catch((e: Error) => { 51 console.error("Return error."); 52 }) 53 }) 54 } 55 .height('100%') 56 .width('100%') 57 } 58} 59``` 60 61## 共享容器与原生API方法的行为差异对比 62 63ArkTS提供了Sendable数据相关的共享容器集，接口行为与原生API存在部分差异，具体可见下文对比。 64 65> **说明：** 66> 67> ArkTS共享容器的类型与Ecmascript262规范定义的原生容器的类型不同，因此使用原生容器Array的isArray()方法判断collections.Array实例对象会返回false。 68> 69> ArkTS共享容器跨线程传递采用引用传递方式，与原生容器相比效率更高，如果开发者需要跨线程传输的数据量很大，建议使用ArkTS共享容器。 70 71### Array 72 73支持原生容器Array通过[collections.Array.from](../reference/apis-arkts/js-apis-arkts-collections.md#from)方法转换为ArkTS Array容器；支持通过原生容器Array的from方法将ArkTS Array容器转换为原生容器Array。 74 75| 原生API方法 | ArkTS容器集方法 | 是否有行为差异 | 在ArkTS容器中的差异表现 | 76| -------- | -------- | -------- | -------- | 77| length: number | readonly length: number | 是 | 为了防止undefined扩散，不允许设置length。 | 78| new(arrayLength ?: number): any[] | static create(arrayLength: number, initialValue: T): Array | 是 | 为了防止undefined扩散，构造函数中必须提供一个初始值。 | 79| new <T>(arrayLength: number): T[] | constructor() | 否 | / | 80| new <T>(...items: T[]): T[] | constructor(first: T, ...left: T[]) | 是 | 为了防止undefined扩散，构造函数中必须提供一个初始值，继承场景下，无法调用该函数进行对象构造。 | 81| from<T>(arrayLike: ArrayLike<T>): T[] | static from<T>(arrayLike: ArrayLike<T>): Array<T> | 否 | / | 82| pop(): T \| undefined | pop(): T \| undefined | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。 | 83| push(...items: T[]): number | push(...items: T[]): number | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。 | 84| concat(...items: ConcatArray<T>[]): T[] | concat(...items: ConcatArray<T>[]): Array<T> | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。 | 85| concat(...items: (T \| ConcatArray<T>)[]): T[] | concat(...items: ConcatArray<T>[]): Array<T> | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。 | 86| join(separator?: string): string | join(separator?: string): string | 否 | / | 87| shift(): T \| undefined | shift(): T \| undefined | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。 | 88| slice(start?: number, end?: number): T[] | slice(start?: number, end?: number): Array<T> | 否 | / | 89| sort(compareFn?: (a: T, b: T) => number): this | sort(compareFn?: (a: T, b: T) => number): Array<T> | 是 | 1. 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。<br/>2. 继承场景下，无法获得实际类型的返回值。 | 90| unshift(...items: T[]): number | unshift(...items: T[]): number | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。 | 91| indexOf(searchElement: T, fromIndex?: number): number | indexOf(searchElement: T, fromIndex?: number): number | 否 | / | 92| forEach(callbackfn: (value: T, index: number, array: T[]) => void, thisArg?: any): void | forEach(callbackFn: (value: T, index: number, array: Array<T>) => void): void | 是 | ArkTS不支持this，因此不支持thisArg参数。 | 93| 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参数。 | 94| 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参数。 | 95| reduce(callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): T | reduce(callbackFn: (previousValue: T, currentValue: T, currentIndex: number, array: Array<T>) => T): T | 否 | / | 96| reduce<U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U | reduce<U>(callbackFn: (previousValue: U, currentValue: T, currentIndex: number, array: Array<T>) => U, initialValue: U): U | 否 | / | 97| [n: number]: T | [index: number]: T | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。 | 98| findIndex(predicate: (value: T, index: number, obj: T[]) => unknown, thisArg?: any): number | findIndex(predicate: (value: T, index: number, obj: Array<T>) => boolean): number | 是 | ArkTS不支持this，因此不支持thisArg参数。 | 99| fill(value: T, start?: number, end?: number): this | fill(value: T, start?: number, end?: number): Array<T> | 是 | 1. 不允许在遍历、访问过程中进行元素的增、删、改操作，否则会抛出异常。<br/>2. 继承场景下，无法获得实际类型的返回值。 | 100| entries(): IterableIterator<[number, T]> | entries(): IterableIterator<[number, T]> | 否 | / | 101| keys(): IterableIterator<number> | keys(): IterableIterator<number> | 否 | / | 102| values(): IterableIterator<T> | values(): IterableIterator<T> | 否 | / | 103| includes(searchElement: T, fromIndex?: number): boolean | includes(searchElement: T, fromIndex?: number): boolean | 否 | / | 104| at(index: number): T \| undefined | at(index: number): T \| undefined | 否 | / | 105 106### ArrayBuffer 107 108| 原生API方法 | ArkTS容器集方法 | 是否有行为差异 | 在ArkTS容器中的差异表现 | 109| -------- | -------- | -------- | -------- | 110| readonly byteLength: number | readonly byteLength: number | 否 | / | 111| slice(begin: number, end?: number): ArrayBuffer | slice(begin: number, end?: number): ArrayBuffer | 否 | / | 112| new(byteLength: number): ArrayBuffer | constructor(byteLength: number) | 否 | / | 113 114### TypedArray（以Int8Array为例） 115 116支持原生容器TypedArray通过[collections.TypedArray.from](../reference/apis-arkts/js-apis-arkts-collections.md#from-1)方法转换为ArkTS TypedArray容器；支持通过原生容器TypedArray的from方法将ArkTS TypedArray容器转换为原生容器TypedArray。 117 118| 原生API方法 | ArkTS容器集方法 | 是否有行为差异 | 在ArkTS容器中的差异表现 | 119| -------- | -------- | -------- | -------- | 120| readonly buffer: ArrayBufferLike | readonly buffer: ArrayBuffer | 否 | / | 121| readonly byteLength: number | readonly byteLength: number | 否 | / | 122| readonly byteOffset: number | readonly byteOffset: number | 否 | / | 123| readonly length: number | readonly length: number | 否 | / | 124| readonly BYTES_PER_ELEMENT: number | static readonly BYTES_PER_ELEMENT: number | 否 | / | 125| copyWithin(target: number, start: number, end?: number): this | copyWithin(target: number, start: number, end?: number): Int8Array | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 126| every(predicate: (value: number, index: number, array: Int8Array) => unknown, thisArg?: any): boolean | every(predicate: TypedArrayPredicateFn<number, Int8Array>): boolean | 是 | 1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。<br/>2. ArkTS不支持this，因此不支持thisArg参数。 | 127| fill(value: number, start?: number, end?: number): this | fill(value: number, start?: number, end?: number): Int8Array | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 128| filter(predicate: (value: number, index: number, array: Int8Array) => any, thisArg?: any): Int8Array | filter(predicate: TypedArrayPredicateFn<number, Int8Array>): Int8Array | 是 | 1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。<br/>2. ArkTS不支持this，因此不支持thisArg参数。 | 129| find(predicate: (value: number, index: number, obj: Int8Array) => boolean, thisArg?: any): number \| undefined | find(predicate: TypedArrayPredicateFn<number, Int8Array>): number \| undefined | 是 | 1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。<br/>2. ArkTS不支持this，因此不支持thisArg参数。 | 130| findIndex(predicate: (value: number, index: number, obj: Int8Array) => boolean, thisArg?: any): number | findIndex(predicate: TypedArrayPredicateFn<number, Int8Array>): number | 是 | ArkTS不支持this，因此不支持thisArg参数。 | 131| forEach(callbackfn: (value: number, index: number, array: Int8Array) => void, thisArg?: any): void | forEach(callbackFn: (value: number, index: number, array: Int8Array) => void): void | 是 | 1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。<br/>2. ArkTS不支持this，因此不支持thisArg参数。 | 132| indexOf(searchElement: number, fromIndex?: number): number | indexOf(searchElement: number, fromIndex?: number): number | 否 | / | 133| join(separator?: string): string | join(separator?: string): string | 否 | / | 134| map(callbackfn: (value: number, index: number, array: Int8Array) => number, thisArg?: any): Int8Array | map(callbackFn: TypedArrayForEachCallback<number, Int8Array>): Int8Array | 是 | 1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。<br/>2. ArkTS不支持this，因此不支持thisArg参数。 | 135| reduce(callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Int8Array) => number): number | reduce(callbackFn: TypedArrayReduceCallback<number, number, Int8Array>): number | 否 | / | 136| reduce(callbackfn: (previousValue: number, currentValue: number, currentIndex: number, array: Int8Array) => number, initialValue: number): number | reduce(callbackFn: TypedArrayReduceCallback<number, number, Int8Array>, initialValue: number): number | 否 | / | 137| reduce<U>(callbackfn: (previousValue: U, currentValue: number, currentIndex: number, array: Int8Array) => U, initialValue: U): U | reduce<U>(callbackFn: TypedArrayReduceCallback<U, number, Int8Array>, initialValue: U): U | 否 | / | 138| reverse(): Int8Array | reverse(): Int8Array | 否 | / | 139| set(array: ArrayLike<number>, offset?: number): void | set(array: ArrayLike<number>, offset?: number): void | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 140| slice(start?: number, end?: number): Int8Array | slice(start?: number, end?: number): Int8Array | 否 | / | 141| some(predicate: (value: number, index: number, array: Int8Array) => unknown, thisArg?: any): boolean | some(predicate: TypedArrayPredicateFn<number, Int8Array>): boolean | 是 | ArkTS不支持this，因此不支持thisArg参数。 | 142| sort(compareFn?: (a: number, b: number) => number): this | sort(compareFn?: TypedArrayCompareFn<number>): Int8Array | 是 | 1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。<br/>2. 继承场景下，无法获得实际类型的返回值。 | 143| subarray(begin?: number, end?: number): Int8Array | subarray(begin?: number, end?: number): Int8Array | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 144| [index: number]: number | [index: number]: number | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 145| entries(): IterableIterator<[number, number]> | entries(): IterableIterator<[number, number]> | 否 | / | 146| keys(): IterableIterator<number> | keys(): IterableIterator<number> | 否 | / | 147| values(): IterableIterator<number> | values(): IterableIterator<number> | 否 | / | 148| includes(searchElement: number, fromIndex?: number): boolean | includes(searchElement: number, fromIndex?: number): boolean | 否 | / | 149| at(index: number): number \| undefined | at(index: number): number \| undefined | 否 | / | 150| new(length: number): Int8Array | constructor(length: number) | 否 | / | 151| new(array: ArrayLike<number> \| ArrayBufferLike): Int8Array | constructor(array: ArrayLike<number> \| ArrayBuffer) | 否 | / | 152| new(buffer: ArrayBufferLike, byteOffset?: number, length?: number): Int8Array | constructor(buffer: ArrayBuffer, byteOffset?: number, length?: number) | 否 | / | 153| from(arrayLike: ArrayLike<number>): Int8Array | static from(arrayLike: ArrayLike<number>): Int8Array | 否 | / | 154| from<T>(arrayLike: ArrayLike<T>, mapfn: (v: T, k: number) => number, thisArg?: any): Int8Array | static from<T>(arrayLike: ArrayLike<T>, mapFn: TypedArrayFromMapFn<T, number>): Int8Array | 是 | ArkTS不支持this，因此不支持thisArg参数。 | 155| from(arrayLike: Iterable<number>, mapfn?: (v: number, k: number) => number, thisArg?: any): Int8Array | static from(arrayLike: Iterable<number>, mapFn?: TypedArrayFromMapFn<number, number>): Int8Array | 是 | ArkTS不支持this，因此不支持thisArg参数。 | 156 157### Map 158 159| 原生API方法 | ArkTS容器集方法 | 是否有行为差异 | 在ArkTS容器中的差异表现 | 160| -------- | -------- | -------- | -------- | 161| readonly size: number | readonly size: number | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 162| clear(): void | clear(): void | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 163| delete(key: K): boolean | delete(key: K): boolean | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 164| forEach(callbackfn: (value: V, key: K, map: Map<K, V>) => void, thisArg?: any): void | forEach(callbackFn: (value: V, key: K, map: Map<K, V>) => void): void | 是 | 1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。<br/>2. ArkTS不支持this，因此不支持thisArg参数。 | 165| get(key: K): V \| undefined | get(key: K): V \| undefined | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 166| has(key: K): boolean | has(key: K): boolean | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 167| set(key: K, value: V): this | set(key: K, value: V): Map<K, V> | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 168| entries(): IterableIterator<[K, V]> | entries(): IterableIterator<[K, V]> | 否 | / | 169| keys(): IterableIterator<K> | keys(): IterableIterator<K> | 否 | / | 170| values(): IterableIterator<V> | values(): IterableIterator<V> | 否 | / | 171| new <K, V>(entries?: readonly (readonly [K, V])[] \| null): Map<K, V> | constructor(entries?: readonly (readonly [K, V])[] \| null) | 是 | 构造时传入的k,v键值不能是非Sendable数据，否则编译会报错。 | 172 173### Set 174 175| 原生API方法 | ArkTS容器集方法 | 是否有行为差异 | 在ArkTS容器中的差异表现 | 176| -------- | -------- | -------- | -------- | 177| readonly size: number | readonly size: number | 是 | Sendable类和接口中不允许使用计算属性名称(arkts-sendable-compated-prop-name)。 | 178| add(value: T): this | add(value: T): Set<T> | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 179| clear(): void | clear(): void | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 180| delete(value: T): boolean | delete(value: T): boolean | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 181| forEach(callbackfn: (value: T, value2: T, set: Set<T>) => void, thisArg?: any): void | forEach(callbackFn: (value: T, value2: T, set: Set<T>) => void): void | 是 | 1. 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。<br/>2. ArkTS不支持this，因此不支持thisArg参数。 | 182| has(value: T): boolean | has(value: T): boolean | 是 | 不允许在遍历、访问过程中进行元素的增、删、改操作否则会抛出异常。 | 183| entries(): IterableIterator<[T, T]> | entries(): IterableIterator<[T, T]> | 否 | / | 184| keys(): IterableIterator<T> | keys(): IterableIterator<T> | 否 | / | 185| values(): IterableIterator<T> | values(): IterableIterator<T> | 是 | Sendable类和接口中不允许使用计算属性名称(arkts-sendable-compated-prop-name)。 | 186| new <T = any>(values?: readonly T[] \| null): Set<T> | constructor(values?: readonly T[] \| null) | 是 | 构造时传入的数据必须是Sendable类型，否则编译会报错。 | 187