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