List

The <List> component provides a list container that presents a series of list items arranged in a column with the same width. It supports presentations of the same type of data in a multiple and coherent row style, for example, images or text.

NOTE

• This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
• This component can produce a bounce effect only when there is more than one screen of content.

Child Components

This component supports the <ListItem> and <ListItemGroup> child components.

NOTE

Below are the rules for calculating the indexes of the child components of <List>:

The index increases in ascending order of child components.

In the if/else statement, only the child components in the branch where the condition is met participate in the index calculation.

In the ForEach or LazyForEach statement, the indexes of all expanded subnodes are calculated.

If the values of if/else, ForEach, and LazyForEach change, the indexes of subnodes are updated.

Each <ListItemGroup> component is taken as a whole and assigned an index, and the indexes of the list items within are not included in the index calculation.

Child components of <List> whose visibility attribute is set to Hidden or None are included in the index calculation.

Child components of <List> whose visibility attribute is set to None are not displayed, but the spacing above and below them still takes effect.

APIs

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

Since API version 9, this API is supported in ArkTS widgets.

Parameters

Attributes

In addition to the universal attributes, the following attributes are supported.

ListItemAlign⁹⁺

This API is supported in ArkTS widgets.

StickyStyle⁹⁺

This API is supported in ArkTS widgets.

NOTE

The default value of the universal attribute clip is true for the <List> component.

Events

ScrollState

Since API version 9, this API is supported in ArkTS widgets.

NOTE

To enable the editable mode for a list, the following conditions must be met:

• editMode is set to true.

• The list is bound to the onItemDelete event and the event returns true in the event callback.

• The editable attribute of ListItem is set to true.

To enable dragging for a list item, the following conditions must be met:

• editMode is set to true.

• The list item is bound to the onDragStart event and the event returns a floating UI during event callback.

Example

// 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) // Arrangement direction
      .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) // Divider
      .edgeEffect(EdgeEffect.Spring) // No effect when the list scrolls to the edge.
      .onScrollIndex((firstIndex: number, lastIndex: number) => {
        console.info('first' + firstIndex)
        console.info('last' + lastIndex)
      })
      .width('90%')
    }
    .width('100%')
    .height('100%')
    .backgroundColor(0xDCDCDC)
    .padding({ top: 5 })
  }
}

// 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("Change 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 })
  }
}