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