1# Class (Array) 2<!--Kit: ArkTS--> 3<!--Subsystem: CommonLibrary--> 4<!--Owner: @lijiamin2025--> 5<!--Designer: @weng-changcheng--> 6<!--Tester: @kirl75; @zsw_zhushiwei--> 7<!--Adviser: @ge-yafang--> 8> **说明：** 9> 10> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 11> 12> 此模块仅支持在ArkTS文件（文件后缀为.ets）中导入使用。 13 14一种线性数据结构，底层基于数组实现，可以在ArkTS上并发实例间传递。 15 16当需要在ArkTS上并发实例间传递Array时，可以通过传递Array引用提升传递性能。 17 18文档中存在泛型的使用，涉及以下泛型标记符： 19 20- T：Type，支持[Sendable支持的数据类型](../../arkts-utils/arkts-sendable.md#sendable支持的数据类型)。 21 22**装饰器类型：**\@Sendable 23 24## 导入模块 25 26```ts 27import { collections } from '@kit.ArkTS'; 28``` 29 30## 属性 31 32**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 33 34**系统能力：** SystemCapability.Utils.Lang 35 36| 名称 | 类型 | 只读 | 可选 | 说明 | 37| ------ | ------ | ---- | ---- | ----------------- | 38| length | number | 是 | 否 | Array的元素个数。 | 39 40 41## constructor 42 43constructor() 44 45创建一个ArkTS Array的构造函数。 46 47**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 48 49**系统能力：** SystemCapability.Utils.Lang 50 51**错误码：** 52 53以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 54 55| 错误码ID | 错误信息 | 56| -------- | --------------------------------------------------- | 57| 10200012 | The Array's constructor cannot be directly invoked. | 58 59**示例：** 60 61```ts 62let array = new collections.Array<number>(); 63``` 64 65## constructor 66 67constructor(first: T, ...left: T[]) 68 69ArkTS Array的构造函数，通过开发者提供的元素进行初始化。 70 71**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 72 73**系统能力：** SystemCapability.Utils.Lang 74 75**参数：** 76 77| 参数名 | 类型 | 必填 | 说明 | 78| ------ | ---- | ---- | ------------------------------- | 79| first | T | 是 | 初始化ArkTS Array的第一个元素。 | 80| left | T[] | 否 | 初始化ArkTS Array的剩余元素。 | 81 82**错误码：** 83 84以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 85 86| 错误码ID | 错误信息 | 87| -------- | --------------------------------------------------- | 88| 401 | Parameter error. | 89| 10200012 | The Array's constructor cannot be directly invoked. | 90 91**示例：** 92 93```ts 94let array = new collections.Array<number>(1, 2, 3, 4); 95``` 96## constructor 97 98constructor(...items: T[]) 99 100ArkTS Array的构造函数，通过开发者提供的元素进行初始化。 101 102**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 103 104**系统能力：** SystemCapability.Utils.Lang 105 106**参数：** 107 108| 参数名 | 类型 | 必填 | 说明 | 109| ------ | ---- | ---- | ------------------------------- | 110| items | T[] | 否 | 初始化ArkTS Array的元素。 | 111 112**错误码：** 113 114以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 115 116| 错误码ID | 错误信息 | 117| -------- | --------------------------------------------------- | 118| 401 | Parameter error. | 119| 10200012 | The Array's constructor cannot be directly invoked. | 120 121**示例：** 122 123```ts 124let arrayPara = [1,2,3]; 125let array = new collections.Array<number>(...arrayPara); 126``` 127 128## create 129 130static create\<T>(arrayLength: number, initialValue: T): Array\<T> 131 132生成一个固定长度的Array，其中，每个元素的初始值为initialValue。 133 134**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 135 136**系统能力：** SystemCapability.Utils.Lang 137 138**参数：** 139 140| 参数名 | 类型 | 必填 | 说明 | 141| --------- | ------------- | ---- | ------------------------------- | 142| arrayLength | number | 是 | 用于构造ArkTS Array的长度。 | 143| initialValue | T | 是 | 用于填充ArkTS Array的值。 | 144 145**返回值：** 146 147| 类型 | 说明 | 148| --------- | ----------------------- | 149| Array\<T> | 新创建的ArkTS Array实例。 | 150 151**错误码：** 152 153以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 154 155| 错误码ID | 错误信息 | 156| -------- | -------------------------------- | 157| 401 | Parameter error. | 158 159**示例：** 160 161```ts 162let array = collections.Array.create<number>(3, 10); // [10, 10, 10] 163``` 164 165## from 166 167static from\<T>(arrayLike: ArrayLike\<T>): Array\<T> 168 169从一个实现了ArrayLike接口的对象创建一个新的ArkTS Array。 170 171**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 172 173**系统能力：** SystemCapability.Utils.Lang 174 175**参数：** 176 177| 参数名 | 类型 | 必填 | 说明 | 178| --------- | ------------- | ---- | ------------------------------- | 179| arrayLike | ArrayLike\<T> | 是 | 用于构造ArkTS Array的对象。 | 180 181**返回值：** 182 183| 类型 | 说明 | 184| --------- | ----------------------- | 185| Array\<T> | 新创建的ArkTS Array实例。 | 186 187**错误码：** 188 189以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 190 191| 错误码ID | 错误信息 | 192| -------- | -------------------------------- | 193| 401 | Parameter error. | 194 195**示例：** 196 197```ts 198// 正例 199let array : Array<string> = ['str1', 'str2', 'str3']; // 原生Array<T>，T是Sendable数据类型。 200let sendableArray = collections.Array.from<string>(array); // 返回Sendable Array<T> 201``` 202 203<!--code_no_check--> 204```ts 205// 反例 206let array : Array<Array<string>> = [['str1', 'str2', 'str3'], ['str4', 'str5', 'str6'], ['str7', 'str8', 'str9']]; // 原生Array<T>，T是非Sendable数据类型。 207let sendableArray = collections.Array.from<Array<string>>(array); // 打印异常信息：Parameter error.Only accept sendable value 208``` 209 210## from 211 212static from\<T>(iterable: Iterable\<T>): Array\<T> 213 214从一个实现了Iterable接口的对象创建一个新的ArkTS Array。 215 216**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 217 218**系统能力：** SystemCapability.Utils.Lang 219 220**参数：** 221 222| 参数名 | 类型 | 必填 | 说明 | 223| --------- | ------------- | ---- | ------------------------------- | 224| iterable | Iterable\<T> | 是 | 用于构造ArkTS Array的对象。 | 225 226**返回值：** 227 228| 类型 | 说明 | 229| --------- | ----------------------- | 230| Array\<T> | 新创建的ArkTS Array实例。 | 231 232**错误码：** 233 234以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 235 236| 错误码ID | 错误信息 | 237| -------- | -------------------------------- | 238| 401 | Parameter error: Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 239 240**示例：** 241 242```ts 243// 正例 244const mapper = new Map([ 245 ['1', 'a'], 246 ['2', 'b'], 247]); 248let newArray: collections.Array<string> = collections.Array.from(mapper.values()); 249console.info(newArray.toString()); // 预期输出： a,b 250``` 251 252## from<sup>18+</sup> 253 254static from\<T>(arrayLike: ArrayLike\<T> | Iterable\<T>, mapFn: ArrayFromMapFn\<T, T>): Array\<T> 255 256从一个实现了ArrayLike接口的对象创建一个新的ArkTS Array，并且使用自定义函数处理每个数组元素。 257 258**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 259 260**系统能力：** SystemCapability.Utils.Lang 261 262**参数：** 263 264| 参数名 | 类型 | 必填 | 说明 | 265| --------- | ------------- | ---- | ------------------------------- | 266| arrayLike | ArrayLike\<T> \| Iterable\<T> | 是 | 用于构造ArkTS Array的对象。 | 267| mapFn | [ArrayFromMapFn](arkts-apis-arkts-collections-Types.md#arrayfrommapfn18)\<T,T> | 是 | 调用数组每个元素的函数。 | 268 269**返回值：** 270 271| 类型 | 说明 | 272| --------- | ----------------------- | 273| Array\<T> | 新创建的ArkTS Array实例。 | 274 275**错误码：** 276 277以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 278 279| 错误码ID | 错误信息 | 280| -------- | -------------------------------- | 281| 401 | Parameter error: Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 282 283**示例：** 284 285```ts 286let array : Array<number> = [1, 2, 3]; // 原生Array<T>，T是Sendable数据类型。 287let newArray = collections.Array.from<number>(array, (value, index) => value + index); // 返回新的 Array<T> 288console.info(newArray.toString()); // 预期输出： 1, 3, 5 289``` 290 291## from<sup>18+</sup> 292 293static from\<U, T>(arrayLike: ArrayLike\<U> | Iterable\<U>, mapFn: ArrayFromMapFn\<U, T>): Array\<T> 294 295从一个实现了ArrayLike接口的对象创建一个新的ArkTS Array，并且使用自定义函数处理每个数组元素，ArrayLike接口对象的元素类型可以和数组元素的类型不一样。 296 297**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 298 299**系统能力：** SystemCapability.Utils.Lang 300 301**参数：** 302 303| 参数名 | 类型 | 必填 | 说明 | 304| --------- | ------------- | ---- | ------------------------------- | 305| arrayLike | ArrayLike\<U> \| Iterable\<U> | 是 | 用于构造ArkTS Array的对象。 | 306| mapFn | [ArrayFromMapFn](arkts-apis-arkts-collections-Types.md#arrayfrommapfn18)\<U, T> | 是 | 调用数组每个元素的函数。 | 307 308**返回值：** 309 310| 类型 | 说明 | 311| --------- | ----------------------- | 312| Array\<T> | 新创建的ArkTS Array实例。 | 313 314**错误码：** 315 316以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 317 318| 错误码ID | 错误信息 | 319| -------- | -------------------------------- | 320| 401 | Parameter error: Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 321 322**示例：** 323 324```ts 325let array : Array<number> = [1, 2, 3]; // 原生Array<T> 326let newArray = collections.Array.from<number, string>(array, (value, index) => value + "." + index); // 返回新的 Array<T> 327console.info(newArray.toString()); // 预期输出： 1.0, 2.1, 3.2 328``` 329 330## isArray<sup>18+</sup> 331 332static isArray(value: Object | undefined | null): boolean 333 334检查传入的参数是否是一个ArkTS Array。 335 336**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 337 338**系统能力：** SystemCapability.Utils.Lang 339 340**参数：** 341 342| 参数名 | 类型 | 必填 | 说明 | 343| --------- | ------------- | ---- | ------------------------------- | 344| value | Object \| undefined \| null | 是 | 需要被检查的值。 | 345 346**返回值：** 347 348| 类型 | 说明 | 349| --------- | ----------------------- | 350| boolean | 假如给定对象是ArkTS Array数组，返回true，否则返回false。 | 351 352**错误码：** 353 354以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 355 356| 错误码ID | 错误信息 | 357| -------- | -------------------------------- | 358| 401 | Parameter error: Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 359 360**示例：** 361 362```ts 363let arr: collections.Array<string> = new collections.Array('a', 'b', 'c', 'd'); 364let result: boolean = collections.Array.isArray(arr); 365console.info(result + ''); // 预期输出： true 366``` 367 368## of<sup>18+</sup> 369 370static of\<T>(...items: T\[]): Array\<T> 371 372通过可变数量的参数创建一个新的ArkTS Array。 373 374**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 375 376**系统能力：** SystemCapability.Utils.Lang 377 378**参数：** 379 380| 参数名 | 类型 | 必填 | 说明 | 381| --------- | ------------- | ---- | ------------------------------- | 382| items | T[] | 否 | 用于创建数组的元素集合，参数个数可以是0个、1个或者多个。 | 383 384**返回值：** 385 386| 类型 | 说明 | 387| --------- | ----------------------- | 388| Array\<T> | 新的ArkTS Array实例。 | 389 390**错误码：** 391 392以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 393 394| 错误码ID | 错误信息 | 395| -------- | -------------------------------- | 396| 401 | Parameter error: Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 397 398**示例：** 399 400```ts 401let arr: collections.Array<string> = collections.Array.of('a', 'b', 'c', 'd'); 402console.info(arr.toString()); // 预期输出： a, b, c, d 403``` 404 405## copyWithin<sup>18+</sup> 406copyWithin(target: number, start: number, end?: number): Array\<T> 407 408从ArkTS Array指定范围内的元素依次拷贝到目标位置。 409 410**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 411 412**系统能力：** SystemCapability.Utils.Lang 413 414**参数：** 415 416| 参数名 | 类型 | 必填 | 说明 | 417| ------- | ------ | ---- | ------------------------------------------------------------ | 418| target | number | 是 | 目标起始位置的下标，如果`target < 0`，则会从`target + array.length`位置开始。 | 419| start | number | 是 | 源起始位置下标，如果`start < 0`，则会从`start + array.length`位置开始。 | 420| end | number | 否 | 源终止位置下标，如果`end < 0`，则会从`end + array.length`位置终止。默认为ArkTS Array的长度。| 421 422**返回值：** 423 424| 类型 | 说明 | 425| ------------ | --------- | 426| Array\<T> | 修改后的Array。 | 427 428**错误码：** 429 430以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 431 432| 错误码ID | 错误信息 | 433| -------- | ------------------------------------------------ | 434| 401 | Parameter error: Possible causes: 1. Mandatory parameters are left unspecified;2. Incorrect parameter types; 3. Parameter verification failed. | 435| 10200011 | The copyWithin method cannot be bound. | 436| 10200201 | Concurrent modification error. | 437 438**示例：** 439 440```ts 441let array: collections.Array<number> = collections.Array.from([1, 2, 3, 4, 5, 6, 7, 8]); 442let copied: collections.Array<number> = array.copyWithin(3, 1, 3); 443console.info(copied.toString()); // 预期输出： 1, 2, 3, 2, 3, 6, 7, 8 444``` 445 446## lastIndexOf<sup>18+</sup> 447 448lastIndexOf(searchElement: T, fromIndex?: number): number 449 450返回ArkTS Array实例中最后一次出现searchElement的索引，如果对象不包含，则为-1。 451 452**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 453 454**系统能力：** SystemCapability.Utils.Lang 455 456**参数：** 457 458| 参数名 | 类型 | 必填 | 说明 | 459| ------------- | ------ | --- | --------------------------------------------------------------------------------- | 460| searchElement | T | 是 | 待索引的值。 | 461| fromIndex | number | 否 | 搜索的起始下标。默认值为0。如果下标大于等于ArkTS Array的长度，则返回-1。如果提供的下标值是负数，则从数组末尾开始倒数计数：使用 fromIndex + array.length 的值。 | 462 463**返回值：** 464 465| 类型 | 说明 | 466| ------ | ----------------------- | 467| number | 数组中元素的最后一个索引；没有找到，则返回-1。 | 468 469**错误码：** 470 471以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 472 473| 错误码ID | 错误信息 | 474| -------- | --------------------------------------- | 475| 10200011 | The lastIndexOf method cannot be bound. | 476| 10200201 | Concurrent modification error. | 477 478**示例：** 479 480```ts 481let array: collections.Array<number> = collections.Array.from([3, 5, 9]); 482console.info(array.lastIndexOf(3) + ''); // 预期输出： 0 483console.info(array.lastIndexOf(7) + ''); // 预期输出： -1 484console.info(array.lastIndexOf(9, 2) + ''); // 预期输出： 2 485console.info(array.lastIndexOf(9, -2) + ''); // 预期输出： -1 486``` 487 488## some<sup>18+</sup> 489some(predicate: ArrayPredicateFn\<T, Array\<T>>): boolean 490 491测试ArkTS Array是否存在满足指定条件的元素。 492 493**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 494 495**系统能力：** SystemCapability.Utils.Lang 496 497**参数：** 498 499| 参数名 | 类型 | 必填 | 说明 | 500| ------- | ------ | ---- | ---------------------------------------------------- | 501| predicate | [ArrayPredicateFn](arkts-apis-arkts-collections-Types.md#arraypredicatefn18)\<T, Array\<T>> | 是 | 用于测试的断言函数。| 502 503**返回值：** 504 505| 类型 | 说明 | 506| ------------ | --------- | 507| boolean | 如果存在元素满足指定条件返回true，否则返回false。| 508 509**错误码：** 510 511以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 512 513| 错误码ID | 错误信息 | 514| -------- | ---------------------------------- | 515| 10200011 | The some method cannot be bound. | 516| 10200201 | Concurrent modification error. | 517 518**示例：** 519 520```ts 521let newArray: collections.Array<number> = collections.Array.from([-10, 20, -30, 40, -50]); 522console.info(newArray.some((element: number) => element < 0) + ''); // 预期输出： true 523``` 524 525## reduceRight<sup>18+</sup> 526 527reduceRight(callbackFn: ArrayReduceCallback\<T, T, Array\<T>>): T 528 529对Array中的每个元素按照从右到左顺序执行回调函数，将其结果作为累加值，并返回最终的结果。 530 531**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 532 533**系统能力：** SystemCapability.Utils.Lang 534 535**参数：** 536 537| 参数名 | 类型 | 必填 | 说明 | 538| ---------- | -------------------------------------------------------------------------------- | --- | ------------------------------------------ | 539| callbackFn | [ArrayReduceCallback](arkts-apis-arkts-collections-Types.md#arrayreducecallback18)\<T, T, Array\<T>> | 是 | 一个接受四个参数的函数，用于对每个元素执行操作，并将结果作为累加值传递给下一个元素。 | 540 541**返回值：** 542 543| 类型 | 说明 | 544| --- | ------------- | 545| T | 回调函数执行后的最终结果。 | 546 547**错误码：** 548 549以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 550 551| 错误码ID | 错误信息 | 552| -------- | --------------------------------------- | 553| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 554| 10200011 | The reduceRight method cannot be bound. | 555| 10200201 | Concurrent modification error. | 556 557**示例：** 558 559```ts 560let array = new collections.Array<number>(1, 2, 3, 4, 5); 561let reducedValue = array.reduceRight((accumulator, value) => accumulator + value); // 累加所有元素 562console.info(reducedValue + ''); // 预期输出： 15 563``` 564 565## reduceRight<sup>18+</sup> 566 567reduceRight\<U = T>(callbackFn: ArrayReduceCallback\<U, T, Array\<T>>, initialValue: U): U 568 569与 [reduceRight](#reduceright18)方法类似，但它接受一个初始值作为第二个参数，用于在Array从右到左顺序遍历开始前初始化累加器。 570 571**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 572 573**系统能力：** SystemCapability.Utils.Lang 574 575**参数：** 576 577| 参数名 | 类型 | 必填 | 说明 | 578| ------------ | -------------------------------------------------------------------------------------------- | --- | ------------------------------------------ | 579| callbackFn | [ArrayReduceCallback](arkts-apis-arkts-collections-Types.md#arrayreducecallback18)\<U, T, Array\<T>> | 是 | 一个接受四个参数的函数，用于对每个元素执行操作，并将结果作为累加值传递给下一个元素。 | 580| initialValue | U | 是 | 用于初始化累加器的值。 | 581 582**返回值：** 583 584| 类型 | 说明 | 585| --- | ------------- | 586| U | 回调函数执行后的最终结果。 | 587 588**错误码：** 589 590以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 591 592| 错误码ID | 错误信息 | 593| -------- | --------------------------------------- | 594| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 595| 10200011 | The reduceRight method cannot be bound. | 596| 10200201 | Concurrent modification error. | 597 598**示例：** 599 600```ts 601// 此处使用一个初始值为0的累加器，并将其与Array中的每个元素相加，最终返回累加后的总和 602let array = new collections.Array<number>(1, 2, 3, 4, 5); 603let reducedValue = array.reduceRight<number>((accumulator: number, value: number) => accumulator + value, 0); // 累加所有元素，初始值为0 604console.info(reducedValue + ''); // 预期输出： 15 605``` 606 607## pop 608 609pop(): T | undefined 610 611从ArkTS Array中移除并返回最后一个元素。如果Array为空，则返回undefined，且Array不发生变化。 612 613**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 614 615**系统能力：** SystemCapability.Utils.Lang 616 617**返回值：** 618 619| 类型 | 说明 | 620| -------------- | --------------------------------------------------- | 621| T \| undefined | 从Array中移除的元素；如果Array为空，则返回undefined。 | 622 623**错误码：** 624 625以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 626 627| 错误码ID | 错误信息 | 628| -------- | ------------------------------- | 629| 10200011 | The pop method cannot be bound. | 630| 10200201 | Concurrent modification error. | 631 632**示例：** 633 634```ts 635let array = new collections.Array<number>(1, 2, 3); 636let lastElement = array.pop(); // 返回3，Array变为[1, 2] 637``` 638 639## push 640 641push(...items: T[]): number 642 643在ArkTS Array的末尾添加元素，并返回新的Array长度。 644 645**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 646 647**系统能力：** SystemCapability.Utils.Lang 648 649**参数：** 650 651| 参数名 | 类型 | 必填 | 说明 | 652| ------ | ---- | ---- | ---------------------------------- | 653| items | T[] | 否 | 要添加到Array末尾的元素。 | 654 655**返回值：** 656 657| 类型 | 说明 | 658| ------ | ------------------ | 659| number | 返回新Array的长度。 | 660 661**错误码：** 662 663以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 664 665| 错误码ID | 错误信息 | 666| -------- | -------------------------------- | 667| 401 | Parameter error. | 668| 10200011 | The push method cannot be bound. | 669| 10200201 | Concurrent modification error. | 670 671**示例：** 672 673```ts 674let array = new collections.Array<number>(1, 2, 3); 675let length = array.push(4, 5); // 返回5，Array变为[1, 2, 3, 4, 5] 676``` 677 678## join 679 680join(separator?: string): string 681 682将ArkTS Array的所有元素连接成一个字符串，元素之间可以用指定的分隔符分隔。 683 684**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 685 686**系统能力：** SystemCapability.Utils.Lang 687 688**参数：** 689 690| 参数名 | 类型 | 必填 | 说明 | 691| --------- | ------ | ---- | ---------------------------------------------------- | 692| separator | string | 否 | 用于分隔Array元素的字符串。如果省略，则使用逗号分隔。 | 693 694**返回值：** 695 696| 类型 | 说明 | 697| ------ | ------------------------------------------------------------ | 698| string | 包含所有Array元素连接成的字符串。如果Array为空，则返回空字符串。 | 699 700**错误码：** 701 702以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 703 704| 错误码ID | 错误信息 | 705| -------- | -------------------------------- | 706| 401 | Parameter error. | 707| 10200011 | The join method cannot be bound. | 708| 10200201 | Concurrent modification error. | 709 710**示例：** 711 712```ts 713let array = new collections.Array<string>('a', 'b', 'c'); 714let joinedString = array.join('-'); // 返回 "a-b-c" 715``` 716 717## shift 718 719shift(): T | undefined 720 721从ArkTS Array中移除并返回第一个元素。如果Array为空，则返回undefined，且Array不发生变化。 722 723**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 724 725**系统能力：** SystemCapability.Utils.Lang 726 727**返回值：** 728 729| 类型 | 说明 | 730| -------------- | --------------------------------------------------- | 731| T \| undefined | 从Array中移除的元素；如果Array为空，则返回undefined。 | 732 733**错误码：** 734 735以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 736 737| 错误码ID | 错误信息 | 738| -------- | --------------------------------- | 739| 10200011 | The shift method cannot be bound. | 740| 10200201 | Concurrent modification error. | 741 742**示例：** 743 744```ts 745let array = new collections.Array<number>(1, 2, 3); 746let firstElement = array.shift(); // 返回1，Array变为[2, 3] 747``` 748 749## reverse<sup>18+</sup> 750 751reverse(): Array\<T> 752 753反转ArkTS Array数组中的元素，并返回同一数组的引用。 754 755**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 756 757**系统能力：** SystemCapability.Utils.Lang 758 759**返回值：** 760 761| 类型 | 说明 | 762| ----- | ------------------ | 763| Array\<T> | 反转后的ArkTS Array对象。 | 764 765**错误码：** 766 767以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 768 769| 错误码ID | 错误信息 | 770| -------- | ----------------------------------- | 771| 10200011 | The reverse method cannot be bound. | 772| 10200201 | Concurrent modification error. | 773 774**示例：** 775 776```ts 777let array = new collections.Array<number>(1, 2, 3, 4, 5); 778let reversed = array.reverse(); 779console.info(array.toString()); // 预期输出： 5, 4, 3, 2, 1 780``` 781 782## unshift 783 784unshift(...items: T[]): number 785 786在ArkTS Array的首端插入元素，并返回新的Array长度。 787 788**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 789 790**系统能力：** SystemCapability.Utils.Lang 791 792**参数：** 793 794| 参数名 | 类型 | 必填 | 说明 | 795| ------ | ---- | ---- | ------------------------ | 796| items | T[] | 否 | 要插入到Array首端的元素。 | 797 798**返回值：** 799 800| 类型 | 说明 | 801| ------ | -------------- | 802| number | 新Array的长度。 | 803 804**错误码：** 805 806以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 807 808| 错误码ID | 错误信息 | 809| -------- | ----------------------------------- | 810| 401 | Parameter error. | 811| 10200011 | The unshift method cannot be bound. | 812| 10200201 | Concurrent modification error. | 813 814**示例：** 815 816```ts 817let array = new collections.Array<number>(1, 2, 3); 818let newLength = array.unshift(0); // 返回4，Array变为[0, 1, 2, 3] 819``` 820 821## toString<sup>18+</sup> 822 823toString(): string 824 825ArkTS数组转换为字符串。 826 827**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 828 829**系统能力：** SystemCapability.Utils.Lang 830 831**返回值：** 832 833| 类型 | 说明 | 834| ---------- | ------------- | 835| string | 一个包含数组所有元素的字符串。 | 836 837**错误码：** 838 839以下错误码详细介绍请参考[语言基础类库错误码](errorcode-utils.md)。 840 841| 错误码ID | 错误信息 | 842| -------- | ------------------------------------ | 843| 10200011 | The toString method cannot be bound. | 844| 10200201 | Concurrent modification error. | 845 846**示例：** 847 848```ts 849let array = new collections.Array<number>(1, 2, 3, 4, 5); 850let stringArray = array.toString(); 851console.info(stringArray); // 预期输出：1,2,3,4,5 852``` 853 854## slice 855 856slice(start?: number, end?: number): Array\<T> 857 858返回一个新的Array，该Array是原始ArkTS Array的切片。 859 860**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 861 862**系统能力：** SystemCapability.Utils.Lang 863 864**参数：** 865| 参数名 | 类型 | 必填 | 说明 | 866| ------ | ------ | ---- | ------------------------------------------------------------ | 867| start | number | 否 | 开始索引。如果`start < 0`，则会从`start + array.length`位置开始。默认值为0。 | 868| end | number | 否 | 结束索引（不包括该元素）。如果`end < 0`，则会到`end + array.length`位置结束。默认为原始ArkTS Array的长度。 | 869 870**返回值：** 871 872| 类型 | 说明 | 873| --------- | -------------------------- | 874| Array\<T> | 包含原始Array切片的新Array。 | 875 876**错误码：** 877 878以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 879 880| 错误码ID | 错误信息 | 881| -------- | --------------------------------- | 882| 401 | Parameter error. | 883| 10200011 | The slice method cannot be bound. | 884| 10200201 | Concurrent modification error. | 885 886**示例：** 887 888```ts 889let array = new collections.Array<number>(1, 2, 3, 4, 5); 890let slicedArray = array.slice(1, 3); // 返回[2, 3]，Array保持不变 891``` 892 893## sort 894 895sort(compareFn?: (a: T, b: T) => number): Array\<T> 896 897对ArkTS Array进行排序，并返回排序后的Array。 898 899**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 900 901**系统能力：** SystemCapability.Utils.Lang 902 903**参数：** 904 905| 参数名 | 类型 | 必填 | 说明 | 906| --------- | ---------------------- | ---- | ------------------------------------------ | 907| compareFn | (a: T, b: T) => number | 否 | 用于确定元素顺序的函数。默认使用升序排序。 | 908 909**返回值：** 910 911| 类型 | 说明 | 912| --------- | -------------- | 913| Array\<T> | 排序后的Array。 | 914 915**错误码：** 916 917以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 918 919| 错误码ID | 错误信息 | 920| -------- | -------------------------------- | 921| 401 | Parameter error. | 922| 10200011 | The sort method cannot be bound. | 923| 10200201 | Concurrent modification error. | 924 925**示例：** 926 927```ts 928let array = new collections.Array<number>(1, 3, 5, 4, 2); 929array.sort((a: number, b: number) => a - b); // [1, 2, 3, 4, 5] 930array.sort((a: number, b: number) => b - a); // [5, 4, 3, 2, 1] 931``` 932 933## indexOf 934 935indexOf(searchElement: T, fromIndex?: number): number 936 937返回在ArkTS Array中搜索元素首次出现的索引，如果不存在则返回-1。 938 939**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 940 941**系统能力：** SystemCapability.Utils.Lang 942 943**参数：** 944 945| 参数名 | 类型 | 必填 | 说明 | 946| ------------- | ------ | ---- | --------------------------- | 947| searchElement | T | 是 | 要搜索的值。 | 948| fromIndex | number | 否 | 开始搜索的索引，从0开始，默认值为0。 | 949 950**返回值：** 951 952| 类型 | 说明 | 953| ------ | ---------------------------------------------- | 954| number | 搜索元素首次出现的索引；如果不存在，则返回-1。 | 955 956**错误码：** 957 958以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 959 960| 错误码ID | 错误信息 | 961| -------- | ----------------------------------- | 962| 401 | Parameter error. | 963| 10200011 | The indexOf method cannot be bound. | 964| 10200201 | Concurrent modification error. | 965 966**示例：** 967 968```ts 969let array = new collections.Array<string>('a', 'b', 'c'); 970let index = array.indexOf('b'); // 返回1，因为'b'在索引1的位置 971``` 972 973## forEach 974 975forEach(callbackFn: (value: T, index: number, array: Array\<T>) => void): void 976 977对Array中的每个元素执行提供的回调函数。 978 979**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 980 981**系统能力：** SystemCapability.Utils.Lang 982 983**参数：** 984 985| 参数名 | 类型 | 必填 | 说明 | 986| ---------- | --------------------------------------------------- | ---- | ------------------------------ | 987| callbackFn | (value: T, index: number, array: Array\<T>) => void | 是 | 用于对每个元素执行的回调函数。 | 988 989**错误码：** 990 991以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 992 993| 错误码ID | 错误信息 | 994| -------- | ----------------------------------- | 995| 401 | Parameter error. | 996| 10200011 | The forEach method cannot be bound. | 997| 10200201 | Concurrent modification error. | 998 999**示例：** 1000 1001```ts 1002let array = new collections.Array<string>('a', 'b', 'c'); 1003array.forEach((value, index, array) => { 1004 console.info(`Element ${value} at index ${index}`); 1005}); 1006``` 1007 1008## map 1009 1010map\<U>(callbackFn: (value: T, index: number, array: Array\<T>) => U): Array\<U> 1011 1012对Array中的每个元素执行提供的回调函数，并返回一个新的Array，该Array包含回调函数的结果。 1013 1014**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1015 1016**系统能力：** SystemCapability.Utils.Lang 1017 1018**参数：** 1019 1020| 参数名 | 类型 | 必填 | 说明 | 1021| ---------- | ------------------------------------------------ | ---- | ------------------------------ | 1022| callbackFn | (value: T, index: number, array: Array\<T>) => U | 是 | 用于对每个元素执行的回调函数。 | 1023 1024**返回值：** 1025 1026| 类型 | 说明 | 1027| --------- | -------------------------- | 1028| Array\<U> | 包含回调函数结果的新Array。 | 1029 1030**错误码：** 1031 1032以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1033 1034| 错误码ID | 错误信息 | 1035| -------- | ------------------------------- | 1036| 401 | Parameter error. | 1037| 10200011 | The map method cannot be bound. | 1038| 10200201 | Concurrent modification error. | 1039 1040**示例：** 1041 1042```ts 1043// 此处将原始Array中的每个字符串元素转换为大写形式，并返回一个新Array，其中包含转换后的字符串 1044let array = new collections.Array<string>('a', 'b', 'c'); 1045let mappedArray = array.map((value, index, array) => { 1046 return value.toUpperCase(); // 将每个字符串元素转换为大写 1047}); 1048console.info("" + mappedArray); // 输出: A, B, C 1049``` 1050 1051## filter 1052 1053filter(predicate: (value: T, index: number, array: Array\<T>) => boolean): Array\<T> 1054 1055返回一个新Array，其中包含通过指定回调函数测试的所有元素。 1056 1057**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1058 1059**系统能力：** SystemCapability.Utils.Lang 1060 1061**参数：** 1062 1063| 参数名 | 类型 | 必填 | 说明 | 1064| --------- | ------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1065| predicate | (value: T, index: number, array: Array\<T>) => boolean | 是 | 一个接受三个参数的函数，用于测试每个元素是否应该包含在新Array中。当返回值为true时表示当前元素通过测试，需被保留在新数组中。为false时表示当前元素未通过测试，需被排除在新数组外。 | 1066 1067**返回值：** 1068 1069| 类型 | 说明 | 1070| --------- | ---------------------------- | 1071| Array\<T> | 包含通过测试的元素的新Array。 | 1072 1073**错误码：** 1074 1075以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1076 1077| 错误码ID | 错误信息 | 1078| -------- | ---------------------------------- | 1079| 401 | Parameter error. | 1080| 10200011 | The filter method cannot be bound. | 1081| 10200201 | Concurrent modification error. | 1082 1083**示例：** 1084 1085```ts 1086let array = new collections.Array<number>(1, 2, 3, 4, 5); 1087let filteredArray = array.filter((value : number) => value % 2 === 0); // 返回[2, 4]，只包含偶数 1088``` 1089 1090## reduce 1091 1092reduce(callbackFn: (previousValue: T, currentValue: T, currentIndex: number, array: Array\<T>) => T): T 1093 1094对Array中的每个元素执行回调函数，将其结果作为累加值，并返回最终的结果。 1095 1096**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1097 1098**系统能力：** SystemCapability.Utils.Lang 1099 1100**参数：** 1101 1102| 参数名 | 类型 | 必填 | 说明 | 1103| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1104| callbackFn | (previousValue: T, currentValue: T, currentIndex: number, array: Array\<T>) => T | 是 | 一个接受四个参数的函数，用于对每个元素执行操作，并将结果作为累加值传递给下一个元素。 | 1105 1106**返回值：** 1107 1108| 类型 | 说明 | 1109| ---- | -------------------------- | 1110| T | 回调函数执行后的最终结果。 | 1111 1112**错误码：** 1113 1114以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1115 1116| 错误码ID | 错误信息 | 1117| -------- | ---------------------------------- | 1118| 401 | Parameter error. | 1119| 10200011 | The reduce method cannot be bound. | 1120| 10200201 | Concurrent modification error. | 1121 1122**示例：** 1123 1124```ts 1125let array = new collections.Array<number>(1, 2, 3, 4, 5); 1126let reducedValue = array.reduce((accumulator, value) => accumulator + value); // 返回15，累加所有元素 1127``` 1128 1129## reduce 1130 1131reduce\<U>(callbackFn: (previousValue: U, currentValue: T, currentIndex: number, array: Array\<T>) => U, initialValue: U): U 1132 1133与 reduce方法类似，但它接受一个初始值作为第二个参数，用于在Array遍历开始前初始化累加器。 1134 1135**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1136 1137**系统能力：** SystemCapability.Utils.Lang 1138 1139**参数：** 1140 1141| 参数名 | 类型 | 必填 | 说明 | 1142| ------------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 1143| callbackFn | (previousValue: U, currentValue: T, currentIndex: number, array: Array\<T>) => U | 是 | 一个接受四个参数的函数，用于对每个元素执行操作，并将结果作为累加值传递给下一个元素。 | 1144| initialValue | U | 是 | 用于初始化累加器的值。 | 1145 1146**返回值：** 1147 1148| 类型 | 说明 | 1149| ---- | -------------------------- | 1150| U | 回调函数执行后的最终结果。 | 1151 1152**错误码：** 1153 1154以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1155 1156| 错误码ID | 错误信息 | 1157| -------- | ---------------------------------- | 1158| 401 | Parameter error. | 1159| 10200011 | The reduce method cannot be bound. | 1160| 10200201 | Concurrent modification error. | 1161 1162**示例：** 1163 1164```ts 1165// 此处使用一个初始值为0的累加器，并将其与Array中的每个元素相加，最终返回累加后的总和 1166let array = new collections.Array(1, 2, 3, 4, 5); 1167let reducedValue = array.reduce<number>((accumulator: number, value: number) => accumulator + value, 0); // 返回15，累加所有元素，初始值为0 1168``` 1169 1170## at 1171 1172at(index: number): T | undefined 1173 1174返回Array中指定索引位置的元素。 1175 1176**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1177 1178**系统能力：** SystemCapability.Utils.Lang 1179 1180**参数：** 1181 1182| 参数名 | 类型 | 必填 | 说明 | 1183| ------ | ------ | ---- | ------------------------------------------------------------ | 1184| index | number | 是 | 要返回的Array元素的索引（从零开始），取值为整数。负数索引从Array末尾开始计数，如果`index < 0`，则会访问`index + array.length`位置的元素。 | 1185 1186 1187**返回值：** 1188 1189| 类型 | 说明 | 1190| -------------- | ------------------------------------------------------------ | 1191| T \| undefined | 返回指定索引处的元素；如果索引超出范围或无效，则返回undefined。 | 1192 1193**错误码：** 1194 1195以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1196 1197| 错误码ID | 错误信息 | 1198| -------- | ------------------------------ | 1199| 401 | Parameter error. | 1200| 10200011 | The at method cannot be bound. | 1201| 10200201 | Concurrent modification error. | 1202 1203**示例：** 1204 1205```ts 1206let array = new collections.Array<number>(1, 2, 3, 4, 5); 1207let elementAtIndex = array.at(2); // 返回3，因为索引是从0开始的 1208``` 1209 1210## entries 1211 1212entries(): IterableIterator<[number, T]> 1213 1214返回一个新的可迭代对象，该对象包含Array中每个元素的键值对。 1215 1216**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1217 1218**系统能力：** SystemCapability.Utils.Lang 1219 1220**返回值：** 1221 1222| 类型 | 说明 | 1223| ----------------------------- | ------------------------------------------ | 1224| IterableIterator<[number, T]> | 包含Array中每个元素的键值对的迭代器。 | 1225 1226**错误码：** 1227 1228以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 1229 1230| 错误码ID | 错误信息 | 1231| -------- | ----------------------------------- | 1232| 10200011 | The entries method cannot be bound. | 1233| 10200201 | Concurrent modification error. | 1234 1235**示例：** 1236 1237```ts 1238let array = new collections.Array<number>(1, 2, 3, 4, 5); 1239let iterator = array.entries(); 1240console.info(iterator.next().value); // 输出：[0, 1]，第一个元素的键值对 1241``` 1242 1243## keys 1244 1245keys(): IterableIterator\<number> 1246 1247返回一个新的可迭代对象，该对象包含Array中每个元素的索引。 1248 1249**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1250 1251**系统能力：** SystemCapability.Utils.Lang 1252 1253**返回值：** 1254 1255| 类型 | 说明 | 1256| ------------------------- | -------------------------------------- | 1257| IterableIterator\<number> | 包含Array中每个元素的索引的可迭代迭代器。 | 1258 1259**错误码：** 1260 1261以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 1262 1263| 错误码ID | 错误信息 | 1264| -------- | -------------------------------- | 1265| 10200011 | The keys method cannot be bound. | 1266| 10200201 | Concurrent modification error. | 1267 1268**示例：** 1269 1270```ts 1271let array = new collections.Array<number>(1, 2, 3, 4, 5); 1272let iterator = array.keys(); 1273for (const key of iterator) { 1274 console.info("" + key); // 依次输出 0,1,2,3,4 1275} 1276``` 1277 1278## values 1279 1280values(): IterableIterator\<T> 1281 1282返回一个新的可迭代对象，该对象包含Array中每个元素的值。 1283 1284**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1285 1286**系统能力：** SystemCapability.Utils.Lang 1287 1288**返回值：** 1289 1290| 类型 | 说明 | 1291| -------------------- | -------------------------------------- | 1292| IterableIterator\<T> | 包含Array中每个元素的值的可迭代迭代器。 | 1293 1294**错误码：** 1295 1296以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 1297 1298| 错误码ID | 错误信息 | 1299| -------- | ---------------------------------- | 1300| 10200011 | The values method cannot be bound. | 1301| 10200201 | Concurrent modification error. | 1302 1303**示例：** 1304 1305```ts 1306let array = new collections.Array<number>(1, 2, 3, 4, 5); 1307let iterator = array.values(); 1308for(const value of iterator) { 1309 console.info("" + value); // 依次输出 1,2,3,4,5 1310} 1311``` 1312 1313## find 1314 1315find(predicate: (value: T, index: number, obj: Array\<T>) => boolean): T | undefined 1316 1317返回Array中第一个满足指定测试函数的元素的值，如果所有元素都不满足，则返回undefined。 1318 1319**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1320 1321**系统能力：** SystemCapability.Utils.Lang 1322 1323**参数：** 1324 1325| 参数名 | 类型 | 必填 | 说明 | 1326| --------- | ---------------------------------------------------- | ---- | ------------------------------------------------------ | 1327| predicate | (value: T, index: number, obj: Array\<T>) => boolean | 是 | 一个接受三个参数的函数，用于测试每个元素是否满足条件。当返回值为true时表示元素满足条件，会立即停止遍历，并将该元素作为结果返回。为false时表示元素不满足条件，会继续检查下一个元素，直到找到符合条件的元素或遍历完整个数组。 | 1328 1329**返回值：** 1330 1331| 类型 | 说明 | 1332| -------------- | ------------------------------------------------------------ | 1333| T \| undefined | 第一个满足条件的元素的值；如果所有元素都不满足条件，则返回undefined。 | 1334 1335**错误码：** 1336 1337以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1338 1339| 错误码ID | 错误信息 | 1340| -------- | -------------------------------- | 1341| 401 | Parameter error. | 1342| 10200011 | The find method cannot be bound. | 1343| 10200201 | Concurrent modification error. | 1344 1345**示例：** 1346 1347```ts 1348let array = new collections.Array<number>(1, 2, 3, 4, 5); 1349let foundValue = array.find((value: number) => value % 2 === 0); // 返回2，第一个偶数元素 1350``` 1351 1352## includes 1353 1354includes(searchElement: T, fromIndex?: number): boolean 1355 1356判断Array是否包含指定的元素，并返回一个布尔值。 1357 1358**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1359 1360**系统能力：** SystemCapability.Utils.Lang 1361 1362**参数：** 1363 1364| 参数名 | 类型 | 必填 | 说明 | 1365| ------------- | ------ | ---- | --------------------------- | 1366| searchElement | T | 是 | 要搜索的元素。 | 1367| fromIndex | number | 否 | 开始搜索的索引。默认值为0。 | 1368 1369**返回值：** 1370 1371| 类型 | 说明 | 1372| ------- | --------------------------------------------------- | 1373| boolean | 如果Array包含指定的元素，则返回true；否则返回false。 | 1374 1375**错误码：** 1376 1377以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1378 1379| 错误码ID | 错误信息 | 1380| -------- | ------------------------------------ | 1381| 401 | Parameter error. | 1382| 10200011 | The includes method cannot be bound. | 1383| 10200201 | Concurrent modification error. | 1384 1385**示例：** 1386 1387```ts 1388let array = new collections.Array<number>(1, 2, 3, 4, 5); 1389let includesResult = array.includes(3); // 返回true，因为Array中包含3 1390``` 1391 1392## findIndex 1393 1394findIndex(predicate: (value: T, index: number, obj: Array\<T>) => boolean): number 1395 1396返回Array中第一个满足指定测试函数的元素的索引，如果所有元素都不满足，则返回-1。 1397 1398**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1399 1400**系统能力：** SystemCapability.Utils.Lang 1401 1402**参数：** 1403 1404| 参数名 | 类型 | 必填 | 说明 | 1405| --------- | ---------------------------------------------------- | ---- | ------------------------------------------------------ | 1406| predicate | (value: T, index: number, obj: Array\<T>) => boolean | 是 | 一个接受三个参数的函数，用于测试每个元素是否满足条件。当返回值为true时表示当前元素满足条件，会立即停止遍历，并返回该元素的索引。为false时表示当前元素不满足条件，会继续检查下一个元素，直到找到符合条件的元素或遍历完整个数组。 | 1407 1408**返回值：** 1409 1410| 类型 | 说明 | 1411| ------ | ------------------------------------------------------------ | 1412| number | 第一个满足条件的元素的索引；如果所有元素都不满足条件，则返回-1。 | 1413 1414**错误码：** 1415 1416以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1417 1418| 错误码ID | 错误信息 | 1419| -------- | ------------------------------------- | 1420| 401 | Parameter error. | 1421| 10200011 | The findIndex method cannot be bound. | 1422| 10200201 | Concurrent modification error. | 1423 1424**示例：** 1425 1426```ts 1427let array = new collections.Array<number>(1, 2, 3, 4, 5); 1428let foundIndex = array.findIndex((value: number) => value % 2 === 0); // 返回1，因为2是第一个偶数元素 1429``` 1430 1431## fill 1432 1433fill(value: T, start?: number, end?: number): Array\<T> 1434 1435使用指定的值填充Array中指定范围的所有元素。 1436 1437**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1438 1439**系统能力：** SystemCapability.Utils.Lang 1440 1441**参数：** 1442 1443| 参数名 | 类型 | 必填 | 说明 | 1444| ------ | ------ | ---- | ------------------------------------------------------ | 1445| value | T | 是 | 要填充的值。 | 1446| start | number | 否 | 开始填充的索引。默认值为0。 | 1447| end | number | 否 | 结束填充的索引（不包括该元素）。如果省略，则填充到Array的最后一个元素。 | 1448 1449**返回值：** 1450 1451| 类型 | 说明 | 1452| --------- | -------------- | 1453| Array\<T> | 填充后的Array。 | 1454 1455**错误码：** 1456 1457以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1458 1459| 错误码ID | 错误信息 | 1460| -------- | -------------------------------- | 1461| 401 | Parameter error. | 1462| 10200011 | The fill method cannot be bound. | 1463| 10200201 | Concurrent modification error. | 1464 1465**示例：** 1466 1467```ts 1468let array = new collections.Array(1, 2, 3, 4, 5); 1469array.fill(0, 1, 3); // 返回[1, 0, 0, 4, 5]，因为1到3的索引范围内的元素被替换为0 1470``` 1471 1472## shrinkTo 1473 1474shrinkTo(arrayLength: number): void 1475 1476使Array收缩到指定长度。 1477 1478**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1479 1480**系统能力：** SystemCapability.Utils.Lang 1481 1482**参数：** 1483 1484| 参数名 | 类型 | 必填 | 说明 | 1485| ------ | ------ | ---- | ------------------------------------------------------ | 1486| arrayLength | number | 是 | Array的新长度。如果arrayLength >= array.length，则Array不变。 | 1487 1488**错误码：** 1489 1490以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1491 1492| 错误码ID | 错误信息 | 1493| -------- | -------------------------------- | 1494| 401 | Parameter error. | 1495| 10200011 | The shrinkTo method cannot be bound. | 1496| 10200201 | Concurrent modification error. | 1497 1498**示例：** 1499 1500```ts 1501let array1 = new collections.Array(1, 2, 3, 4, 5); 1502array1.shrinkTo(1); // array内容变为：[1] 1503 1504let array2 = new collections.Array(1, 2, 3, 4, 5); 1505array2.shrinkTo(10); // array内容不变 1506``` 1507 1508## extendTo 1509 1510extendTo(arrayLength: number, initialValue: T): void 1511 1512使Array扩展到指定长度，扩展的部分使用给定值填充。 1513 1514**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1515 1516**系统能力：** SystemCapability.Utils.Lang 1517 1518**参数：** 1519 1520| 参数名 | 类型 | 必填 | 说明 | 1521| ------ | ------ | ---- | ------------------------------------------------------ | 1522| arrayLength | number | 是 | Array的新长度。如果arrayLength <= array.length，则Array不变。 | 1523| initialValue | T | 是 | 扩展的部分的填充值。 | 1524 1525**错误码：** 1526 1527以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1528 1529| 错误码ID | 错误信息 | 1530| -------- | -------------------------------- | 1531| 401 | Parameter error. | 1532| 10200011 | The extendTo method cannot be bound. | 1533| 10200201 | Concurrent modification error. | 1534 1535**示例：** 1536 1537```ts 1538let array1 = new collections.Array(1, 2, 3); 1539array1.extendTo(5, 10); // array内容变为：[1, 2, 3, 10, 10] 1540 1541let array2 = new collections.Array(1, 2, 3); 1542array2.extendTo(1, 10); // array内容不变 1543``` 1544 1545## concat 1546 1547concat(...items: ConcatArray\<T>[]): Array\<T> 1548 1549拼接两个或多个数组。 1550 1551**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1552 1553**系统能力：** SystemCapability.Utils.Lang 1554 1555**参数：** 1556 1557| 参数名 | 类型 | 必填 | 说明 | 1558| ------ | ---- | ---- | ---------------------------------- | 1559| items | ConcatArray\<T>[] | 否 | 拼接两个或多个数组。 | 1560 1561**返回值：** 1562 1563| 类型 | 说明 | 1564| ---- | ---------------------------------- | 1565| Array\<T> | 拼接后的数组。 | 1566 1567**错误码：** 1568 1569以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1570 1571| 错误码ID | 错误信息 | 1572| ------- | -------- | 1573| 401 | Parameter error. Not a valid array. | 1574| 10200011 | The concat method cannot be bound. | 1575| 10200201 | Concurrent modification error. | 1576 1577**示例：** 1578 1579```ts 1580let array = new collections.Array(1, 2, 3); 1581let array1 = new collections.Array(4, 5, 6); 1582let array2 = new collections.Array(7, 8, 9); 1583 1584let concatArray = array.concat(array1, array2); // concatArray的内容为：[1, 2, 3, 4, 5, 6, 7, 8, 9] 1585``` 1586 1587## splice 1588 1589splice(start: number): Array\<T> 1590 1591删除Array中指定位置的元素。 1592 1593**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1594 1595**系统能力：** SystemCapability.Utils.Lang 1596 1597**参数：** 1598 1599| 参数名 | 类型 | 必填 | 说明 | 1600| ----- | ------ | -- | ------------------------------------------------------------------- | 1601| start | number | 是 | 开始索引。如果`-array.length =< start < 0`，从`start + array.length`开始，如果`start < -array.length`，则从0开始。 | 1602 1603**返回值：** 1604 1605| 类型 | 说明 | 1606| --------- | --------------------- | 1607| Array\<T> | 返回一个新的包含被删除元素的Array对象。如果没有元素被删除，返回一个空的Array对象。 | 1608 1609**错误码：** 1610 1611以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1612 1613| 错误码ID | 错误信息 | 1614| -------- | ---------------------------------- | 1615| 401 | Parameter error. Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1616| 10200011 | The splice method cannot be bound. | 1617| 10200201 | Concurrent modification error. | 1618 1619**示例：** 1620 1621```ts 1622let array = new collections.Array<number>(1, 2, 3, 4, 5); 1623let removeArray = array.splice(2); // array内容变为[1, 2]，返回[3, 4, 5] 1624``` 1625 1626## every<sup>18+</sup> 1627 1628every(predicate: ArrayPredicateFn\<T, Array\<T>>): boolean 1629 1630测试ArkTS Array中的所有元素是否满足指定条件。 1631 1632**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1633 1634**系统能力：** SystemCapability.Utils.Lang 1635 1636**参数：** 1637| 参数名 | 类型 | 必填 | 说明 | 1638| ------- | ------ | ---- | ----------------------------------------------------- | 1639| predicate | [ArrayPredicateFn](arkts-apis-arkts-collections-Types.md#arraypredicatefn18)\<T, Array\<T>> | 是 | 用于测试的断言函数。| 1640 1641**返回值：** 1642 1643| 类型 | 说明 | 1644| ------------ | --------- | 1645| boolean | 如果所有元素都满足指定条件则返回true，否则返回false。| 1646 1647**错误码：** 1648 1649以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 1650 1651| 错误码ID | 错误信息 | 1652| -------- | ------------------------------------------------- | 1653| 10200011 | The every method cannot be bound. | 1654| 10200201 | Concurrent modification error. | 1655 1656**示例：** 1657 1658```ts 1659let newArray: collections.Array<number> = collections.Array.from([-10, 20, -30, 40, -50]); 1660console.info(newArray.every((element: number) => element > 0) + ''); // 预期输出：false 1661``` 1662 1663## toLocaleString<sup>18+</sup> 1664 1665toLocaleString(): string 1666 1667根据当前应用的系统地区获取符合当前文化习惯的字符串表示形式，让每个元素调用自己的toLocaleString方法转换为字符串，然后使用逗号将每个元素的结果字符串按照顺序拼接成字符串。 1668 1669**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 1670 1671**系统能力：** SystemCapability.Utils.Lang 1672 1673**返回值：** 1674 1675| 类型 | 说明 | 1676| ---------- | ------------- | 1677| string | 一个包含数组所有元素的字符串。 | 1678 1679**错误码：** 1680 1681以下错误码详细介绍请参考[语言基础类库错误码](errorcode-utils.md)。 1682 1683| 错误码ID | 错误信息 | 1684| -------- | ------------------------------------------ | 1685| 10200011 | The toLocaleString method cannot be bound. | 1686| 10200201 | Concurrent modification error. | 1687 1688**示例：** 1689 1690```ts 1691// 当前应用所在系统为法国地区 1692let array = new collections.Array<number | string>(1000, 'Test', 53621); 1693let stringArray = array.toLocaleString(); 1694console.info(stringArray); // 预期输出：1,000,Test,53,621 1695``` 1696 1697## splice 1698 1699splice(start: number, deleteCount: number, ...items: T[]): Array\<T> 1700 1701删除Array中指定位置的元素，需要时在Array的指定位置插入新元素。 1702 1703**原子化服务API**：从API version 12 开始，该接口支持在原子化服务中使用。 1704 1705**系统能力：** SystemCapability.Utils.Lang 1706 1707**参数：** 1708 1709| 参数名 | 类型 | 必填 | 说明 | 1710| ----------- | ------ | -- | ------------------------------------------------------------------- | 1711| start | number | 是 | 开始索引。如果`-array.length =< start < 0`，从`start + array.length`开始，如果`start < -array.length`，则从0开始。 | 1712| deleteCount | number | 是 | 删除元素的个数， 如果`deleteCount <= 0`，则不删除任何元素。 | 1713| items | T[] | 否 | 从`start`位置开始插入的新元素。如果省略，仅删除Array内的指定元素。 | 1714 1715**返回值：** 1716 1717| 类型 | 说明 | 1718| --------- | ------------------------------------ | 1719| Array\<T> | 返回一个新的包含被删除元素的Array对象。如果没有元素被删除，返回一个空的Array对象。 | 1720 1721**错误码：** 1722 1723以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1724 1725| 错误码ID | 错误信息 | 1726| -------- | ---------------------------------- | 1727| 401 | Parameter error. Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types. | 1728| 10200011 | The splice method cannot be bound. | 1729| 10200201 | Concurrent modification error. | 1730 1731**示例：** 1732 1733```ts 1734// 例1： 1735let array = new collections.Array<number>(1, 2, 3, 4, 5); 1736let removeArray = array.splice(2, 2); // array内容变为[1, 2, 5]，返回[3, 4] 1737``` 1738 1739```ts 1740// 例2： 1741let array = new collections.Array<number>(1, 2, 3, 4, 5); 1742let removeArray = array.splice(2, 2, 6, 7, 8); // array内容变为[1, 2, 6, 7, 8, 5]，返回[3, 4] 1743``` 1744 1745## [Symbol.iterator] 1746 1747[Symbol.iterator]\(): IterableIterator<T> 1748 1749返回一个迭代器，迭代器的每一项都是一个 JavaScript 对象，并返回该对象。 1750 1751> **说明：** 1752> 1753> 本接口不支持在.ets文件中使用。 1754 1755**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1756 1757**系统能力：** SystemCapability.Utils.Lang 1758 1759**返回值：** 1760 1761| 类型 | 说明 | 1762| ------------------------- | ---------------- | 1763| IterableIterator<T> | 返回一个迭代器。 | 1764 1765**错误码：** 1766 1767以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 1768 1769| 错误码ID | 错误信息 | 1770| -------- | ------------------------------------------- | 1771| 10200011 | The Symbol.iterator method cannot be bound. | 1772 1773**示例：** 1774 1775```ts 1776let array= new collections.Array<number>(1, 2, 3, 4); 1777 1778for (let item of array) { 1779 console.info(`value : ${item}`); 1780} 1781``` 1782 1783## [index: number] 1784 1785[index: number]: T 1786 1787返回Array指定索引位置的元素。 1788 1789**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1790 1791**系统能力：** SystemCapability.Utils.Lang 1792 1793**参数：** 1794 1795| 参数名 | 类型 | 必填 | 说明 | 1796| ----- | ------ | ---- | ------------------------------------------------------------------ | 1797| index | number | 是 | 所需代码单元的从零开始的索引。当index<0 或者index>=length，则会抛出错误。 | 1798 1799**返回值：** 1800 1801| 类型 | 说明 | 1802| ----- | ------------------------ | 1803| T | Array给定的元素数据类型。 | 1804 1805**错误码**： 1806 1807以下错误码详细介绍请参考[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1808 1809| 错误码ID | 错误信息 | 1810| ------- | ------------------------------------ | 1811| 401 | Parameter error. | 1812| 10200001 | The value of index is out of range. | 1813 1814**示例：** 1815 1816```ts 1817let array = new collections.Array<number>(1, 2, 4); 1818console.info("Element at index 1: ", array[1]); 1819``` 1820