1# @ohos.util.List (线性容器List) 2 3List底层通过单向链表实现，每个节点有一个指向后一个元素的引用。当需要查询元素时，必须从头遍历，插入、删除效率高，查询效率低。List允许元素为null。 4 5List和[LinkedList](js-apis-linkedlist.md)相比，LinkedList是双向链表，可以快速地在头尾进行增删，而List是单向链表，无法双向操作。 6 7**推荐使用场景：** 当需要频繁的插入删除时，推荐使用List高效操作。 8 9文档中存在泛型的使用，涉及以下泛型标记符：<br> 10- T：Type，类 11 12> **说明：** 13> 14> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15 16 17## 导入模块 18 19```ts 20import List from '@ohos.util.List'; 21``` 22 23 24## List 25 26### 属性 27 28**系统能力：** SystemCapability.Utils.Lang 29 30| 名称 | 类型 | 可读 | 可写 | 说明 | 31| -------- | -------- | -------- | -------- | -------- | 32| length | number | 是 | 否 | List的元素个数。 | 33 34 35### constructor 36 37constructor() 38 39List的构造函数。 40 41**系统能力：** SystemCapability.Utils.Lang 42 43**错误码：** 44 45以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 46 47| 错误码ID | 错误信息 | 48| -------- | -------- | 49| 10200012 | The List's constructor cannot be directly invoked. | 50 51**示例：** 52 53```ts 54let list: List<string | number | boolean | object> = new List(); 55``` 56 57 58### add 59 60add(element: T): boolean 61 62在List尾部插入元素。 63 64**系统能力：** SystemCapability.Utils.Lang 65 66**参数：** 67 68| 参数名 | 类型 | 必填 | 说明 | 69| -------- | -------- | -------- | -------- | 70| element | T | 是 | 添加进去的元素。 | 71 72**返回值：** 73 74| 类型 | 说明 | 75| -------- | -------- | 76| boolean | 插入成功返回true，否则返回false。 | 77 78**错误码：** 79 80以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 81 82| 错误码ID | 错误信息 | 83| -------- | -------- | 84| 10200011 | The add method cannot be bound. | 85 86**示例：** 87 88```ts 89let list: List<string | number | boolean | object> = new List(); 90let result1 = list.add("a"); 91let result2 = list.add(1); 92let b = [1, 2, 3]; 93let result3 = list.add(b); 94class C { 95 name: string = '' 96 age: string = '' 97} 98let c: C = {name : "Dylon", age : "13"}; 99let result4 = list.add(c); 100let result5 = list.add(false); 101``` 102 103### insert 104 105insert(element: T, index: number): void 106 107在长度范围内任意位置插入指定元素。 108 109**系统能力：** SystemCapability.Utils.Lang 110 111**参数：** 112 113| 参数名 | 类型 | 必填 | 说明 | 114| -------- | -------- | -------- | -------- | 115| element | T | 是 | 插入元素。 | 116| index | number | 是 | 插入的位置索引。 | 117 118**错误码：** 119 120以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 121 122| 错误码ID | 错误信息 | 123| -------- | -------- | 124| 10200011 | The insert method cannot be bound. | 125| 10200001 | The value of index is out of range. | 126 127**示例：** 128 129```ts 130let list: List<string | number | boolean> = new List(); 131list.insert("A", 0); 132list.insert(0, 1); 133list.insert(true, 2); 134``` 135 136### has 137 138has(element: T): boolean 139 140判断此List中是否含有该指定元素。 141 142**系统能力：** SystemCapability.Utils.Lang 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 说明 | 147| -------- | -------- | -------- | -------- | 148| element | T | 是 | 指定元素。 | 149 150**返回值：** 151 152| 类型 | 说明 | 153| -------- | -------- | 154| boolean | 包含指定元素返回true，否则返回false。 | 155 156**错误码：** 157 158以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 159 160| 错误码ID | 错误信息 | 161| -------- | -------- | 162| 10200011 | The has method cannot be bound. | 163 164**示例：** 165 166```ts 167let list: List<string> = new List(); 168list.add("squirrel"); 169let result = list.has("squirrel"); 170``` 171 172### get 173 174get(index: number): T 175 176根据下标获取List中的元素。 177 178**系统能力：** SystemCapability.Utils.Lang 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| -------- | -------- | -------- | -------- | 184| index | number | 是 | 要查找的下标。 | 185 186**返回值：** 187 188| 类型 | 说明 | 189| -------- | -------- | 190| T | 根据下标查找到的元素。 | 191 192**错误码：** 193 194以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 195 196| 错误码ID | 错误信息 | 197| -------- | -------- | 198| 10200011 | The get method cannot be bound. | 199 200**示例：** 201 202```ts 203let list: List<number> = new List(); 204list.add(2); 205list.add(4); 206list.add(5); 207list.add(2); 208list.add(1); 209list.add(2); 210list.add(4); 211let result = list.get(2); 212``` 213 214### getLastIndexOf 215 216getLastIndexOf(element: T): number 217 218查找指定元素最后一次出现的下标值，查找失败返回-1。 219 220**系统能力：** SystemCapability.Utils.Lang 221 222**参数：** 223 224| 参数名 | 类型 | 必填 | 说明 | 225| -------- | -------- | -------- | -------- | 226| element | T | 是 | 指定元素。 | 227 228**返回值：** 229 230| 类型 | 说明 | 231| -------- | -------- | 232| number | 返回指定元素最后一次出现的下标值，没有找到返回-1。 | 233 234**错误码：** 235 236以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 237 238| 错误码ID | 错误信息 | 239| -------- | -------- | 240| 10200011 | The getLastIndexOf method cannot be bound. | 241 242**示例：** 243 244```ts 245let list: List<number> = new List(); 246list.add(2); 247list.add(4); 248list.add(5); 249list.add(2); 250list.add(1); 251list.add(2); 252list.add(4); 253let result = list.getLastIndexOf(2); 254``` 255 256### getIndexOf 257 258getIndexOf(element: T): number 259 260查找指定元素第一次出现的下标值，查找失败返回-1。 261 262**系统能力：** SystemCapability.Utils.Lang 263 264**参数：** 265 266| 参数名 | 类型 | 必填 | 说明 | 267| -------- | -------- | -------- | -------- | 268| element | T | 是 | 指定元素。 | 269 270**返回值：** 271 272| 类型 | 说明 | 273| -------- | -------- | 274| number | 返回第一次找到指定元素的下标，没有找到返回-1。 | 275 276**错误码：** 277 278以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 279 280| 错误码ID | 错误信息 | 281| -------- | -------- | 282| 10200011 | The getIndexOf method cannot be bound. | 283 284**示例：** 285 286```ts 287let list: List<number> = new List(); 288list.add(2); 289list.add(4); 290list.add(5); 291list.add(2); 292list.add(1); 293list.add(2); 294list.add(4); 295let result = list.getIndexOf(2); 296``` 297 298### equal 299 300equal(obj: Object): boolean 301 302比较指定对象与此List是否相等。 303 304**系统能力：** SystemCapability.Utils.Lang 305 306**参数：** 307 308| 参数名 | 类型 | 必填 | 说明 | 309| -------- | -------- | -------- | -------- | 310| obj | Object | 是 | 用来比较的对象。 | 311 312**返回值：** 313 314| 类型 | 说明 | 315| -------- | -------- | 316| boolean | 如果对象与此列表相同返回true，否则返回false。 | 317 318**错误码：** 319 320以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 321 322| 错误码ID | 错误信息 | 323| -------- | -------- | 324| 10200011 | The equal method cannot be bound. | 325 326**示例：** 327 328```ts 329let list: List<number> = new List(); 330list.add(2); 331list.add(4); 332list.add(5); 333let obj: List<number> = new List(); 334obj.add(2); 335obj.add(4); 336obj.add(5); 337let result = list.equal(obj); 338``` 339 340### removeByIndex 341 342removeByIndex(index: number): T 343 344根据元素的下标值查找元素，并将其删除。 345 346**系统能力：** SystemCapability.Utils.Lang 347 348**参数：** 349 350| 参数名 | 类型 | 必填 | 说明 | 351| -------- | -------- | -------- | -------- | 352| index | number | 是 | 指定元素的下标值。 | 353 354**返回值：** 355 356| 类型 | 说明 | 357| -------- | -------- | 358| T | 返回被删除的元素。 | 359 360**错误码：** 361 362以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 363 364| 错误码ID | 错误信息 | 365| -------- | -------- | 366| 10200011 | The removeByIndex method cannot be bound. | 367| 10200001 | The value of index is out of range. | 368 369**示例：** 370 371```ts 372let list: List<number> = new List(); 373list.add(2); 374list.add(4); 375list.add(5); 376list.add(2); 377list.add(4); 378let result = list.removeByIndex(2); 379``` 380 381### remove 382 383remove(element: T): boolean 384 385删除查找到的第一个指定的元素。 386 387**系统能力：** SystemCapability.Utils.Lang 388 389**参数：** 390 391| 参数名 | 类型 | 必填 | 说明 | 392| -------- | -------- | -------- | -------- | 393| element | T | 是 | 指定元素。 | 394 395**返回值：** 396 397| 类型 | 说明 | 398| -------- | -------- | 399| boolean | 删除成功返回true，否则返回false。 | 400 401**错误码：** 402 403以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 404 405| 错误码ID | 错误信息 | 406| -------- | -------- | 407| 10200011 | The remove method cannot be bound. | 408 409**示例：** 410 411```ts 412let list: List<number> = new List(); 413list.add(2); 414list.add(4); 415list.add(5); 416list.add(4); 417let result = list.remove(2); 418``` 419 420### replaceAllElements 421 422replaceAllElements(callbackFn: (value: T, index?: number, list?: List<T>) => T, 423thisArg?: Object): void 424 425用户操作List中的元素,用操作后的元素替换原元素并返回操作后的元素。 426 427**系统能力：** SystemCapability.Utils.Lang 428 429**参数：** 430 431| 参数名 | 类型 | 必填 | 说明 | 432| -------- | -------- | -------- | -------- | 433| callbackFn | function | 是 | 回调函数。 | 434| thisArg | Object | 否 | callbackfn被调用时用作this值，默认值为当前实例对象。 | 435 436callbackfn的参数说明： 437 438| 参数名 | 类型 | 必填 | 说明 | 439| -------- | -------- | -------- | -------- | 440| value | T | 是 | 当前遍历到的元素。 | 441| index | number | 否 | 当前遍历到的下标值，默认值为0。 | 442| list | List<T> | 否 | 当前调用replaceAllElements方法的实例对象，默认值为当前实例对象。 | 443 444**错误码：** 445 446以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 447 448| 错误码ID | 错误信息 | 449| -------- | -------- | 450| 10200011 | The replaceAllElements method cannot be bound. | 451 452**示例：** 453 454```ts 455let list: List<number> = new List(); 456list.add(2); 457list.add(4); 458list.add(5); 459list.add(4); 460list.replaceAllElements((value: number) => { 461 // 用户操作逻辑根据实际场景进行添加。 462 return value; 463}); 464``` 465 466### forEach 467 468forEach(callbackFn: (value: T, index?: number, List?: List<T>) => void, 469thisArg?: Object): void 470 471通过回调函数来遍历List实例对象上的元素以及元素对应的下标。 472 473**系统能力：** SystemCapability.Utils.Lang 474 475**参数：** 476 477| 参数名 | 类型 | 必填 | 说明 | 478| -------- | -------- | -------- | -------- | 479| callbackFn | function | 是 | 回调函数。 | 480| thisArg | Object | 否 | callbackfn被调用时用作this值，默认值为当前实例对象。 | 481 482callbackfn的参数说明： 483 484| 参数名 | 类型 | 必填 | 说明 | 485| -------- | -------- | -------- | -------- | 486| value | T | 是 | 当前遍历到的元素。 | 487| index | number | 否 | 当前遍历到的下标值，默认值为0。 | 488| List | List<T> | 否 | 当前调用forEach方法的实例对象，默认值为当前实例对象。 | 489 490**错误码：** 491 492以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 493 494| 错误码ID | 错误信息 | 495| -------- | -------- | 496| 10200011 | The forEach method cannot be bound. | 497 498**示例：** 499 500```ts 501let list: List<number> = new List(); 502list.add(2); 503list.add(4); 504list.add(5); 505list.add(4); 506list.forEach((value: number, index?: number) => { 507 console.log("value:" + value, "index:" + index); 508}); 509``` 510 511### sort 512 513sort(comparator: (firstValue: T, secondValue: T) => number): void 514 515对List中的元素进行一个排序操作。 516 517**系统能力：** SystemCapability.Utils.Lang 518 519**参数：** 520 521| 参数名 | 类型 | 必填 | 说明 | 522| -------- | -------- | -------- | -------- | 523| comparator | function | 是 | 回调函数。 | 524 525comparator的参数说明： 526 527| 参数名 | 类型 | 必填 | 说明 | 528| -------- | -------- | -------- | -------- | 529| firstValue | T | 是 | 前一项元素。 | 530| secondValue | T | 是 | 后一项元素。 | 531 532**错误码：** 533 534以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 535 536| 错误码ID | 错误信息 | 537| -------- | -------- | 538| 10200011 | The sort method cannot be bound. | 539 540**示例：** 541 542```ts 543let list: List<number> = new List(); 544list.add(2); 545list.add(4); 546list.add(5); 547list.add(4); 548list.sort((a: number, b: number) => a - b); // 结果为升序排列 549list.sort((a: number, b: number) => b - a); // 结果为降序排列 550``` 551 552### getSubList 553 554getSubList(fromIndex: number, toIndex: number): List<T> 555 556根据下标截取List中的一段元素，并返回这一段List实例，包括起始值但不包括终止值。 557 558**系统能力：** SystemCapability.Utils.Lang 559 560**参数：** 561 562| 参数名 | 类型 | 必填 | 说明 | 563| -------- | -------- | -------- | -------- | 564| fromIndex | number | 是 | 起始下标。 | 565| toIndex | number | 是 | 终止下标。 | 566 567**返回值：** 568 569| 类型 | 说明 | 570| -------- | -------- | 571| List<T> | 返回List对象实例。 | 572 573**错误码：** 574 575以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 576 577| 错误码ID | 错误信息 | 578| -------- | -------- | 579| 10200011 | The getSubList method cannot be bound. | 580| 10200001 | The value of fromIndex or toIndex is out of range. | 581 582**示例：** 583 584```ts 585let list: List<number> = new List(); 586list.add(2); 587list.add(4); 588list.add(5); 589list.add(4); 590let result = list.getSubList(1, 3); 591``` 592 593### clear 594 595clear(): void 596 597清除List中的所有元素，并把length置为0。 598 599**系统能力：** SystemCapability.Utils.Lang 600 601**错误码：** 602 603以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 604 605| 错误码ID | 错误信息 | 606| -------- | -------- | 607| 10200011 | The clear method cannot be bound. | 608 609**示例：** 610 611```ts 612let list: List<number> = new List(); 613list.add(2); 614list.add(4); 615list.add(5); 616list.add(4); 617list.clear(); 618``` 619 620### set 621 622set(index: number, element: T): T 623 624将此 List 中指定位置的元素替换为指定元素。 625 626**系统能力：** SystemCapability.Utils.Lang 627 628**参数：** 629 630| 参数名 | 类型 | 必填 | 说明 | 631| -------- | -------- | -------- | -------- | 632| index | number | 是 | 查找的下标值。 | 633| element | T | 是 | 用来替换的元素。 | 634 635**返回值：** 636 637| 类型 | 说明 | 638| -------- | -------- | 639| T | 返回替换后的元素 | 640 641**错误码：** 642 643以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 644 645| 错误码ID | 错误信息 | 646| -------- | -------- | 647| 10200011 | The set method cannot be bound. | 648| 10200001 | The value of index is out of range. | 649 650**示例：** 651 652```ts 653let list: List<number | string> = new List(); 654list.add(2); 655list.add(4); 656list.add(5); 657list.add(4); 658let result = list.set(2, "b"); 659``` 660 661### convertToArray 662 663convertToArray(): Array<T> 664 665把当前List实例转换成数组，并返回转换后的数组。 666 667**系统能力：** SystemCapability.Utils.Lang 668 669**返回值：** 670 671| 类型 | 说明 | 672| -------- | -------- | 673| Array<T> | 返回转换后的数组。 | 674 675**错误码：** 676 677以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 678 679| 错误码ID | 错误信息 | 680| -------- | -------- | 681| 10200011 | The convertToArray method cannot be bound. | 682 683**示例：** 684 685```ts 686let list: List<number> = new List(); 687list.add(2); 688list.add(4); 689list.add(5); 690list.add(4); 691let result = list.convertToArray(); 692``` 693 694### isEmpty 695 696isEmpty(): boolean 697 698判断该List是否为空。 699 700**系统能力：** SystemCapability.Utils.Lang 701 702**返回值：** 703 704| 类型 | 说明 | 705| -------- | -------- | 706| boolean | 为空返回true，不为空返回false。 | 707 708**错误码：** 709 710以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 711 712| 错误码ID | 错误信息 | 713| -------- | -------- | 714| 10200011 | The isEmpty method cannot be bound. | 715 716**示例：** 717 718```ts 719let list: List<number> = new List(); 720list.add(2); 721list.add(4); 722list.add(5); 723list.add(4); 724let result = list.isEmpty(); 725``` 726 727### getFirst 728 729getFirst(): T 730 731获取List实例中的第一个元素。 732 733**系统能力：** SystemCapability.Utils.Lang 734 735**返回值：** 736 737| 类型 | 说明 | 738| -------- | -------- | 739| T | 返回实例的第一个元素。 | 740 741**错误码：** 742 743以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 744 745| 错误码ID | 错误信息 | 746| -------- | -------- | 747| 10200011 | The getFirst method cannot be bound. | 748 749**示例：** 750 751```ts 752let list: List<number> = new List(); 753list.add(2); 754list.add(4); 755list.add(5); 756list.add(4); 757let result = list.getFirst(); 758``` 759 760### getLast 761 762getLast(): T 763 764获取List实例中的最后一个元素。 765 766**系统能力：** SystemCapability.Utils.Lang 767 768**返回值：** 769 770| 类型 | 说明 | 771| -------- | -------- | 772| T | 返回实例的最后一个元素。 | 773 774**错误码：** 775 776以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 777 778| 错误码ID | 错误信息 | 779| -------- | -------- | 780| 10200011 | The getLast method cannot be bound. | 781 782**示例：** 783 784```ts 785let list: List<number> = new List(); 786list.add(2); 787list.add(4); 788list.add(5); 789list.add(4); 790let result = list.getLast(); 791``` 792 793### [Symbol.iterator] 794 795[Symbol.iterator]\(): IterableIterator<T> 796 797返回一个迭代器，迭代器的每一项都是一个 JavaScript 对象，并返回该对象。 798 799> **说明：** 800> 801> 本接口不支持在.ets文件中使用 802 803**系统能力：** SystemCapability.Utils.Lang 804 805**返回值：** 806 807| 类型 | 说明 | 808| -------- | -------- | 809| IterableIterator<T> | 返回一个迭代器。 | 810 811**错误码：** 812 813以下错误码的详细介绍请参见[语言基础类库错误码](errorcode-utils.md)。 814 815| 错误码ID | 错误信息 | 816| -------- | -------- | 817| 10200011 | The Symbol.iterator method cannot be bound. | 818 819**示例：** 820 821```ts 822let list: List<number> = new List(); 823list.add(2); 824list.add(4); 825list.add(5); 826list.add(4); 827 828// 使用方法一： 829let items = Array.from(list) 830for (let item of items) { 831 console.log("value: " + item); 832} 833 834// 使用方法二： 835let iter = list[Symbol.iterator](); 836let temp: IteratorResult<number> = iter.next(); 837while(!temp.done) { 838 console.log("value: " + temp.value); 839 temp = iter.next(); 840} 841```