鸿蒙开发 ArkTS 组件之 List 篇

星星_坠入梦里
289 阅读3分钟

简介

List 是鸿蒙开发中常用的一种列表容器组件，它包含一系列相同宽度的列表项，适合连续、多行呈现同类数据，例如图片、文本等。

该组件的完整用法请参考官方文档：List 组件

使用方法

（1）关于子组件

List 仅支持 ListItem、ListItemGroup子组件和自定义组件。当子组件的高度超过父组件时，会出现滚动效果。

①简单使用

如果不涉及标题栏或者分组，可以使用 ForEach 渲染所需数据，示例代码如下所示：

List({ space: 10 }) {
  ForEach(Array.from({ length: 20 }), (_: string, index: number) => {
    ListItem() {
      Text(`第 ${index + 1} 项`)
        .fontSize(18)
        .fontWeight(600)
        .width('100%')
        .textAlign(TextAlign.Center)
    }
    .width('90%')
    .height(50)
    .border({ width: 1, color: 0x000000, radius: 10 })
  })
}
.height('100%')
.width('100%')
.scrollBar(BarState.Off) // 设置滚动条状态
.padding(10)
.alignListItem(ListItemAlign.Center)

效果如下图所示：

List-图片1.gif

②使用 ListItemGroup 组件进行分组

通过使用 ListItemGroup 组件，并结合 sticky 属性可以实现吸顶/吸底效果（吸顶居多），该效果类似于手机通讯录按姓名首字母进行分组，向上滑动时分组的标题始终在最上面显示，部分示例代码如下：

// 分组的标题
@State groupArr: string[] = ["第 1 组", "第 2 组", "第 3 组", "第 4 组", "第 5 组"]
 
// ListItemGroup 的 Header 参数
@Builder
ListItemGroupBuilder(title: string) {
  Row() {
    Text(title)
      .fontSize(20)
      .fontWeight(700)
      .fontColor(0xFFFFFF)
      .padding({ top: 10, bottom: 10, left: 20 })
  }
  .width('100%')
  .backgroundColor(0xFF6600)
  .borderRadius(10)
  .margin({ bottom: 10 })
}
 
List({ space: 10 }) {
  ForEach(this.groupArr, (item: string, index: number) => {
    ListItemGroup({ header: this.ListItemGroupBuilder(item), space: 10 }) {
      ForEach(Array.from({ length: 20 }), (_: string, index: number) => {
        ListItem() {
          Text(`第 ${index + 1} 项`)
            .fontSize(18)
            .fontWeight(600)
            .width('100%')
            .textAlign(TextAlign.Center)
        }
        .width('90%')
        .height(50)
        .border({ width: 1, color: 0x000000, radius: 10 })
      })
    }
  })
}
.height('100%')
.width('100%')
.scrollBar(BarState.Off) // 设置滚动条状态
.padding(10)
.alignListItem(ListItemAlign.Center)
.sticky(StickyStyle.Header) // 可用于设置吸顶/吸底

这里只展示常用的属性及参数，完整用法可参考官方文档，上述代码的实现效果如下所示：

List-图片2.gif

（2）List 的常用属性

① listDirection：设置List组件排列方向

② scrollBar：设置滚动条状态

③ edgeEffect：设置边缘滑动效果

④ alignListItem：ListItem 在 List 交叉轴方向的布局方式

以上几个属性的使用方法的示例代码如下所示：

List({ space: 10 }) {
  ForEach(this.groupArr, (item: string, index: number) => {
    ListItemGroup({ header: this.ListItemGroupBuilder(item), space: 10 }) {
      ForEach(Array.from({ length: 18 }), (_: string, index: number) => {
        ListItem() {
          Text(`第 ${index + 1} 项`)
            .fontSize(18)
            .fontWeight(600)
            .width('100%')
            .textAlign(TextAlign.Center)
        }
        .width('90%')
        .height(50)
        .border({ width: 1, color: 0x000000, radius: 10 })
      })
    }
  })
}
.height('100%')
.width('100%')
.listDirection(Axis.Vertical) // 设置List组件排列方向（默认是垂直方向）
.scrollBar(BarState.Off) // 设置滚动条状态
.lanes(2, 10) // 设置List组件的布局列数或行数
.alignListItem(ListItemAlign.Center) // ListItem在List交叉轴方向的布局方式
.edgeEffect(EdgeEffect.Spring) // 设置边缘滑动效果，默认为Spring效果
.sticky(StickyStyle.Header) // 可用于设置吸顶/吸底

（3）List 的常用事件

① onReachEnd

onReachEnd(event: ( ) => void)

列表达到末尾时触发。该事件可以结合 Refresh 组件共同实现下拉刷新、上划加载更多的功能。该事件的示例代码如下：

List({ space: 10, initialIndex: 0 }) {
  ForEach(this.groupArr, (item: string, index: number) => {
    ListItemGroup({ header: this.ListItemGroupBuilder(item), space: 10 }) {
      ForEach(Array.from({ length: 18 }), (_: string, index: number) => {
        ListItem() {
          Text(`第 ${index + 1} 项`)
            .fontSize(18)
            .fontWeight(600)
            .width('100%')
            .textAlign(TextAlign.Center)
        }
        .border({ width: 1, color: 0x000000, radius: 10 })
        .height(50)
        .width('90%')
        .swipeAction({ edgeEffect: SwipeEdgeEffect.None, end: this.endSwipeStyle() })
      })
    }
  })
}
.onReachEnd(() => console.info("列表已经到底啦~~~")) // 列表到达末尾时触发

② onScrollIndex

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

参数名类型必填说明
startnumber是List显示区域内第一个子组件的索引值
endnumber是List显示区域内最后一个子组件的索引值。
centernumber是List显示区域内中间位置子组件的索引值。

当有子组件划入或划出List显示区域时会触发该事件，部分示例代码如下：

List({ space: 10, initialIndex: 0 }) {
  ForEach(this.groupArr, (item: string, index: number) => {
    ListItemGroup({ header: this.ListItemGroupBuilder(item), space: 10 }) {
      ForEach(Array.from({ length: 18 }), (_: string, index: number) => {
        ListItem() {
          Text(`第 ${index + 1} 项`)
            .fontSize(18)
            .fontWeight(600)
            .width('100%')
            .textAlign(TextAlign.Center)
        }
        .border({ width: 1, color: 0x000000, radius: 10 })
        .height(50)
        .width('90%')
        .swipeAction({ edgeEffect: SwipeEdgeEffect.None, end: this.endSwipeStyle() })
      })
    }
  })
}
.onScrollIndex((start: number, end: number, center: number) => {
  console.info(`列表滑动时触发，start: ${start}, end: ${end}, center: ${center}`)
})

效果如图所示：

List-图片3.gif

（4）ListItem 的常用事件

swipeAction

swipeAction(value: SwipeActionOptions)

可以通过设置滑动（左滑或右滑）某个列表项，实现滑出组件的显示，比如这里给大家展示一下如何实现左滑删除的功能，示例代码如下：

// 列表向左滑动的样式
@Builder
endSwipeStyle() {
  Row() {
    Text("删除")
      .width('100%')
      .textAlign(TextAlign.Center)
      .fontColor(0xFFFFFF)
  }
  .width(50)
  .height('100%')
  .borderRadius(10)
  .backgroundColor(0xFF0000)
  .onClick(() => {
    this.getUIContext().showAlertDialog({
      message: "确定要删除嘛",
      buttons: [
        {
          value: "确定",
          action: () => {
            // 这里仅用于展示该方法如何使用，如果想真的删除该数据，可以通过数组方法自行尝试
            promptAction.openToast({ message: "已删除" })
          }
        },
        {
          value: "取消",
          action: () => {
          }
        }
      ]
    })
  })
}
 
ListItem() {
  Text(`第 ${index + 1} 项`)
    .fontSize(18)
    .fontWeight(600)
    .width('100%')
    .textAlign(TextAlign.Center)
}
.border({ width: 1, color: 0x000000, radius: 10 })
.height(50)
.width('90%')
.swipeAction({ edgeEffect: SwipeEdgeEffect.None, end: this.endSwipeStyle() })

实现效果如下：

List-图片4.gif

完整代码请从Gitee上下载完整项目：List 组件

avatar
文章
阅读
粉丝