鴻蒙HarmonyOS實戰-ArkUI元件（List）

🚀一、List

🔎1.概述

列表是一種非常有用且功能強大的容器，它常用於呈現同型別或多型別資料集合，例如圖片、文字、音樂、通訊錄、購物清單等。列表對於顯示大量內容而不耗費過多空間和記憶體是非常有幫助的，因為當列表項數量超過螢幕大小時，可以自動提供滾動功能。這使得列表成為構建結構化、可滾動資訊的理想容器。

使用列表可以輕鬆、高效地顯示資訊。使用List元件，可以按垂直或水平方向線性排列子元件，這些子元件可以是單個檢視，也可以使用ForEach迭代一組行或列，或混合任意數量的單個檢視和ForEach結構，構建一個靈活的列表。同時，List元件支援使用條件渲染、迴圈渲染、懶載入等渲染控制方式生成子元件，使得列表變得更加靈活和高效。

列表是一種非常實用的容器，適用於呈現各種型別的資料集合，並且可以為使用者提供高效、流暢的滾動瀏覽體驗。

🔎2.佈局與約束

ListItemGroup是一個用於列表資料分組展示的元件，它的子元件也是ListItem。

• ListItem是單個列表項的表示，每個ListItem可以包含一個單獨的子元件，用於更詳細的展示該列表項的內容。

• ListItemGroup可以透過增加、刪除子元件或調整子元件的位置，來展示不同的分組資料。同時，你也可以擴充套件ListItem和ListItemGroup，新增更多的屬性和方法，以適配不同的使用場景。

🦋2.1 佈局

1、垂直滾動列表

2、水平滾動列表（左：單行；右：多行）

🦋2.2 約束

1、列表的主軸與交叉軸

如果List元件主軸或交叉軸方向設定了尺寸，則其對應方向上的尺寸為設定值。

2、一個垂直列表B沒有設定高度時，其父元件A高度為200vp，若其所有子元件C的高度總和為150vp，則此時列表B的高度為150vp。

3、同樣是沒有設定高度的垂直列表B，其父元件A高度為200vp，若其所有子元件C的高度總和為300vp，則此時列表B的高度為200vp。

🔎3.開釋出局

🦋3.1 設定主軸方向

List() {
  ...
}
.listDirection(Axis.Horizontal)

List元件預設主軸方向是垂直的，可以自動構建垂直滾動列表，無需手動設定。如果需要構建水平滾動列表，只需要將List元件的listDirection屬性設定為Axis.Horizontal即可。需要注意的是，listDirection屬性的預設值為Axis.Vertical，即預設情況下List元件的主軸方向是垂直方向。

更多鴻蒙最新技術知識點，請關注作者部落格：https://t.doruo.cn/14DjR1rEY

🦋3.2 設定交叉軸佈局

List元件的交叉軸佈局可以透過lanes和alignListItem屬性進行設定。lanes屬性用於確定交叉軸排列的列表項數量，alignListItem用於設定子元件在交叉軸方向的對齊方式。一般情況下，List元件的lanes屬性被用於在不同尺寸的裝置上自適應構建不同行數或列數的列表。lanes屬性的取值型別為"number | LengthConstrain"，即整數或者LengthConstrain型別。

List() {
  ...
}
.lanes(2)

List() {
  ...
}
.lanes({ minLength: 200, maxLength: 300 })

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

• lanes：設定列數
• alignListItem：設定對齊方式

🔎4.案例

🦋4.1 在列表中顯示資料

@Entry
@Component
struct Index {
  build() {
    List() {
      ListItem() {
        Text('北京').fontSize(24)
      }

      ListItem() {
        Text('杭州').fontSize(24)
      }

      ListItem() {
        Text('上海').fontSize(24)
      }
    }
    .backgroundColor('#FFF1F3F5')
    .alignListItem(ListItemAlign.Center)
  }
}

@Entry
@Component
struct Index {
  build() {
    List() {
      ListItem() {
        Row() {
          Image($r('app.media.app_icon'))
            .width(40)
            .height(40)
            .margin(10)

          Text('小明')
            .fontSize(20)
        }
      }

      ListItem() {
        Row() {
          Image($r('app.media.app_icon'))
            .width(40)
            .height(40)
            .margin(10)

          Text('小紅')
            .fontSize(20)
        }
      }
    }
  }
}

🦋4.1 迭代列表內容

import util from '@ohos.util';

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 Index {
  private contacts = [
    new Contact('小明', $r("app.media.app_icon")),
    new Contact('小紅', $r("app.media.app_icon")),
    new Contact('張三', $r("app.media.app_icon")),
    new Contact('李四', $r("app.media.app_icon")),
  ]

  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 => item.key+item.name)
    }
    .width('100%')
  }
}

🦋4.3 自定義列表樣式

☀️4.3.1 內容間距

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

☀️4.3.2 新增分隔線

List() {
  ...
}
.divider({
  strokeWidth: 1,
  startMargin: 60,
  endMargin: 10,
  color: '#ffe9f0f0'
})

☀️4.3.3 新增捲軸

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

☀️4.3.4 分組列表

1、直接手動分鐘

@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') }) {
        // 迴圈渲染分組A的ListItem
        ...
      }
      ...

      ListItemGroup({ header: this.itemHead('B') }) {
        // 迴圈渲染分組B的ListItem
        ...
      }
      ...
    }
  }
}

2、遍歷分組

contactsGroups: object[] = [
  {
    title: 'A',
    contacts: [
      new Contact('艾佳', $r('app.media.iconA')),
      new Contact('安安', $r('app.media.iconB')),
      new Contact('Angela', $r('app.media.iconC')),
    ],
  },
  {
    title: 'B',
    contacts: [
      new Contact('白葉', $r('app.media.iconD')),
      new Contact('伯明', $r('app.media.iconE')),
    ],
  },
  ...
]

List() {
  // 迴圈渲染ListItemGroup，contactsGroups為多個分組聯絡人contacts和標題title的資料集合
  ForEach(this.contactsGroups, item => {
    ListItemGroup({ header: this.itemHead(item.title) }) {
      // 迴圈渲染ListItem
      ForEach(item.contacts, contact => {
        ListItem() {
          ...
        }
      }, item => item.key)
    }
    ...
  })
}

☀️4.3.5 新增粘性標題（官方）

@Component
struct ContactsList {
  // 定義分組聯絡人資料集合contactsGroups陣列
  ...
 
  @Builder itemHead(text: string) {
    // 列表分組的頭部元件，對應聯絡人分組A、B等位置的元件
    Text(text)
      .fontSize(20)
      .backgroundColor('#fff1f3f5')
      .width('100%')
      .padding(5)
  }

  build() {
    List() {
      // 迴圈渲染ListItemGroup，contactsGroups為多個分組聯絡人contacts和標題title的資料集合
      ForEach(this.contactsGroups, item => {
        ListItemGroup({ header: this.itemHead(item.title) }) {
          // 迴圈渲染ListItem
          ForEach(item.contacts, contact => {
            ListItem() {
              ...
            }
          }, item => item.key)
        }
        ...
      })
    }
    .sticky(StickyStyle.Header)  // 設定吸頂，實現粘性標題效果
  }
}

image

☀️4.3.6 控制滾動位置（官方）

private listScroller: Scroller = new Scroller();
Stack({ alignContent: Alignment.BottomEnd }) {
  // 將listScroller用於初始化List元件的scroller引數，完成listScroller與列表的繫結。
  List({ space: 20, scroller: this.listScroller }) {
    ...
  }
  ...

  Button() {
    ...
  }
  .onClick(() => {
    // 點選按鈕時，指定跳轉位置，返回列表頂部
    this.listScroller.scrollToIndex(0)
  })
  ...
}

☀️4.3.7 響應滾動位置（官方）

...
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 = firstIndex
        // 根據列表滾動到的索引值，重新計算對應聯絡人索引欄的位置this.selectedIndex
        ...
      })
      ...
      // 字母表索引元件
      AlphabetIndexer({ arrayValue: alphabets, selected: 0 })
        .selected(this.selectedIndex)
      ...
    }
  }
}

☀️4.3.8 響應列表項側滑（官方）

@Entry
@Component
struct MessageList {
  @State messages: object[] = [
    // 初始化訊息列表資料
    ...
  ];

  @Builder itemEnd(index: number) {
    // 側滑後尾端出現的元件
    Button({ type: ButtonType.Circle }) {
      Image($r('app.media.ic_public_delete_filled'))
        .width(20)
        .height(20)
    }
    .onClick(() => {
      this.messages.splice(index, 1);
    })
    ...
  }
  build() {
    ...
      List() {
        ForEach(this.messages, (item, index) => {
          ListItem() {
            ...
          }
          .swipeAction({ end: this.itemEnd.bind(this, index) }) // 設定側滑屬性
        }, item => item.id.toString())
      }
    ...
  }
}

☀️4.3.9 給列表項新增標記（官方）

Badge({
  count: 1,
  position: BadgePosition.RightTop,
  style: { badgeSize: 16, badgeColor: '#FA2A2D' }
}) {
  // Image元件實現訊息聯絡人頭像
  ...
}
...

☀️4.3.10 下拉重新整理與上拉載入（官方）
案例：https://developer.huawei.com/consumer/cn/codelabsPortal/carddetails/tutorials_NewsDataLoad?ha_linker=eyJ0cyI6MTcwMTY1Njg2NjU1MywiaWQiOiJjNDFjZDY5NTVjZDQ0NTBjZWE1ZWQxOTQ0MzZkODJkNSJ9

第三方元件：https://gitee.com/openharmony-sig/PullToRefresh

更多鴻蒙最新技術知識點，請關注作者部落格：https://t.doruo.cn/14DjR1rEY

☀️4.3.11 編輯列表（官方）

1、定義列表項資料結構

import util from '@ohos.util';

export class ToDo {
  key: string = util.generateRandomUUID(true);
  name: string;

  constructor(name: string) {
    this.name = name;
  }
}

2、初始化資料

@State toDoData: ToDo[] = [];
private availableThings: string[] = ['讀書', '運動', '旅遊', '聽音樂', '看電影', '唱歌'];

3、構建列表佈局和列表項

List({ space: 10 }) {
  ForEach(this.toDoData, (toDoItem) => {
    ListItem() {
      ...
    }
  }, toDoItem => toDoItem.key)
}

4、響應使用者確定新增事件，更新列表資料

Text('+')
  .onClick(() => {
    TextPickerDialog.show({
      range: this.availableThings,
      onAccept: (value: TextPickerResult) => {
         this.toDoData.push(new ToDo(this.availableThings[value.index])); // 新增列表項資料toDoData
      },
    })
  })

☀️4.3.12 刪除列表項（官方）

1、以待辦列表為例，透過監聽列表項的長按事件，當使用者長按列表項時，進入編輯模式。

// ToDoListItem.ets

Flex({ justifyContent: FlexAlign.SpaceBetween, alignItems: ItemAlign.Center }) {
  ...
}
.gesture(
GestureGroup(GestureMode.Exclusive,
  LongPressGesture()
    .onAction(() => {
      if (!this.isEditMode) {
        this.isEditMode = true; //進入編輯模式
        this.selectedItems.push(this.toDoItem); // 記錄長按時選中的列表項
      }
    })
  )
)

2、在待辦列表中，透過勾選框的勾選或取消勾選，響應使用者勾選列表項變化，記錄所有選擇的列表項。

// ToDoListItem.ets

if (this.isEditMode) {
  Checkbox()
    .onChange((isSelected) => {
      if (isSelected) {
        this.selectedItems.push(this.toDoItem) // 勾選時，記錄選中的列表項
      } else {
        let index = this.selectedItems.indexOf(this.toDoItem)
        if (index !== -1) {
          this.selectedItems.splice(index, 1) // 取消勾選時，則將此項從selectedItems中刪除
        }
      }
    })
    ...
}

3、需要響應使用者點選刪除按鈕事件，刪除列表中對應的選項

// ToDoList.ets

Button('刪除')
  .onClick(() => {
    // 刪除選中的列表項對應的toDoData資料
    let leftData = this.toDoData.filter((item) => {
      return this.selectedItems.find((selectedItem) => selectedItem !== item);
    })

    this.toDoData = leftData;
    this.isEditMode = false;
  })
  ...

🦋4.4 長列表的處理

迴圈渲染適用於短列表。但當構建具有大量列表項的長列表時，直接採用迴圈渲染方式會一次性載入所有的列表元素，導致頁面啟動時間過長，影響使用者體驗。因此，推薦使用資料懶載入（LazyForEach）方式實現按需迭代載入資料，從而提升列表效能。具體實現可參考資料懶載入章節中的示例。

當使用懶載入方式渲染列表時，為了更好的列表滾動體驗，並減少列表滑動時出現白塊，List元件提供了cachedCount引數。該引數用於設定列表項快取數量，只在懶載入LazyForEach中生效。

List() {
  LazyForEach(this.dataSource, item => {
    ListItem() {
      ...
    }
  })
}.cachedCount(3)

🚀寫在最後

• 如果你覺得這篇內容對你還蠻有幫助，我想邀請你幫我三個小忙：
• 點贊，轉發，有你們的 『點贊和評論』，才是我創造的動力。
• 關注小編，同時可以期待後續文章ing🚀，不定期分享原創知識。
• 更多鴻蒙最新技術知識點，請關注作者部落格：https://t.doruo.cn/14DjR1rEY