当前位置：首页 > news >正文

鸿蒙界面开发（九）：列表布局 (List)

news 2025/6/28 0:43:11

列表布局

当列表项达到一定数量，内容超过屏幕大小时，可以自动提供滚动功能。它适合用于呈现同类数据类型或数据类型集，例如图片和文本。在列表中显示数据集合是许多应用程序中的常见要求（如通讯录、音乐列表、购物清单等）。

布局与约束

列表作为一种容器，会自动按其滚动方向排列子组件，向列表中添加组件或从列表中移除组件会重新排列子组件。
ListItemGroup用于列表数据的分组展示，其子组件也是ListItem。ListItem表示单个列表项，可以包含单个子组件。
说明： List的子组件必须是ListItemGroup或ListItem，ListItem和ListItemGroup必须配合List来使用。

Grid和WaterFlow也可以实现单列、多列布局，如果布局每列等宽，且不需要跨行跨列布局，相比Gird和WaterFlow，则更推荐使用List。

如果List组件主轴或交叉轴方向设置了尺寸，则其对应方向上的尺寸为设置值。
如果List组件主轴方向没有设置尺寸，当List子组件主轴方向总尺寸小于List的父组件尺寸时，List 主轴方向尺寸自动适应子组件的总尺寸。如果List的子组件主轴方向总尺寸超过List的父组件尺寸时，List主轴方向尺寸适应List的父组件尺寸。
List组件交叉轴方向在没有设置尺寸时，其尺寸默认自适应父组件尺寸。

开发布局

设置主轴方向

List() { // ...}
.listDirection(Axis.Horizontal)
listDirection属性设置为Axis.Horizontal，水平滚动。
listDirection默认为Axis.Vertical，即主轴默认是垂直方向。

设置交叉轴布局

List组件的交叉轴布局可以通过lanes和alignListItem属性进行设置，
lanes属性用于确定交叉轴排列的列表项数量，
alignListItem用于设置子组件在交叉轴方向的对齐方式。

lanes

List组件的lanes属性通常用于在不同尺寸的设备自适应构建不同行数或列数的列表，即一次开发、多端部署的场景，例如歌单列表。
lanes属性的取值类型是"number | LengthConstrain"，即整数或者LengthConstrain类型。
当其取值为LengthConstrain类型时，表示会根据LengthConstrain与List组件的尺寸自适应决定行或列数。

//取值为number
List() { // ...}
.lanes(2)
//取值为LengthConstrain类型
@Entry
@Component
struct EgLanes {@State egLanes: LengthConstrain = { minLength: 200, maxLength: 300 }build() {List() { // ...}.lanes(this.egLanes)}
}
当List组件宽度为300vp时，由于minLength为200vp，此时列表为一列。
当List组件宽度变化至400vp时，符合两倍的minLength，则此时列表自适应为两列。

alignListItem属性

默认值是ListItemAlign.Start，即列表项在列表交叉轴方向上默认按首部对齐。
ListItemAlign.Center表示列表项在水平方向上居中对齐。

List() { // ...}
.alignListItem(ListItemAlign.Center)

在列表中显示数据

ListItem中只能有一个根节点组件，若列表项是由多个组件元素组成的，则需要将这多个元素组合到一个容器组件内或组成一个自定义组件。

List() {ListItem() {Row() {Image($r('app.media.iconE')).width(40).height(40).margin(10)Text('小明').fontSize(20)}}}

迭代列表内容

通常，应用通过数据集合动态地创建列表。使用循环渲染可从数据源中迭代获取数据，并在每次迭代过程中创建相应的组件，降低代码复杂度。

ArkTS通过ForEach提供了组件的循环渲染能力。

import { util } from '@kit.ArkTS'class Contact {key: string = util.generateRandomUUID(true);name: string;icon: Resource;constructor(name: string, icon: Resource) {this.name = name;this.icon = icon;}
}@Entry
@Component
struct SimpleContacts {private contacts: Array<object> = [new Contact('小明', $r("app.media.iconA")),new Contact('小红', $r("app.media.iconB")),]build() {List() {ForEach(this.contacts, (item: Contact) => {ListItem() {Row() {Image(item.icon).width(40).height(40).margin(10)Text(item.name).fontSize(20)}.width('100%').justifyContent(FlexAlign.Start)}}, (item: Contact) => JSON.stringify(item))}.width('100%')}
}

自定义列表样式

设置内容间距——space参数

List({ space: 10 }) {// ...
}

添加分隔线——divider属性

divider属性用于给列表项之间添加分隔线。在设置divider属性时，可以通过strokeWidth和color属性设置分隔线的粗细和颜色。
startMargin和endMargin属性分别用于设置分隔线距离列表侧边起始端的距离和距离列表侧边结束端的距离。

class DividerTmp {strokeWidth: Length = 1startMargin: Length = 60endMargin: Length = 10color: ResourceColor = '#ffe9f0f0'constructor(strokeWidth: Length, startMargin: Length, endMargin: Length, color: ResourceColor) {this.strokeWidth = strokeWidththis.startMargin = startMarginthis.endMargin = endMarginthis.color = color}
}
@Entry
@Component
struct EgDivider {@State egDivider: DividerTmp = new DividerTmp(1, 60, 10, '#ffe9f0f0')build() {List() {// ... }.divider(this.egDivider)}
}

说明

分隔线的宽度会使ListItem之间存在一定间隔，当List设置的内容间距小于分隔线宽度时，ListItem之间的间隔会使用分隔线的宽度。当List存在多列时，分割线的startMargin和endMargin作用于每一列上。List组件的分隔线画在两个ListItem之间，第一个ListItem上方和最后一个ListItem下方不会绘制分隔线。

添加滚动条——scrollBar属性

在使用List组件时，可通过scrollBar属性控制列表滚动条的显示。scrollBar的取值类型为BarState，当取值为BarState.Auto表示按需显示滚动条。此时，当触摸到滚动条区域时显示控件，可上下拖拽滚动条快速浏览内容，拖拽时会变粗。若不进行任何操作，2秒后滚动条自动消失。

scrollBar属性API version 9及以下版本默认值为BarState.Off，从API version 10版本开始默认值为BarState.Auto。

List() { // ...}
.scrollBar(BarState.Auto)

支持分组列表——ListItemGroup

在List组件中使用ListItemGroup对项目进行分组，可以构建二维列表。
ListItemGroup的宽度默认充满List组件。在初始化ListItemGroup时，可通过header参数设置列表分组的头部组件。

@Entry
@Component
struct ContactsList {@Builder itemHead(text: string) {// 列表分组的头部组件，对应联系人分组A、B等位置的组件Text(text).fontSize(20).backgroundColor('#fff1f3f5').width('100%').padding(5)}build() {List() {ListItemGroup({ header: this.itemHead('A') }) {// 循环渲染分组A的ListItem}}}
}

添加粘性标题——sticky属性

粘性标题是一种常见的标题模式，常用于定位字母列表的头部元素。如在联系人列表中滚动A部分时，B部分开始的头部元素始终处于A的下方。而在开始滚动B部分时，B的头部会固定在屏幕顶部，直到所有B的项均完成滚动后，才被后面的头部替代。

List组件的sticky属性配合ListItemGroup组件使用，用于设置ListItemGroup中的头部组件是否呈现吸顶效果或者尾部组件是否呈现吸底效果。

设置sticky属性为StickyStyle.Header，即可实现列表的粘性标题效果。
如果需要支持吸底效果，可以通过footer参数初始化ListItemGroup的底部组件，并将sticky属性设置为StickyStyle.Footer。ListItemGroup({ header: this.itemHead(itemGroup.title) }) {// 循环渲染ListItem
}.sticky(StickyStyle.Header)  // 设置吸顶，实现粘性标题效果

控制滚动位置

用户滚动列表到一定位置时，希望快速滚动到列表底部或返回列表顶部。此时，可以通过控制滚动位置来实现列表的快速定位。
List组件初始化时，可以通过scroller参数绑定一个Scroller对象，就可以通过Scroller对象的scrollToIndex方法使列表滚动到指定的列表项索引位置。

首先，需要创建一个Scroller的对象listScroller。

private listScroller: Scroller = new Scroller();

然后，通过将listScroller用于初始化List组件的scroller参数，完成listScroller与列表的绑定。在需要跳转的位置指定scrollToIndex的参数为0，表示返回列表顶部。

Stack({ alignContent: Alignment.Bottom }) {// 将listScroller用于初始化List组件的scroller参数，完成listScroller与列表的绑定。List({ space: 20, scroller: this.listScroller }) {// ...}Button() {// ...}.onClick(() => {// 点击按钮时，指定跳转位置，返回列表顶部this.listScroller.scrollToIndex(0)})
}

响应滚动位置

监听列表的滚动位置变化并作出响应
在这里插入图片描述

当联系人列表从A滚动到B时，右侧索引栏也需要同步从选中A状态变成选中B状态。此场景可以通过监听List组件的onScrollIndex事件来实现，右侧索引栏需要使用字母表索引组件AlphabetIndexer。

在列表滚动时，根据列表此时所在的索引值位置firstIndex，重新计算字母索引栏对应字母的位置selectedIndex。由于AlphabetIndexer组件通过selected属性设置了选中项索引值，当selectedIndex变化时会触发AlphabetIndexer组件重新渲染，从而显示为选中对应字母的状态。

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'];
@Entry
@Component
struct ContactsList {@State selectedIndex: number = 0;private listScroller: Scroller = new Scroller();build() {Stack({ alignContent: Alignment.End }) {List({ scroller: this.listScroller }) {}.onScrollIndex((firstIndex: number) => {// 根据列表滚动到的索引值，重新计算对应联系人索引栏的位置this.selectedIndex})// 字母表索引组件AlphabetIndexer({ arrayValue: alphabets, selected: 0 }).selected(this.selectedIndex)}}
}