ListItem

The ListItem component displays specific items in the list. It must be used together with List.

NOTE

• This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version.
• The parent of this component can only be List or ListItemGroup.
• When this component is used with LazyForEach, its child components are created when it is created. When this component is used with if/else or ForEach, or when the parent component is List or ListItemGroup, its child components are created when it is laid out.

Child Components

This component can contain a single child component.

APIs

ListItem¹⁰⁺

ListItem(value?: ListItemOptions)

Widget capability: This API can be used in ArkTS widgets since API version 10.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

ListItem^(deprecated)

ListItem(value?: string)

This API is deprecated since API version 10. You are advised to use ListItem¹⁰⁺ instead.

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

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Attributes

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

sticky^(deprecated)

sticky(value: Sticky)

Sets the sticky effect of the list item.

This attribute is deprecated since API version 9. You are advised to use the sticky attribute of the List component instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

editable^(deprecated)

editable(value: boolean|EditMode)

Sets whether to enable edit mode, where the list item can be deleted or moved.

This API is deprecated since API version 9. There is no substitute API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

selectable⁸⁺

selectable(value: boolean)

Sets whether the list item is selectable for multiselect. This attribute takes effect only when mouse frame selection is enabled for the parent List container.

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

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

selected¹⁰⁺

selected(value: boolean)

Sets whether the list item is selected. This attribute supports two-way binding through $$. This attribute must be used before the style for the selected state is set. Otherwise, the style settings will not take effect.

Widget capability: This API can be used in ArkTS widgets since API version 10.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

swipeAction⁹⁺

swipeAction(value: SwipeActionOptions)

Sets the swipe action item displayed when the list item is swiped out from the screen edge.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Sticky^(deprecated)

This API is deprecated since API version 9. You are advised to use the stickyStyle enum of the List component instead.

System capability: SystemCapability.ArkUI.ArkUI.Full

EditMode^(deprecated)

This API is deprecated since API version 9. There is no substitute API.

System capability: SystemCapability.ArkUI.ArkUI.Full

SwipeEdgeEffect⁹⁺

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

SwipeActionOptions⁹⁺

The top level of the @builder function corresponding to start and end must be a single component and cannot be an if/else, ForEach, or LazyForEach statement.

The swipe gesture works only in the list item area. If a swipe causes a child component to extend beyond the list item area, the portion outside the area does not respond to the swipe. In light of this, avoid setting swipeAction to a component too wide in a multi-column list.

System capability: SystemCapability.ArkUI.ArkUI.Full

SwipeActionItem¹⁰⁺

Describes the swipe action item.
For a list in vertical layout, it refers to the delete option displayed on the left (or right) of the list item when the list item is swiped right (or left).
For a list in horizontal layout, it refers to the delete option displayed below (or above) the list item when the list item is swiped up (or down).

System capability: SystemCapability.ArkUI.ArkUI.Full

ListItemOptions¹⁰⁺

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

ListItemStyle¹⁰⁺

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

SwipeActionState¹¹⁺

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.ArkUI.ArkUI.Full

Events

onSelect⁸⁺

onSelect(event: (isSelected: boolean) => void)

Triggered when the selected state of the list item for multiselect changes.

Widget capability: This API can be used in ArkTS widgets since API version 9.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Example

Example 1: Creating a List Item

This example demonstrates the basic usage of creating a list item.

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

  build() {
    Column() {
      List({ space: 20, initialIndex: 0 }) {
        ForEach(this.arr, (item: number) => {
          ListItem() {
            Text('' + item)
              .width('100%')
              .height(100)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .borderRadius(10)
              .backgroundColor(0xFFFFFF)
          }
        }, (item: string) => item)
      }.width('90%')
      .scrollBar(BarState.Off)
    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
  }
}

Example 2: Setting the Swipe Action Item

This example shows how to set the swipe action item for a list item using swipeAction.

// xxx.ets
@Entry
@Component
struct ListItemExample2 {
  @State arr: number[] = [0, 1, 2, 3, 4]
  @State enterEndDeleteAreaString: string = "not enterEndDeleteArea"
  @State exitEndDeleteAreaString: string = "not exitEndDeleteArea"
  private scroller: ListScroller = new ListScroller()

  @Builder itemEnd() {
    Row() {
      Button("Delete").margin("4vp")
      Button("Set").margin("4vp").onClick(() => {
        this.scroller.closeAllSwipeActions()
      })
    }.padding("4vp").justifyContent(FlexAlign.SpaceEvenly)
  }

  build() {
    Column() {
      List({ space: 10, scroller: this.scroller }) {
        ForEach(this.arr, (item: number) => {
          ListItem() {
            Text("item" + item)
              .width('100%')
              .height(100)
              .fontSize(16)
              .textAlign(TextAlign.Center)
              .borderRadius(10)
              .backgroundColor(0xFFFFFF)
          }
          .transition({ type: TransitionType.Delete, opacity: 0 })
          .swipeAction({
            end: {
              builder: () => { this.itemEnd() },
              onAction: () => {
                animateTo({ duration: 1000 }, () => {
                  let index = this.arr.indexOf(item)
                  this.arr.splice(index, 1)
                })
              },
              actionAreaDistance: 56,
              onEnterActionArea: () => {
                this.enterEndDeleteAreaString = "enterEndDeleteArea"
                this.exitEndDeleteAreaString = "not exitEndDeleteArea"
              },
              onExitActionArea: () => {
                this.enterEndDeleteAreaString = "not enterEndDeleteArea"
                this.exitEndDeleteAreaString = "exitEndDeleteArea"
              }
            }
          })
        }, (item: string) => item)
      }
      Text(this.enterEndDeleteAreaString).fontSize(20)
      Text(this.exitEndDeleteAreaString).fontSize(20)
    }
    .padding(10)
    .backgroundColor(0xDCDCDC)
    .width('100%')
    .height('100%')
  }
}

Example 3: Applying a Card-style Effect

This example illustrates the card-style effect of the ListItem component.

// xxx.ets
@Entry
@Component
struct ListItemExample3 {
  build() {
    Column() {
      List({ space: "4vp", initialIndex: 0 }) {
        ListItemGroup({ style: ListItemGroupStyle.CARD }) {
          ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => {
            ListItem({ style: itemStyle }) {
              Text("" + index)
                .width("100%")
                .textAlign(TextAlign.Center)
            }
          })
        }
        ForEach([ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE], (itemStyle: number, index?: number) => {
          ListItem({ style: itemStyle }) {
            Text("" + index)
              .width("100%")
              .textAlign(TextAlign.Center)
          }
        })
      }
      .width('100%')
      .multiSelectable(true)
      .backgroundColor(0xDCDCDC)
    }
    .width('100%')
    .padding({ top: 5 })
  }
}

Example 4: Setting the Swipe Action Item Using ComponentContent

This example demonstrates how to set swipe action items for list items using ComponentContent.

// xxx.ets
import { ComponentContent } from '@kit.ArkUI';

class BuilderParams {
  text: string|Resource;
  scroller: ListScroller
  constructor(text: string|Resource, scroller: ListScroller) {
    this.text = text;
    this.scroller = scroller;
  }
}

@Builder
function itemBuilder(params: BuilderParams) {
  Row() {
    Button(params.text).margin("4vp")
    Button("Set").margin("4vp").onClick(() => {
      params.scroller.closeAllSwipeActions()
    })
  }.padding("4vp").justifyContent(FlexAlign.SpaceEvenly)
}
@Component
struct MyListItem {
  scroller: ListScroller = new ListScroller()
  @State arr: number[] = [0, 1, 2, 3, 4]
  @State project ?: number = 0
  startBuilder ?: ComponentContent<BuilderParams> = undefined
  endBuilder ?: ComponentContent<BuilderParams> = undefined

  builderParam = new BuilderParams("delete", this.scroller)

  aboutToAppear(): void {
    this.startBuilder = new ComponentContent(this.getUIContext(), wrapBuilder(itemBuilder), this.builderParam)
    this.endBuilder = new ComponentContent(this.getUIContext(), wrapBuilder(itemBuilder), this.builderParam)
  }
  GetStartBuilder() {
    this.startBuilder?.update(new BuilderParams("StartDelete", this.scroller));
    return this.startBuilder;
  }
  GetEndBuilder() {
    this.endBuilder?.update(new BuilderParams("EndDelete", this.scroller));
    return this.endBuilder;
  }
  build() {
    ListItem() {
      Text("item" + this.project)
        .width('100%')
        .height(100)
        .fontSize(16)
        .textAlign(TextAlign.Center)
        .borderRadius(10)
        .backgroundColor(0xFFFFFF)
    }
    .transition({ type: TransitionType.Delete, opacity: 0 })
    .swipeAction({
      end: {
        builderComponent: this.GetEndBuilder(),
        onAction: () => {
          animateTo({ duration: 1000 }, () => {
            let index = this.arr.indexOf(this.project)
            this.arr.splice(index, 1)
          })
        },
        actionAreaDistance: 56
      },
      start: {
        builderComponent: this.GetStartBuilder(),
        onAction: () => {
          animateTo({ duration: 1000 }, () => {
            let index = this.arr.indexOf(this.project)
            this.arr.splice(index, 1)
          })
        },
        actionAreaDistance: 56
      }
    })
    .padding(5)
  }
}

@Entry
@Component
struct ListItemExample {
  @State arr: number[] = [0, 1, 2, 3, 4]
  private scroller: ListScroller = new ListScroller()

  build() {
    Column() {
      List({ space: 10, scroller: this.scroller }) {
        ListItemGroup() {
          ForEach(this.arr, (project: number) => {
            MyListItem({ scroller: this.scroller, project: project, arr:this.arr })
          }, (item: string) => item)
        }
      }
    }
    .padding(10)
    .backgroundColor(0xDCDCDC)
    .width('100%')
    .height('100%')
  }
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArcButton

harmony 鸿蒙ArcSlider

harmony 鸿蒙Chip

harmony 鸿蒙ChipGroup

harmony 鸿蒙ComposeListItem

harmony 鸿蒙ComposeTitleBar

harmony 鸿蒙advanced.Counter

harmony 鸿蒙Dialog Box (Dialog)

harmony 鸿蒙DialogV2

harmony 鸿蒙DownloadFileButton