列表布局

當列表項達到一定數量，內容超過屏幕大小時，可以自動提供滾動功能。它適合用于呈現同類數據類型或數據類型集，例如圖片和文本。在列表中顯示數據集合是許多應用程序中的常見要求（如通訊錄、音樂列表、購物清單等）。

布局與約束

列表作為一種容器，會自動按其滾動方向排列子組件，向列表中添加組件或從列表中移除組件會重新排列子組件。
ListItemGroup用于列表數據的分組展示，其子組件也是ListItem。ListItem表示單個列表項，可以包含單個子組件。
說明： List的子組件必須是ListItemGroup或ListItem，ListItem和ListItemGroup必須配合List來使用。

Grid和WaterFlow也可以實現單列、多列布局，如果布局每列等寬，且不需要跨行跨列布局，相比Gird和WaterFlow，則更推薦使用List。

1. 如果List組件主軸或交叉軸方向設置了尺寸，則其對應方向上的尺寸為設置值。
2. 如果List組件主軸方向沒有設置尺寸，當List子組件主軸方向總尺寸小于List的父組件尺寸時，List 主軸方向尺寸自動適應子組件的總尺寸。如果List的子組件主軸方向總尺寸超過List的父組件尺寸時，List主軸方向尺寸適應List的父組件尺寸。
3. List組件交叉軸方向在沒有設置尺寸時，其尺寸默認自適應父組件尺寸。

開發(fā)布局

設置主軸方向

List() { // ...}
.listDirection(Axis.Horizontal)
listDirection屬性設置為Axis.Horizontal，水平滾動。
listDirection默認為Axis.Vertical，即主軸默認是垂直方向。

設置交叉軸布局

List組件的交叉軸布局可以通過lanes和alignListItem屬性進行設置，
lanes屬性用于確定交叉軸排列的列表項數量，
alignListItem用于設置子組件在交叉軸方向的對齊方式。

lanes

List組件的lanes屬性通常用于在不同尺寸的設備自適應構建不同行數或列數的列表，即一次開發(fā)、多端部署的場景，例如歌單列表。
lanes屬性的取值類型是"number | LengthConstrain"，即整數或者LengthConstrain類型。
當其取值為LengthConstrain類型時，表示會根據LengthConstrain與List組件的尺寸自適應決定行或列數。

//取值為number
List() { // ...}
.lanes(2)
//取值為LengthConstrain類型
@Entry
@Component
struct EgLanes {@State egLanes: LengthConstrain = { minLength: 200, maxLength: 300 }build() {List() { // ...}.lanes(this.egLanes)}
}
當List組件寬度為300vp時，由于minLength為200vp，此時列表為一列。
當List組件寬度變化至400vp時，符合兩倍的minLength，則此時列表自適應為兩列。

alignListItem屬性

默認值是ListItemAlign.Start，即列表項在列表交叉軸方向上默認按首部對齊。
ListItemAlign.Center表示列表項在水平方向上居中對齊。

List() { // ...}
.alignListItem(ListItemAlign.Center)

在列表中顯示數據

ListItem中只能有一個根節(jié)點組件，若列表項是由多個組件元素組成的，則需要將這多個元素組合到一個容器組件內或組成一個自定義組件。

List() {ListItem() {Row() {Image($r('app.media.iconE')).width(40).height(40).margin(10)Text('小明').fontSize(20)}}}

迭代列表內容

通常，應用通過數據集合動態(tài)地創(chuàng)建列表。使用循環(huán)渲染可從數據源中迭代獲取數據，并在每次迭代過程中創(chuàng)建相應的組件，降低代碼復雜度。

ArkTS通過ForEach提供了組件的循環(huán)渲染能力。

import { util } from '@kit.ArkTS'class Contact {key: string = util.generateRandomUUID(true);name: string;icon: Resource;constructor(name: string, icon: Resource) {this.name = name;this.icon = icon;}
}@Entry
@Component
struct SimpleContacts {private contacts: Array<object> = [new Contact('小明', $r("app.media.iconA")),new Contact('小紅', $r("app.media.iconB")),]build() {List() {ForEach(this.contacts, (item: Contact) => {ListItem() {Row() {Image(item.icon).width(40).height(40).margin(10)Text(item.name).fontSize(20)}.width('100%').justifyContent(FlexAlign.Start)}}, (item: Contact) => JSON.stringify(item))}.width('100%')}
}

自定義列表樣式

設置內容間距——space參數

List({ space: 10 }) {// ...
}

添加分隔線——divider屬性

divider屬性用于給列表項之間添加分隔線。在設置divider屬性時，可以通過strokeWidth和color屬性設置分隔線的粗細和顏色。
startMargin和endMargin屬性分別用于設置分隔線距離列表側邊起始端的距離和距離列表側邊結束端的距離。

class DividerTmp {strokeWidth: Length = 1startMargin: Length = 60endMargin: Length = 10color: ResourceColor = '#ffe9f0f0'constructor(strokeWidth: Length, startMargin: Length, endMargin: Length, color: ResourceColor) {this.strokeWidth = strokeWidththis.startMargin = startMarginthis.endMargin = endMarginthis.color = color}
}
@Entry
@Component
struct EgDivider {@State egDivider: DividerTmp = new DividerTmp(1, 60, 10, '#ffe9f0f0')build() {List() {// ... }.divider(this.egDivider)}
}

說明

分隔線的寬度會使ListItem之間存在一定間隔，當List設置的內容間距小于分隔線寬度時，ListItem之間的間隔會使用分隔線的寬度。當List存在多列時，分割線的startMargin和endMargin作用于每一列上。List組件的分隔線畫在兩個ListItem之間，第一個ListItem上方和最后一個ListItem下方不會繪制分隔線。

添加滾動條——scrollBar屬性

在使用List組件時，可通過scrollBar屬性控制列表滾動條的顯示。scrollBar的取值類型為BarState，當取值為BarState.Auto表示按需顯示滾動條。此時，當觸摸到滾動條區(qū)域時顯示控件，可上下拖拽滾動條快速瀏覽內容，拖拽時會變粗。若不進行任何操作，2秒后滾動條自動消失。

scrollBar屬性API version 9及以下版本默認值為BarState.Off，從API version 10版本開始默認值為BarState.Auto。

List() { // ...}
.scrollBar(BarState.Auto)

支持分組列表——ListItemGroup

在List組件中使用ListItemGroup對項目進行分組，可以構建二維列表。
ListItemGroup的寬度默認充滿List組件。在初始化ListItemGroup時，可通過header參數設置列表分組的頭部組件。

@Entry
@Component
struct ContactsList {@Builder itemHead(text: string) {// 列表分組的頭部組件，對應聯系人分組A、B等位置的組件Text(text).fontSize(20).backgroundColor('#fff1f3f5').width('100%').padding(5)}build() {List() {ListItemGroup({ header: this.itemHead('A') }) {// 循環(huán)渲染分組A的ListItem}}}
}

添加粘性標題——sticky屬性

粘性標題是一種常見的標題模式，常用于定位字母列表的頭部元素。如在聯系人列表中滾動A部分時，B部分開始的頭部元素始終處于A的下方。而在開始滾動B部分時，B的頭部會固定在屏幕頂部，直到所有B的項均完成滾動后，才被后面的頭部替代。

List組件的sticky屬性配合ListItemGroup組件使用，用于設置ListItemGroup中的頭部組件是否呈現吸頂效果或者尾部組件是否呈現吸底效果。

設置sticky屬性為StickyStyle.Header，即可實現列表的粘性標題效果。
如果需要支持吸底效果，可以通過footer參數初始化ListItemGroup的底部組件，并將sticky屬性設置為StickyStyle.Footer。ListItemGroup({ header: this.itemHead(itemGroup.title) }) {// 循環(huán)渲染ListItem
}.sticky(StickyStyle.Header)  // 設置吸頂，實現粘性標題效果

控制滾動位置

用戶滾動列表到一定位置時，希望快速滾動到列表底部或返回列表頂部。此時，可以通過控制滾動位置來實現列表的快速定位。
List組件初始化時，可以通過scroller參數綁定一個Scroller對象，就可以通過Scroller對象的scrollToIndex方法使列表滾動到指定的列表項索引位置。

首先，需要創(chuàng)建一個Scroller的對象listScroller。

private listScroller: Scroller = new Scroller();

然后，通過將listScroller用于初始化List組件的scroller參數，完成listScroller與列表的綁定。在需要跳轉的位置指定scrollToIndex的參數為0，表示返回列表頂部。

Stack({ alignContent: Alignment.Bottom }) {// 將listScroller用于初始化List組件的scroller參數，完成listScroller與列表的綁定。List({ space: 20, scroller: this.listScroller }) {// ...}Button() {// ...}.onClick(() => {// 點擊按鈕時，指定跳轉位置，返回列表頂部this.listScroller.scrollToIndex(0)})
}

響應滾動位置

監(jiān)聽列表的滾動位置變化并作出響應

當聯系人列表從A滾動到B時，右側索引欄也需要同步從選中A狀態(tài)變成選中B狀態(tài)。此場景可以通過監(jiān)聽List組件的onScrollIndex事件來實現，右側索引欄需要使用字母表索引組件AlphabetIndexer。

在列表滾動時，根據列表此時所在的索引值位置firstIndex，重新計算字母索引欄對應字母的位置selectedIndex。由于AlphabetIndexer組件通過selected屬性設置了選中項索引值，當selectedIndex變化時會觸發(fā)AlphabetIndexer組件重新渲染，從而顯示為選中對應字母的狀態(tài)。

const alphabets = ['#', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K','L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z'];
@Entry
@Component
struct ContactsList {@State selectedIndex: number = 0;private listScroller: Scroller = new Scroller();build() {Stack({ alignContent: Alignment.End }) {List({ scroller: this.listScroller }) {}.onScrollIndex((firstIndex: number) => {// 根據列表滾動到的索引值，重新計算對應聯系人索引欄的位置this.selectedIndex})// 字母表索引組件AlphabetIndexer({ arrayValue: alphabets, selected: 0 }).selected(this.selectedIndex)}}
}

說明
計算索引值時，ListItemGroup作為一個整體占一個索引值，不計算ListItemGroup內部ListItem的索引值。

響應列表項側滑——swipeAction屬性

給列表項添加標記——Badge組件

下拉刷新與上拉加載

編輯列表

新增列表項

刪除列表項

長列表的處理——懶加載

循環(huán)渲染適用于短列表，當構建具有大量列表項的長列表時，如果直接采用循環(huán)渲染方式，會一次性加載所有的列表元素，會導致頁面啟動時間過長，影響用戶體驗。因此，推薦使用數據懶加載（LazyForEach）方式實現按需迭代加載數據，從而提升列表性能。