文章目录
一、List组件简介
在我们常用的手机应用中，经常会见到一些数据列表，如设置页面、通讯录、商品列表等。下图中两个页面都包含列表，“首页”页面中包含两个网格布局，“商城”页面中包含一个商品列表。
列表中都包含一系列相同宽度的列表项，连续、多行呈现同类数据，例如图片和文本。常见的列表有线性列表（List列表）和网格布局（Grid列表）。
为了帮助开发者构建包含列表的应用，ArkUI提供了List组件和Grid组件，开发者使用List和Grid组件能够很轻松的完成一些列表页面。
List是很常用的滚动类容器组件，一般和子组件ListItem一起使用，List列表中的每一个列表项对应一个ListItem组件。
1、List组件
列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。
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 | 否 | 可滚动组件的控制器。用于与可滚动组件进行绑定。 说明： 不允许和其他滚动类组件绑定同一个滚动控制对象。 |
2、ListItem组件
用来展示列表具体item，必须配合List来使用。
ListItem(value?: string)
参数：
| 参数名 | 参数类型 | 参数描述 |
|---|---|---|
| selectable | boolean | 当前ListItem元素是否可以被鼠标框选。 说明： 外层List容器的鼠标框选开启时，ListItem的框选才生效。 默认值：true |
| swipeAction | { 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语句。 |
3、ListItemGroup组件
该组件用来展示列表item分组，宽度默认充满List组件，必须配合List组件来使用。
当ListItemGroup的父组件List的listDirection属性为Axis.Vertical时，不允许设置ListItemGroup组件的height属性。
ListItemGroup的高度为header高度、footer高度和所有ListItem布局后总高度之和。当父组件List的listDirection属性为Axis.Horizontal时，不允许设置ListItemGroup组件的width属性。ListItemGroup的宽度为header宽度、footer宽度和所有ListItem布局后总宽度之和。
当前ListItemGroup内部的ListItem组件不支持编辑、框选、拖拽功能，即ListItem组件的editable、selectable属性不生效。
ListItemGroup(options?: {header?: CustomBuilder, footer?: CustomBuilder, space?: number | string})
参数：
| 参数名 | 参数类型 | 必填 | 参数描述 |
|---|---|---|---|
| header | CustomBuilder | 否 | 设置ListItemGroup头部组件。 |
| footer | CustomBuilder | 否 | 设置ListItemGroup尾部组件。 |
| space | number、string | 否 | 列表项间距。只作用于ListItem与ListItem之间，不作用于header与ListItem、footer与ListItem之间。 |
说明：
ListItemGroup组件不支持设置通用属性aspectRatio。
ListItemGroup组件如果主轴方向是垂直方向时，设置通用属性height属性不生效。
ListItemGroup组件如果主轴方向是水平方向时，设置通用属性width属性不生效。
二、使用ForEach渲染列表
列表往往由多个列表项组成，所以我们需要在List组件中使用多个ListItem组件来构建列表，这就会导致代码的冗余。使用循环渲染（ForEach）遍历数组的方式构建列表，可以减少重复代码。
ForEach接口基于数组类型数据来进行循环渲染，需要与容器组件配合使用，且接口返回的组件应当是允许包含在ForEach父容器组件中的子组件。例如，ListItem组件要求ForEach的父容器组件必须为List组件。
ForEach(
arr: Array,
itemGenerator: (item: Array, index?: number) => void,
keyGenerator?: (item: Array, index?: number): string => string
)
三、设置列表分割线
List组件子组件ListItem之间默认是没有分割线的，部分场景子组件ListItem间需要设置分割线，这时候您可以使用List组件的divider属性。divider属性包含四个参数：
- strokeWidth: 分割线的线宽。
- color: 分割线的颜色。
- startMargin：分割线距离列表侧边起始端的距离。
- endMargin: 分割线距离列表侧边结束端的距离。
endMargin +startMargin 不能超过列宽度。
startMargin和endMargin不支持设置百分比。
List的分割线画在主轴方向两个子组件之间，第一个子组件上方和最后一个子组件下方不会绘制分割线。
多列模式下，ListItem与ListItem之间的分割线起始边距从每一列的交叉轴方向起始边开始计算，其他情况从List交叉轴方向起始边开始计算。
四、设置List排列方向
List组件里面的列表项默认是按垂直方向排列的，如果您想让列表沿水平方向排列，您可以将List组件的listDirection属性设置为Axis.Horizontal。
listDirection参数类型是Axis，定义了以下两种类型：
- Vertical（默认值）：子组件ListItem在List容器组件中呈纵向排列。
- Horizontal：子组件ListItem在List容器组件中呈横向排列。
五、索引值计算规则
List的子组件的索引值计算规则：
- 按子组件的顺序依次递增。
- if/else语句中，只有条件成立的分支内的子组件会参与索引值计算，条件不成立的分支内子组件不计算索引值。
- ForEach/LazyForEach语句中，会计算展开所有子节点索引值。
- if/else/ForEach/LazyForEach发生变化以后，会更新子节点索引值。
- ListItemGroup作为一个整体计算一个索引值，ListItemGroup内部的ListItem不计算索引值。
- List子组件的visibility属性设置为Hidden或None依然会计算索引值。
- List子组件的visibility属性设置为None时不显示，但该子组件上下的space还会生效。
六、示例演示
List组件结合AlphabetIndexer实现汽车之家选车页面布局
1、AlphabetIndexer组件
可以与容器组件联动用于按逻辑结构快速定位容器显示区域的组件。
AlphabetIndexer(value: {arrayValue: Array<string>, selected: number})
参数：
| 参数名 | 参数类型 | 必填 | 参数描述 |
|---|---|---|---|
| arrayValue | Array | 是 | 字母索引字符串数组，不可设置为空。 |
| selected | number | 是 | 初始选中项索引值，若超出索引值范围，则取默认值0。 |
2、代码
const alphabets = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K',
'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z'];
interface CarItemInterface {
title: string
}
interface CarInterface {
alphabet: string,
carItem: CarItemInterface[]
}
@Entry
@Component
struct CarListIndex {
@State selectedIndex: number = 0
private listScroller: Scroller = new Scroller()
@State carList: CarInterface[] = [{
alphabet: "A",
carItem: [
{
title: "奥迪"
},
{
title: "奥拓"
},
{
title: "爱驰"
},
{
title: "ATS"
},
{
title: "AIM"
},
{
title: "阿尔特"
},
]
},
{
alphabet: "B",
carItem: [
{
title: "奔驰"
},
{
title: "比亚迪"
},
{
title: "宝马"
},
{
title: "保时捷"
},
{
title: "北京"
},
{
title: "标致"
},
]
},
{
alphabet: "C",
carItem: [
{
title: "长安"
},
{
title: "长城"
},
{
title: "曹操汽车"
},
{
title: "成功汽车"
},
{
title: "北京"
},
{
title: "标致"
},
]
},
{
alphabet: "D",
carItem: [
{
title: "大众"
},
{
title: "东风"
},
{
title: "Ds"
},
{
title: "大运"
},
{
title: "东南"
},
{
title: "大帝"
},
]
},
{
alphabet: "E",
carItem: [
{
title: "e.GO"
},
{
title: "Elek"
},
]
},
{
alphabet: "F",
carItem: [
{
title: "丰田"
},
{
title: "福特"
},
{
title: "福田"
},
{
title: "法拉利"
},
{
title: "福地"
},
{
title: "菲亚特"
},
]
}
]
//自定义组件内自定义构建函数
@Builder itemHead(text: string) {
Text(text)
.fontSize(20)
.backgroundColor(0xEEEEEE)
.width("100%")
.padding(10)
}
build() {
Column() {
Stack({ alignContent: Alignment.End }) {
Column() {
List({ scroller: this.listScroller }) {
ForEach(this.carList, (item: CarInterface) => {
ListItemGroup({ header: this.itemHead(item.alphabet) }) {
ForEach(item.carItem, (pro: CarItemInterface) => {
ListItem() {
Text(pro.title)
.fontSize(16)
.padding(10)
.width("100%")
}
})
}
})
}
.onScrollIndex((index: number) => {
this.selectedIndex = index
})
.sticky(StickyStyle.Header)
}.height('100%')
.width('100%')
AlphabetIndexer({ arrayValue: alphabets, selected: 0 })
.selected(this.selectedIndex)
.onSelect((index) => {
this.listScroller.scrollToIndex(index)
})
}
}
.width('100%')
.height('100%')
}
}
3、效果
