閱讀(496) 書簽贊(0) 我要糾錯(cuò)

列表項(xiàng)

2024-01-22 17:53 更新

列表包含一系列相同寬度的列表項(xiàng)。適合連續(xù)、多行呈現(xiàn)同類數(shù)據(jù)，例如圖片和文本。

說明

該組件從API Version 7開始支持。后續(xù)版本如有新增內(nèi)容，則采用上角標(biāo)單獨(dú)標(biāo)記該內(nèi)容的起始版本。
該組件回彈的前提是要有滾動。內(nèi)容小于一屏?xí)r，沒有回彈效果。

子組件

包含ListItem、ListItemGroup子組件。

說明

List的子組件的索引值計(jì)算規(guī)則：

按子組件的順序依次遞增。
if/else語句中，只有條件成立的分支內(nèi)的子組件會參與索引值計(jì)算，條件不成立的分支內(nèi)子組件不計(jì)算索引值。
ForEach/LazyForEach語句中，會計(jì)算展開所有子節(jié)點(diǎn)索引值。
if/else/ForEach/LazyForEach發(fā)生變化以后，會更新子節(jié)點(diǎn)索引值。
ListItemGroup作為一個(gè)整體計(jì)算一個(gè)索引值，ListItemGroup內(nèi)部的ListItem不計(jì)算索引值。
List子組件的visibility屬性設(shè)置為Hidden或None依然會計(jì)算索引值。
List子組件的visibility屬性設(shè)置為None時(shí)不顯示，但該子組件上下的space還會生效。

接口

List(value?:{space?: number | string, initialIndex?: number, scroller?: Scroller})

從API version 9開始，該接口支持在ArkTS卡片中使用。

參數(shù)：

參數(shù)名	參數(shù)類型	必填	參數(shù)描述
space	number \| string	否	子組件主軸方向的間隔。默認(rèn)值：0 說明：設(shè)置為除-1外其他負(fù)數(shù)或百分比時(shí)，按默認(rèn)值顯示。 space參數(shù)值小于List分割線寬度時(shí)，子組件主軸方向的間隔取分割線寬度。
initialIndex	number	否	設(shè)置當(dāng)前List初次加載時(shí)視口起始位置顯示的item的索引值。默認(rèn)值：0 說明：設(shè)置為除-1外其他負(fù)數(shù)或超過了當(dāng)前List最后一個(gè)item的索引值時(shí)視為無效取值，無效取值按默認(rèn)值顯示。
scroller	Scroller	否	可滾動組件的控制器。用于與可滾動組件進(jìn)行綁定。說明：不允許和其他滾動類組件綁定同一個(gè)滾動控制對象。

參數(shù)名

參數(shù)類型

必填

參數(shù)描述

space

number | string

否

子組件主軸方向的間隔。

默認(rèn)值：0

說明：

設(shè)置為除-1外其他負(fù)數(shù)或百分比時(shí)，按默認(rèn)值顯示。

space參數(shù)值小于List分割線寬度時(shí)，子組件主軸方向的間隔取分割線寬度。

initialIndex

number

否

設(shè)置當(dāng)前List初次加載時(shí)視口起始位置顯示的item的索引值。

默認(rèn)值：0

說明：

設(shè)置為除-1外其他負(fù)數(shù)或超過了當(dāng)前List最后一個(gè)item的索引值時(shí)視為無效取值，無效取值按默認(rèn)值顯示。

scroller

Scroller

否

可滾動組件的控制器。用于與可滾動組件進(jìn)行綁定。

說明：

不允許和其他滾動類組件綁定同一個(gè)滾動控制對象。

屬性

除支持通用屬性外，還支持以下屬性：

名稱	參數(shù)類型	描述
listDirection	Axis	設(shè)置List組件排列方向。默認(rèn)值：Axis.Vertical 從API version 9開始，該接口支持在ArkTS卡片中使用。
divider	{ strokeWidth: Length, color?:ResourceColor, startMargin?: Length, endMargin?: Length } \| null	設(shè)置ListItem分割線樣式，默認(rèn)無分割線。 - strokeWidth: 分割線的線寬。 - color: 分割線的顏色。 - startMargin: 分割線與列表側(cè)邊起始端的距離。 - endMargin: 分割線與列表側(cè)邊結(jié)束端的距離。從API version 9開始，該接口支持在ArkTS卡片中使用。 endMargin +startMargin 不能超過列寬度。 startMargin和endMargin不支持設(shè)置百分比。 List的分割線畫在主軸方向兩個(gè)子組件之間，第一個(gè)子組件上方和最后一個(gè)子組件下方不會繪制分割線。多列模式下，ListItem與ListItem之間的分割線起始邊距從每一列的交叉軸方向起始邊開始計(jì)算，其他情況從List交叉軸方向起始邊開始計(jì)算。
scrollBar	BarState	設(shè)置滾動條狀態(tài)。默認(rèn)值：BarState.Off 從API version 9開始，該接口支持在ArkTS卡片中使用。
cachedCount	number	設(shè)置列表中ListItem/ListItemGroup的預(yù)加載數(shù)量，其中ListItemGroup將作為一個(gè)整體進(jìn)行計(jì)算，ListItemGroup中的所有ListItem會一次性全部加載出來。具體使用可參考減少應(yīng)用白塊說明。默認(rèn)值：1 從API version 9開始，該接口支持在ArkTS卡片中使用。說明：單列模式下，會在List顯示的ListItem前后各緩存cachedCount個(gè)ListItem。多列模式下，會在List顯示的ListItem前后各緩存cachedCount*列數(shù)個(gè)ListItem。
editMode(deprecated)	boolean	聲明當(dāng)前List組件是否處于可編輯模式?？蓞⒖?a rel="external nofollow" target="_blank" >示例3實(shí)現(xiàn)刪除選中的list項(xiàng)。從API version9開始廢棄。默認(rèn)值：false
edgeEffect	EdgeEffect	設(shè)置組件的滑動效果。默認(rèn)值：EdgeEffect.Spring 從API version 9開始，該接口支持在ArkTS卡片中使用。
chainAnimation	boolean	設(shè)置當(dāng)前List是否啟用鏈?zhǔn)铰?lián)動動效，開啟后列表滑動以及頂部和底部拖拽時(shí)會有鏈?zhǔn)铰?lián)動的效果。鏈?zhǔn)铰?lián)動效果：List內(nèi)的list-item間隔一定距離，在基本的滑動交互行為下，主動對象驅(qū)動從動對象進(jìn)行聯(lián)動，驅(qū)動效果遵循彈簧物理動效。默認(rèn)值：false - false：不啟用鏈?zhǔn)铰?lián)動。 - true：啟用鏈?zhǔn)铰?lián)動。從API version 9開始，該接口支持在ArkTS卡片中使用。
multiSelectable8+	boolean	是否開啟鼠標(biāo)框選。默認(rèn)值：false - false：關(guān)閉框選。 - true：開啟框選。從API version 9開始，該接口支持在ArkTS卡片中使用。
lanes9+	number \| LengthConstrain	以列模式為例（listDirection為Axis.Vertical）: lanes用于決定List組件在交叉軸方向按幾列布局。默認(rèn)值：1 規(guī)則如下： - lanes為指定的數(shù)量時(shí)，根據(jù)指定的數(shù)量與List組件的交叉軸尺寸除以列數(shù)作為列的寬度。 - lanes設(shè)置了{(lán)minLength，maxLength}時(shí)，根據(jù)List組件的寬度自適應(yīng)決定lanes數(shù)量（即列數(shù)），保證縮放過程中l(wèi)ane的寬度符合{minLength，maxLength}的限制。其中，minLength條件會被優(yōu)先滿足，即優(yōu)先保證符合ListItem的交叉軸尺寸符合最小限制。 - lanes設(shè)置了{(lán)minLength，maxLength}，如果父組件交叉軸方向尺寸約束為無窮大時(shí)，固定按一列排列，列寬度按顯示區(qū)域內(nèi)最大的ListItem計(jì)算。 - ListItemGroup在多列模式下也是獨(dú)占一行，ListItemGroup中的ListItem按照List組件的lanes屬性設(shè)置值來布局。 - lanes設(shè)置了{(lán)minLength，maxLength}時(shí)，計(jì)算列數(shù)會按照ListItemGroup的交叉軸尺寸計(jì)算。當(dāng)ListItemGroup交叉軸尺寸與List交叉軸尺寸不一致時(shí)ListItemGroup中的列數(shù)與List中的列數(shù)可能不一樣。該接口支持在ArkTS卡片中使用。
alignListItem9+	ListItemAlign	List交叉軸方向?qū)挾却笥贚istItem交叉軸寬度 * lanes時(shí)，ListItem在List交叉軸方向的布局方式，默認(rèn)為首部對齊。默認(rèn)值：ListItemAlign.Start 該接口支持在ArkTS卡片中使用。
sticky9+	StickyStyle	配合ListItemGroup組件使用，設(shè)置ListItemGroup中header和footer是否要吸頂或吸底。默認(rèn)值：StickyStyle.None 該接口支持在ArkTS卡片中使用。說明： sticky屬性可以設(shè)置為 StickyStyle.Header \| StickyStyle.Footer 以同時(shí)支持header吸頂和footer吸底。

ListItemAlign9+枚舉說明

該接口支持在ArkTS卡片中使用。

名稱	描述
Start	ListItem在List中，交叉軸方向首部對齊。
Center	ListItem在List中，交叉軸方向居中對齊。
End	ListItem在List中，交叉軸方向尾部對齊。

StickyStyle9+枚舉說明

該接口支持在ArkTS卡片中使用。

名稱	描述
None	ListItemGroup的header不吸頂，footer不吸底。
Header	ListItemGroup的header吸頂，footer不吸底。
Footer	ListItemGroup的footer吸底，header不吸頂。

說明

List組件通用屬性clip的默認(rèn)值為true。

事件

名稱	功能描述
onItemDelete(deprecated)(event: (index: number) => boolean)	當(dāng)List組件在編輯模式時(shí)，點(diǎn)擊ListItem右邊出現(xiàn)的刪除按鈕時(shí)觸發(fā)。從API version9開始廢棄。 - index: 被刪除的列表項(xiàng)的索引值。
onScroll(event: (scrollOffset: number, scrollState: ScrollState) => void)	列表滑動時(shí)觸發(fā)。 - scrollOffset: 每幀滾動的偏移量，List的內(nèi)容向上滾動時(shí)偏移量為正，向下滾動時(shí)偏移量為負(fù)。 - scrollState: 當(dāng)前滑動狀態(tài)。使用控制器調(diào)用ScrollEdge和ScrollToIndex時(shí)不會觸發(fā)，其余情況有滾動就會觸發(fā)該事件。從API version 9開始，該接口支持在ArkTS卡片中使用。
onScrollIndex(event: (start: number, end: number) => void)	列表滑動時(shí)觸發(fā)。計(jì)算索引值時(shí)，ListItemGroup作為一個(gè)整體占一個(gè)索引值，不計(jì)算ListItemGroup內(nèi)部ListItem的索引值。 - start: 滑動起始位置索引值。 - end: 滑動結(jié)束位置索引值。觸發(fā)該事件的條件：列表初始化時(shí)會觸發(fā)一次，List顯示區(qū)域內(nèi)第一個(gè)子組件的索引值或后一個(gè)子組件的索引值有變化時(shí)會觸發(fā)。 List的邊緣效果為彈簧效果時(shí)，在List劃動到邊緣繼續(xù)劃動和松手回彈過程不會觸發(fā)onScrollIndex事件。從API version 9開始，該接口支持在ArkTS卡片中使用。
onReachStart(event: () => void)	列表到達(dá)起始位置時(shí)觸發(fā)。從API version 9開始，該接口支持在ArkTS卡片中使用。說明： List初始化時(shí)如果initialIndex為0會觸發(fā)一次，List滾動到起始位置時(shí)觸發(fā)一次。List邊緣效果為彈簧效果時(shí)，劃動經(jīng)過起始位置時(shí)觸發(fā)一次，回彈回起始位置時(shí)再觸發(fā)一次。
onReachEnd(event: () => void)	列表到底末尾位置時(shí)觸發(fā)。從API version 9開始，該接口支持在ArkTS卡片中使用。說明： List邊緣效果為彈簧效果時(shí)，劃動經(jīng)過末尾位置時(shí)觸發(fā)一次，回彈回末尾位置時(shí)再觸發(fā)一次。
onScrollFrameBegin9+(event: (offset: number, state: ScrollState) => { offsetRemain })	列表開始滑動時(shí)觸發(fā)，事件參數(shù)傳入即將發(fā)生的滑動量，事件處理函數(shù)中可根據(jù)應(yīng)用場景計(jì)算實(shí)際需要的滑動量并作為事件處理函數(shù)的返回值返回，列表將按照返回值的實(shí)際滑動量進(jìn)行滑動。 - offset：即將發(fā)生的滑動量，單位vp。 - state：當(dāng)前滑動狀態(tài)。 - offsetRemain：實(shí)際滑動量，單位vp。觸發(fā)該事件的條件：手指拖動List、List慣性劃動時(shí)每幀開始時(shí)觸發(fā)；List超出邊緣回彈、使用滾動控制器的滾動不會觸發(fā)。該接口支持在ArkTS卡片中使用。說明：當(dāng)listDirection的值為Axis.Vertical時(shí)，返回垂直方向滑動量，當(dāng)listDirection的值為Axis.Horizontal時(shí)，返回水平方向滑動量。
onScrollStart9+(event: () => void)	列表滑動開始時(shí)觸發(fā)。手指拖動列表或列表的滾動條觸發(fā)的滑動開始時(shí)，會觸發(fā)該事件。使用Scroller滑動控制器觸發(fā)的帶動畫的滑動，動畫開始時(shí)會觸發(fā)該事件。該接口支持在ArkTS卡片中使用。
onScrollStop(event: () => void)	列表滑動停止時(shí)觸發(fā)。手拖動列表或列表的滾動條觸發(fā)的滑動，手離開屏幕并且滑動停止時(shí)會觸發(fā)該事件；使用Scroller滑動控制器觸發(fā)的帶動畫的滑動，動畫停止會觸發(fā)該事件。從API version 9開始，該接口支持在ArkTS卡片中使用。
onItemMove(event: (from: number, to: number) => boolean)	列表元素發(fā)生移動時(shí)觸發(fā)。 - from: 移動前索引值。 - to: 移動后索引值。
onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => ((() => any) \| void)	開始拖拽列表元素時(shí)觸發(fā)。 - event: 見ItemDragInfo對象說明。 - itemIndex: 被拖拽列表元素索引值。
onItemDragEnter(event: (event: ItemDragInfo) => void)	拖拽進(jìn)入列表元素范圍內(nèi)時(shí)觸發(fā)。 - event: 見ItemDragInfo對象說明。
onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void)	拖拽在列表元素范圍內(nèi)移動時(shí)觸發(fā)。 - event: 見ItemDragInfo對象說明。 - itemIndex: 拖拽起始位置。 - insertIndex: 拖拽插入位置。
onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void)	拖拽離開列表元素時(shí)觸發(fā)。 - event: 見ItemDragInfo對象說明。 - itemIndex: 拖拽離開的列表元素索引值。
onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void)	綁定該事件的列表元素可作為拖拽釋放目標(biāo)，當(dāng)在列表元素內(nèi)停止拖拽時(shí)觸發(fā)。 - event: 見ItemDragInfo對象說明。 - itemIndex: 拖拽起始位置。 - insertIndex: 拖拽插入位置。 - isSuccess: 是否成功釋放。說明：跨List拖拽時(shí)，當(dāng)拖拽釋放的位置綁定了onItemDrop時(shí)會返回true，否則為false。List內(nèi)部拖拽時(shí)，isSuccess為onItemMove事件的返回值。

ScrollState枚舉說明

從API version 9開始，該接口支持在ArkTS卡片中使用。

名稱	描述
Idle	未滑動狀態(tài)。
Scroll	手指拖動狀態(tài)。
Fling	慣性滑動狀態(tài)。

說明

要使List處于可編輯模式需配合onItemDelete事件和ListItem的editable屬性，即可編輯模式實(shí)現(xiàn)刪除列表項(xiàng)功能，需滿足以下條件：

editMode屬性設(shè)置為true。
綁定onItemDelete事件，且事件回調(diào)返回true。
ListItem的editable屬性設(shè)置為true。

實(shí)現(xiàn)ListItem拖拽，需滿足以下條件：

editMode屬性設(shè)置為true。
綁定onDragStart事件，且事件回調(diào)中返回浮動UI布局。

示例

示例1


// xxx.ets
@Entry
@Component
struct ListExample {
  private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

  build() {
    Column() {
      List({ space: 20, initialIndex: 0 }) {
        ForEach(this.arr, (item) => {
          ListItem() {
            Text('' + item)
              .width('100%').height(100).fontSize(16)
              .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF)
          }
        }, item => item)
      }
      .listDirection(Axis.Vertical) // 排列方向
      .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) // 每行之間的分界線
      .edgeEffect(EdgeEffect.Spring) // 滑動到邊緣無效果
      .onScrollIndex((firstIndex: number, lastIndex: number) => {
        console.info('first' + firstIndex)
        console.info('last' + lastIndex)
      })
      .width('90%')
    }
    .width('100%')
    .height('100%')
    .backgroundColor(0xDCDCDC)
    .padding({ top: 5 })
  }
}

示例2


// xxx.ets
@Entry
@Component
struct ListLanesExample {
  @State arr: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"]
  @State alignListItem: ListItemAlign = ListItemAlign.Start

  build() {
    Column() {
      List({ space: 20, initialIndex: 0 }) {
        ForEach(this.arr, (item) => {
          ListItem() {
            Text('' + item)
              .width('100%')
              .height(100)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .borderRadius(10)
              .backgroundColor(0xFFFFFF)
          }
          .border({ width: 2, color: Color.Green })
        }, item => item)
      }
      .height(300)
      .width("90%")
      .editMode(true)
      .border({ width: 3, color: Color.Red })
      .lanes({ minLength: 40, maxLength: 40 })
      .alignListItem(this.alignListItem)

      Button("點(diǎn)擊更改alignListItem:" + this.alignListItem).onClick(() => {
        if (this.alignListItem == ListItemAlign.Start) {
          this.alignListItem = ListItemAlign.Center
        } else if (this.alignListItem == ListItemAlign.Center) {
          this.alignListItem = ListItemAlign.End
        } else {
          this.alignListItem = ListItemAlign.Start
        }
      })
    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
  }
}

示例3


// xxx.ets
@Entry
@Component
struct ListExample{
  @State arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
  @State editFlag: boolean = false

  build(){
    Stack({alignContent: Alignment.TopStart}) {
      Column(){
        List({space:20, initialIndex:0}) {
          ForEach(this.arr, (item, index) => {
            ListItem() {
              Flex({direction: FlexDirection.Row, alignItems: ItemAlign.Center}) {
                Text('' + item)
                  .width('100%')
                  .height(80)
                  .fontSize(20)
                  .textAlign(TextAlign.Center)
                  .borderRadius(10)
                  .backgroundColor(0xFFFFFF)
                  .flexShrink(1)
                if (this.editFlag) {
                  Button() {
                    Text("delete").fontSize(16)
                  }.width('30%').height(40)
                  .onClick(() => {
                    console.info(this.arr[index] + 'Delete')
                    this.arr.splice(index, 1)
                    console.info(JSON.stringify(this.arr))
                    this.editFlag = false
                  }).stateEffect(true)
                }
              }
            }
          }, item => item)
        }.width('90%')
      }.width('100%')

      Button('edit list')
        .onClick(() => {
          this.editFlag = !this.editFlag
        }).margin({ top: 5, left: 20 })
    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
  }
}

以上內(nèi)容是否對您有幫助：

← 網(wǎng)格容器中單項(xiàng)內(nèi)容容器

列表具體item →

寫筆記

我要補(bǔ)充

列表項(xiàng)

子組件

接口

屬性

ListItemAlign9+枚舉說明

StickyStyle9+枚舉說明

事件

ScrollState枚舉說明

示例

示例1

示例2

示例3

推薦文章

推薦教程

推薦課程