列表項(xiàng)

2024-01-22 17:53 更新

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

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

子組件

包含ListItem、ListItemGroup子組件。

說(shuō)明

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

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

接口

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

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

參數(shù)：

參數(shù)名

參數(shù)類型

必填

參數(shù)描述

space

number | string

否

子組件主軸方向的間隔。

默認(rèn)值：0

說(shuō)明：

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

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

initialIndex

number

否

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

默認(rèn)值：0

說(shuō)明：

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

scroller

Scroller

否

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

說(shuō)明：

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

屬性

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

名稱

參數(shù)類型

描述

listDirection

Axis

設(shè)置List組件排列方向。

默認(rèn)值：Axis.Vertical

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

divider

{

strokeWidth: Length,

color?:ResourceColor,

startMargin?: Length,

endMargin?: Length

} | null

設(shè)置ListItem分割線樣式，默認(rèn)無(wú)分割線。

- strokeWidth: 分割線的線寬。

- color: 分割線的顏色。

- startMargin: 分割線與列表側(cè)邊起始端的距離。

- endMargin: 分割線與列表側(cè)邊結(jié)束端的距離。

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

endMargin +startMargin 不能超過(guò)列寬度。

startMargin和endMargin不支持設(shè)置百分比。

List的分割線畫在主軸方向兩個(gè)子組件之間，第一個(gè)子組件上方和最后一個(gè)子組件下方不會(huì)繪制分割線。

多列模式下，ListItem與ListItem之間的分割線起始邊距從每一列的交叉軸方向起始邊開(kāi)始計(jì)算，其他情況從List交叉軸方向起始邊開(kāi)始計(jì)算。

scrollBar

BarState

設(shè)置滾動(dòng)條狀態(tài)。

默認(rèn)值：BarState.Off

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

cachedCount

number

設(shè)置列表中ListItem/ListItemGroup的預(yù)加載數(shù)量，其中ListItemGroup將作為一個(gè)整體進(jìn)行計(jì)算，ListItemGroup中的所有ListItem會(huì)一次性全部加載出來(lái)。具體使用可參考減少應(yīng)用白塊說(shuō)明。

默認(rèn)值：1

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

說(shuō)明：

單列模式下，會(huì)在List顯示的ListItem前后各緩存cachedCount個(gè)ListItem。

多列模式下， 會(huì)在List顯示的ListItem前后各緩存cachedCount*列數(shù)個(gè)ListItem。

editMode(deprecated)

boolean

聲明當(dāng)前List組件是否處于可編輯模式。可參考示例3實(shí)現(xiàn)刪除選中的list項(xiàng)。

從API version9開(kāi)始廢棄。

默認(rèn)值：false

edgeEffect

EdgeEffect

設(shè)置組件的滑動(dòng)效果。

默認(rèn)值：EdgeEffect.Spring

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

chainAnimation

boolean

設(shè)置當(dāng)前List是否啟用鏈?zhǔn)铰?lián)動(dòng)動(dòng)效，開(kāi)啟后列表滑動(dòng)以及頂部和底部拖拽時(shí)會(huì)有鏈?zhǔn)铰?lián)動(dòng)的效果。鏈?zhǔn)铰?lián)動(dòng)效果：List內(nèi)的list-item間隔一定距離，在基本的滑動(dòng)交互行為下，主動(dòng)對(duì)象驅(qū)動(dòng)從動(dòng)對(duì)象進(jìn)行聯(lián)動(dòng)，驅(qū)動(dòng)效果遵循彈簧物理動(dòng)效。

默認(rèn)值：false

- false：不啟用鏈?zhǔn)铰?lián)動(dòng)。

- true：?jiǎn)⒂面準(zhǔn)铰?lián)動(dòng)。

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

multiSelectable8+

boolean

是否開(kāi)啟鼠標(biāo)框選。

默認(rèn)值：false

- false：關(guān)閉框選。

- true：開(kāi)啟框選。

從API version 9開(kāi)始，該接口支持在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ù)），保證縮放過(guò)程中l(wèi)ane的寬度符合{minLength，maxLength}的限制。其中，minLength條件會(huì)被優(yōu)先滿足，即優(yōu)先保證符合ListItem的交叉軸尺寸符合最小限制。

- lanes設(shè)置了{(lán)minLength，maxLength}，如果父組件交叉軸方向尺寸約束為無(wú)窮大時(shí)，固定按一列排列，列寬度按顯示區(qū)域內(nèi)最大的ListItem計(jì)算。

- ListItemGroup在多列模式下也是獨(dú)占一行，ListItemGroup中的ListItem按照List組件的lanes屬性設(shè)置值來(lái)布局。

- lanes設(shè)置了{(lán)minLength，maxLength}時(shí)，計(jì)算列數(shù)會(huì)按照ListItemGroup的交叉軸尺寸計(jì)算。當(dāng)ListItemGroup交叉軸尺寸與List交叉軸尺寸不一致時(shí)ListItemGroup中的列數(shù)與List中的列數(shù)可能不一樣。

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

alignListItem9+

ListItemAlign

List交叉軸方向?qū)挾却笥贚istItem交叉軸寬度 * lanes時(shí)，ListItem在List交叉軸方向的布局方式，默認(rèn)為首部對(duì)齊。

默認(rèn)值：ListItemAlign.Start

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

sticky9+

StickyStyle

配合ListItemGroup組件使用，設(shè)置ListItemGroup中header和footer是否要吸頂或吸底。

默認(rèn)值：StickyStyle.None

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

說(shuō)明：

sticky屬性可以設(shè)置為 StickyStyle.Header | StickyStyle.Footer 以同時(shí)支持header吸頂和footer吸底。

ListItemAlign9+枚舉說(shuō)明

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

名稱

描述

Start

ListItem在List中，交叉軸方向首部對(duì)齊。

Center

ListItem在List中，交叉軸方向居中對(duì)齊。

End

ListItem在List中，交叉軸方向尾部對(duì)齊。

StickyStyle9+枚舉說(shuō)明

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

名稱

描述

None

ListItemGroup的header不吸頂，footer不吸底。

Header

ListItemGroup的header吸頂，footer不吸底。

Footer

ListItemGroup的footer吸底，header不吸頂。

說(shuō)明

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

事件

名稱

功能描述

onItemDelete(deprecated)(event: (index: number) => boolean)

當(dāng)List組件在編輯模式時(shí)，點(diǎn)擊ListItem右邊出現(xiàn)的刪除按鈕時(shí)觸發(fā)。

從API version9開(kāi)始廢棄。

- index: 被刪除的列表項(xiàng)的索引值。

onScroll(event: (scrollOffset: number, scrollState: ScrollState) => void)

列表滑動(dòng)時(shí)觸發(fā)。

- scrollOffset: 每幀滾動(dòng)的偏移量，List的內(nèi)容向上滾動(dòng)時(shí)偏移量為正，向下滾動(dòng)時(shí)偏移量為負(fù)。

- scrollState: 當(dāng)前滑動(dòng)狀態(tài)。

使用控制器調(diào)用ScrollEdge和ScrollToIndex時(shí)不會(huì)觸發(fā)，其余情況有滾動(dòng)就會(huì)觸發(fā)該事件。

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

onScrollIndex(event: (start: number, end: number) => void)

列表滑動(dòng)時(shí)觸發(fā)。

計(jì)算索引值時(shí)，ListItemGroup作為一個(gè)整體占一個(gè)索引值，不計(jì)算ListItemGroup內(nèi)部ListItem的索引值。

- start: 滑動(dòng)起始位置索引值。

- end: 滑動(dòng)結(jié)束位置索引值。

觸發(fā)該事件的條件：列表初始化時(shí)會(huì)觸發(fā)一次，List顯示區(qū)域內(nèi)第一個(gè)子組件的索引值或后一個(gè)子組件的索引值有變化時(shí)會(huì)觸發(fā)。

List的邊緣效果為彈簧效果時(shí)，在List劃動(dòng)到邊緣繼續(xù)劃動(dòng)和松手回彈過(guò)程不會(huì)觸發(fā)onScrollIndex事件。

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

onReachStart(event: () => void)

列表到達(dá)起始位置時(shí)觸發(fā)。

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

說(shuō)明：

List初始化時(shí)如果initialIndex為0會(huì)觸發(fā)一次，List滾動(dòng)到起始位置時(shí)觸發(fā)一次。List邊緣效果為彈簧效果時(shí)，劃動(dòng)經(jīng)過(guò)起始位置時(shí)觸發(fā)一次，回彈回起始位置時(shí)再觸發(fā)一次。

onReachEnd(event: () => void)

列表到底末尾位置時(shí)觸發(fā)。

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

說(shuō)明：

List邊緣效果為彈簧效果時(shí)，劃動(dòng)經(jīng)過(guò)末尾位置時(shí)觸發(fā)一次，回彈回末尾位置時(shí)再觸發(fā)一次。

onScrollFrameBegin9+(event: (offset: number, state: ScrollState) => { offsetRemain })

列表開(kāi)始滑動(dòng)時(shí)觸發(fā)，事件參數(shù)傳入即將發(fā)生的滑動(dòng)量，事件處理函數(shù)中可根據(jù)應(yīng)用場(chǎng)景計(jì)算實(shí)際需要的滑動(dòng)量并作為事件處理函數(shù)的返回值返回，列表將按照返回值的實(shí)際滑動(dòng)量進(jìn)行滑動(dòng)。

- offset：即將發(fā)生的滑動(dòng)量，單位vp。

- state：當(dāng)前滑動(dòng)狀態(tài)。

- offsetRemain：實(shí)際滑動(dòng)量，單位vp。

觸發(fā)該事件的條件：手指拖動(dòng)List、List慣性劃動(dòng)時(shí)每幀開(kāi)始時(shí)觸發(fā)；List超出邊緣回彈、使用滾動(dòng)控制器的滾動(dòng)不會(huì)觸發(fā)。

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

說(shuō)明：

當(dāng)listDirection的值為Axis.Vertical時(shí)，返回垂直方向滑動(dòng)量，當(dāng)listDirection的值為Axis.Horizontal時(shí)，返回水平方向滑動(dòng)量。

onScrollStart9+(event: () => void)

列表滑動(dòng)開(kāi)始時(shí)觸發(fā)。手指拖動(dòng)列表或列表的滾動(dòng)條觸發(fā)的滑動(dòng)開(kāi)始時(shí)，會(huì)觸發(fā)該事件。使用Scroller滑動(dòng)控制器觸發(fā)的帶動(dòng)畫的滑動(dòng)，動(dòng)畫開(kāi)始時(shí)會(huì)觸發(fā)該事件。

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

onScrollStop(event: () => void)

列表滑動(dòng)停止時(shí)觸發(fā)。手拖動(dòng)列表或列表的滾動(dòng)條觸發(fā)的滑動(dòng)，手離開(kāi)屏幕并且滑動(dòng)停止時(shí)會(huì)觸發(fā)該事件；使用Scroller滑動(dòng)控制器觸發(fā)的帶動(dòng)畫的滑動(dòng)，動(dòng)畫停止會(huì)觸發(fā)該事件。

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

onItemMove(event: (from: number, to: number) => boolean)

列表元素發(fā)生移動(dòng)時(shí)觸發(fā)。

- from: 移動(dòng)前索引值。

- to: 移動(dòng)后索引值。

onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => ((() => any) | void)

開(kāi)始拖拽列表元素時(shí)觸發(fā)。

- event: 見(jiàn)ItemDragInfo對(duì)象說(shuō)明。

- itemIndex: 被拖拽列表元素索引值。

onItemDragEnter(event: (event: ItemDragInfo) => void)

拖拽進(jìn)入列表元素范圍內(nèi)時(shí)觸發(fā)。

- event: 見(jiàn)ItemDragInfo對(duì)象說(shuō)明。

onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void)

拖拽在列表元素范圍內(nèi)移動(dòng)時(shí)觸發(fā)。

- event: 見(jiàn)ItemDragInfo對(duì)象說(shuō)明。

- itemIndex: 拖拽起始位置。

- insertIndex: 拖拽插入位置。

onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void)

拖拽離開(kāi)列表元素時(shí)觸發(fā)。

- event: 見(jiàn)ItemDragInfo對(duì)象說(shuō)明。

- itemIndex: 拖拽離開(kāi)的列表元素索引值。

onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void)

綁定該事件的列表元素可作為拖拽釋放目標(biāo)，當(dāng)在列表元素內(nèi)停止拖拽時(shí)觸發(fā)。

- event: 見(jiàn)ItemDragInfo對(duì)象說(shuō)明。

- itemIndex: 拖拽起始位置。

- insertIndex: 拖拽插入位置。

- isSuccess: 是否成功釋放。

說(shuō)明：

跨List拖拽時(shí)，當(dāng)拖拽釋放的位置綁定了onItemDrop時(shí)會(huì)返回true，否則為false。List內(nèi)部拖拽時(shí)，isSuccess為onItemMove事件的返回值。

ScrollState枚舉說(shuō)明

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

名稱

描述

Idle

未滑動(dòng)狀態(tài)。

Scroll

手指拖動(dòng)狀態(tài)。

Fling

慣性滑動(dòng)狀態(tài)。

說(shuō)明

要使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)中返回浮動(dòng)UI布局。

示例

示例1

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

  7.   build() {
  8.     Column() {
  9.       List({ space: 20, initialIndex: 0 }) {
  10.         ForEach(this.arr, (item) => {
  11.           ListItem() {
  12.             Text('' + item)
  13.               .width('100%').height(100).fontSize(16)
  14.               .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF)
  15.           }
  16.         }, item => item)
  17.       }
  18.       .listDirection(Axis.Vertical) // 排列方向
  19.       .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) // 每行之間的分界線
  20.       .edgeEffect(EdgeEffect.Spring) // 滑動(dòng)到邊緣無(wú)效果
  21.       .onScrollIndex((firstIndex: number, lastIndex: number) => {
  22.         console.info('first' + firstIndex)
  23.         console.info('last' + lastIndex)
  24.       })
  25.       .width('90%')
  26.     }
  27.     .width('100%')
  28.     .height('100%')
  29.     .backgroundColor(0xDCDCDC)
  30.     .padding({ top: 5 })
  31.   }
  32. }

示例2

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

  8.   build() {
  9.     Column() {
  10.       List({ space: 20, initialIndex: 0 }) {
  11.         ForEach(this.arr, (item) => {
  12.           ListItem() {
  13.             Text('' + item)
  14.               .width('100%')
  15.               .height(100)
  16.               .fontSize(16)
  17.               .textAlign(TextAlign.Center)
  18.               .borderRadius(10)
  19.               .backgroundColor(0xFFFFFF)
  20.           }
  21.           .border({ width: 2, color: Color.Green })
  22.         }, item => item)
  23.       }
  24.       .height(300)
  25.       .width("90%")
  26.       .editMode(true)
  27.       .border({ width: 3, color: Color.Red })
  28.       .lanes({ minLength: 40, maxLength: 40 })
  29.       .alignListItem(this.alignListItem)
  30. 

  31.       Button("點(diǎn)擊更改alignListItem:" + this.alignListItem).onClick(() => {
  32.         if (this.alignListItem == ListItemAlign.Start) {
  33.           this.alignListItem = ListItemAlign.Center
  34.         } else if (this.alignListItem == ListItemAlign.Center) {
  35.           this.alignListItem = ListItemAlign.End
  36.         } else {
  37.           this.alignListItem = ListItemAlign.Start
  38.         }
  39.       })
  40.     }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
  41.   }
  42. }

示例3

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

  8.   build(){
  9.     Stack({alignContent: Alignment.TopStart}) {
  10.       Column(){
  11.         List({space:20, initialIndex:0}) {
  12.           ForEach(this.arr, (item, index) => {
  13.             ListItem() {
  14.               Flex({direction: FlexDirection.Row, alignItems: ItemAlign.Center}) {
  15.                 Text('' + item)
  16.                   .width('100%')
  17.                   .height(80)
  18.                   .fontSize(20)
  19.                   .textAlign(TextAlign.Center)
  20.                   .borderRadius(10)
  21.                   .backgroundColor(0xFFFFFF)
  22.                   .flexShrink(1)
  23.                 if (this.editFlag) {
  24.                   Button() {
  25.                     Text("delete").fontSize(16)
  26.                   }.width('30%').height(40)
  27.                   .onClick(() => {
  28.                     console.info(this.arr[index] + 'Delete')
  29.                     this.arr.splice(index, 1)
  30.                     console.info(JSON.stringify(this.arr))
  31.                     this.editFlag = false
  32.                   }).stateEffect(true)
  33.                 }
  34.               }
  35.             }
  36.           }, item => item)
  37.         }.width('90%')
  38.       }.width('100%')
  39. 

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

以上內(nèi)容是否對(duì)您有幫助：
在線筆記
App下載
App下載

掃描二維碼

下載編程獅App

公眾號(hào)
微信公眾號(hào)

編程獅公眾號(hào)