【鸿蒙开发】系统组件List，ListItem，ListItemGroup

List组件

List列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。

包含ListItem，ListItemGroup子组件

接口：

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

参数：

参数名	参数类型	必填	参数描述
space	number | string	否	子组件主轴方向的间隔。 默认值：0 说明： 设置为除-1外其他负数或百分比时，按默认值显示。 space参数值小于List分割线宽度时，子组件主轴方向的间隔取分割线宽度。
initialIndex	number	否	设置当前List初次加载时视口起始位置显示的item的索引值。 默认值：0 说明： 设置为除-1外其他负数或超过了当前List最后一个item的索引值时视为无效取值，无效取值按默认值显示。
scroller	Scroller	否	可滚动组件的控制器。用于与可滚动组件进行绑定。 说明： 不允许和其他滚动类组件绑定同一个滚动控制对象。

属性：

除支持通用属性外，还支持以下属性：

名称	参数类型	描述
listDirection	Axis	设置List组件排列方向。 默认值：Axis.Vertical 从API version 9开始，该接口支持在ArkTS卡片中使用。
divider	{ strokeWidth: Length, color?:ResourceColor, startMargin?: Length, endMargin?: Length } | null	设置ListItem分割线样式，默认无分割线。 - strokeWidth: 分割线的线宽。 - color: 分割线的颜色。 - startMargin: 分割线与列表侧边起始端的距离。 - endMargin: 分割线与列表侧边结束端的距离。 从API version 9开始，该接口支持在ArkTS卡片中使用。 endMargin +startMargin 不能超过列宽度。 startMargin和endMargin不支持设置百分比。 List的分割线画在主轴方向两个子组件之间，第一个子组件上方和最后一个子组件下方不会绘制分割线。 多列模式下，ListItem与ListItem之间的分割线起始边距从每一列的交叉轴方向起始边开始计算，其他情况从List交叉轴方向起始边开始计算。
scrollBar	BarState	设置滚动条状态。 默认值：BarState.Off 从API version 9开始，该接口支持在ArkTS卡片中使用。
cachedCount	number	设置列表中ListItem/ListItemGroup的预加载数量，其中ListItemGroup将作为一个整体进行计算，ListItemGroup中的所有ListItem会一次性全部加载出来。具体使用可参考减少应用白块说明。 默认值：1 从API version 9开始，该接口支持在ArkTS卡片中使用。 说明： 单列模式下，会在List显示的ListItem前后各缓存cachedCount个ListItem。 多列模式下， 会在List显示的ListItem前后各缓存cachedCount*列数个ListItem。
editMode(deprecated)	boolean	声明当前List组件是否处于可编辑模式。可参考示例3实现删除选中的list项。 从API version9开始废弃。 默认值：false
edgeEffect	EdgeEffect	设置组件的滑动效果。 默认值：EdgeEffect.Spring 从API version 9开始，该接口支持在ArkTS卡片中使用。
chainAnimation	boolean	设置当前List是否启用链式联动动效，开启后列表滑动以及顶部和底部拖拽时会有链式联动的效果。链式联动效果：List内的list-item间隔一定距离，在基本的滑动交互行为下，主动对象驱动从动对象进行联动，驱动效果遵循弹簧物理动效。 默认值：false - false：不启用链式联动。 - true：启用链式联动。 从API version 9开始，该接口支持在ArkTS卡片中使用。
multiSelectable8+	boolean	是否开启鼠标框选。 默认值：false - false：关闭框选。 - true：开启框选。 从API version 9开始，该接口支持在ArkTS卡片中使用。
lanes9+	number | LengthConstrain	以列模式为例（listDirection为Axis.Vertical）: lanes用于决定List组件在交叉轴方向按几列布局。 默认值：1 规则如下： - lanes为指定的数量时，根据指定的数量与List组件的交叉轴尺寸除以列数作为列的宽度。 - lanes设置了{minLength，maxLength}时，根据List组件的宽度自适应决定lanes数量（即列数），保证缩放过程中lane的宽度符合{minLength，maxLength}的限制。其中，minLength条件会被优先满足，即优先保证符合ListItem的交叉轴尺寸符合最小限制。 - lanes设置了{minLength，maxLength}，如果父组件交叉轴方向尺寸约束为无穷大时，固定按一列排列，列宽度按显示区域内最大的ListItem计算。 - ListItemGroup在多列模式下也是独占一行，ListItemGroup中的ListItem按照List组件的lanes属性设置值来布局。 - lanes设置了{minLength，maxLength}时，计算列数会按照ListItemGroup的交叉轴尺寸计算。当ListItemGroup交叉轴尺寸与List交叉轴尺寸不一致时ListItemGroup中的列数与List中的列数可能不一样。 该接口支持在ArkTS卡片中使用。
alignListItem9+	ListItemAlign	List交叉轴方向宽度大于ListItem交叉轴宽度 * lanes时，ListItem在List交叉轴方向的布局方式，默认为首部对齐。 默认值：ListItemAlign.Start 该接口支持在ArkTS卡片中使用。
sticky9+	StickyStyle	配合ListItemGroup组件使用，设置ListItemGroup中header和footer是否要吸顶或吸底。 默认值：StickyStyle.None 该接口支持在ArkTS卡片中使用。 说明： sticky属性可以设置为 StickyStyle.Header | StickyStyle.Footer 以同时支持header吸顶和footer吸底。

ListItemAlign：

名称	描述
Start	ListItem在List中，交叉轴方向首部对齐。
Center	ListItem在List中，交叉轴方向居中对齐。
End	ListItem在List中，交叉轴方向尾部对齐。

StickyStyle：

名称	描述
None	ListItemGroup的header不吸顶，footer不吸底。
Header	ListItemGroup的header吸顶，footer不吸底。
Footer	ListItemGroup的footer吸底，header不吸顶。

ListItem组件

ListItem用来展示列表具体item，必须配合List来使用。

可以包含单个子组件。

接口：

ListItem(value?: string)

属性：

除支持通用属性外，还支持以下属性：

名称	参数类型	描述
sticky(deprecated)	Sticky	设置ListItem吸顶效果。 默认值：Sticky.None 从API version9开始废弃，推荐使用List组件sticky属性。
editable(deprecated)	boolean | EditMode	当前ListItem元素是否可编辑，进入编辑模式后可删除或移动列表项。 从API version9开始废弃。 默认值：false
selectable8+	boolean	当前ListItem元素是否可以被鼠标框选。 从API version 9开始，该接口支持在ArkTS卡片中使用。 说明： 外层List容器的鼠标框选开启时，ListItem的框选才生效。 默认值：true
swipeAction9+	{ start?: CustomBuilder, end?:CustomBuilder, edgeEffect?: SwipeEdgeEffect, }	用于设置ListItem的划出组件。 - start: ListItem向右划动时item左边的组件（List垂直布局时）或ListItem向下划动时item上方的组件（List水平布局时）。 - end: ListItem向左划动时item右边的组件（List垂直布局时）或ListItem向上划动时item下方的组件（List水平布局时）。 - edgeEffect: 滑动效果。 说明： start和end对应的@builder函数中顶层必须是单个组件，不能是if/else、ForEach、LazyForEach语句。

EditMode：

名称	描述
None	编辑操作不限制。
Deletable	可删除。
Movable	可移动。

SwipeEdgeEffect：

名称	描述
Spring	ListItem划动距离超过划出组件大小后可以继续划动，松手后按照弹簧阻尼曲线回弹。
None	ListItem划动距离不能超过划出组件大小。

ListItemGroup组件

ListItemGroup该组件用来展示列表item分组，宽度默认充满List组件，必须配合List组件来使用。

包含ListItem子组件

接口：

ListItemGroup(options?: {header?: CustomBuilder, footer?: CustomBuilder, space?: number | string})

参数：

参数名	参数类型	必填	参数描述
header	CustomBuilder	否	设置ListItemGroup头部组件。
footer	CustomBuilder	否	设置ListItemGroup尾部组件。
space	number | string	否	列表项间距。只作用于ListItem与ListItem之间，不作用于header与ListItem、footer与ListItem之间。

属性：

名称	参数类型	描述
divider	{ strokeWidth: Length, color?: ResourceColor, startMargin?: Length, endMargin?: Length } | null	用于设置ListItem分割线样式，默认无分割线。 strokeWidth: 分割线的线宽。 color: 分割线的颜色。 startMargin： 分割线距离列表侧边起始端的距离。 endMargin: 分割线距离列表侧边结束端的距离。 strokeWidth, startMargin和endMargin不支持设置百分比。

示例

@Entry
@Component
struct APage {
  @Builder
  HeaderTitle(title: string) {
    Text(title)
      .fontSize(20)
      .fontWeight(900)
      .height(50)
      .backgroundColor('#ccc')
      .width('100%')
  }

  @Builder
  delButton() {
    Button("删除")
  }

  build() {
    Column() {
      List({ space: 10 }) {
        ListItemGroup({ header: this.HeaderTitle("李"), space: 20 }) {
          ListItem() {
            Text("李李1")
          }
          .width('100%')
          .height(50)
          .swipeAction({ end: this.delButton() })

          ListItem() {
            Text("李李2")
          }
          .width('100%')
          .height(50)

          ListItem() {
            Text("李李3")
          }
          .width('100%')
          .height(50)
        }
        .width("100%")
        .divider({ strokeWidth: 3, color: "#ccc" })

        ListItemGroup({ header: this.HeaderTitle("刘") }) {
          ListItem() {
            Text("刘刘1")
          }
          .width('100%')
          .height(50)

          ListItem() {
            Text("刘刘2")
          }
          .width('100%')
          .height(50)

          ListItem() {
            Text("刘刘3")
          }
          .width('100%')
          .height(50)
        }
        .width("100%")
        .divider({ strokeWidth: 3, color: "#ccc" })

      }
      .width("100%")
      .height(400)
      .alignListItem(ListItemAlign.Center)
      .listDirection(Axis.Vertical)
      .scrollBar(BarState.Auto)
    }
    .width("100%")
    .height("100%")
  }
}