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