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

鸿蒙应用开发从入门到实战（十七）：ArkUI组件List列表布局

news 2025/10/10 10:24:40

大家好，我是潘Sir，持续分享IT技术，帮你少走弯路。《鸿蒙应用开发从入门到项目实战》系列文章持续更新中，陆续更新AI+编程、企业级项目实战等原创内容、欢迎关注！

ArkUI提供了丰富的系统组件，用于制作鸿蒙原生应用APP的UI，本文通过简单案例演示如何使用List组件实现列表布局。

一、List布局优化商品列表

上一小节里的商品列表，随着数据增多，当超出界面后，无法滚动查看。List列表布局就可以解决这个问题。

List列表是一种复杂容器，具备下列特点：

列表项ListItem数量过多超出屏幕后，会自动提供滚动功能
列表项ListItem既可以纵向排列，也可以横向排列

再pages/layout下新建list目录，新建ProductList.ets文件，将上一小节里的代码文件ProductListPage.ets文件里的内容拷贝过来进行修改。

将ForEach部分的内容放到List组件里即可

class Item1 { // 复制过来后，即使再不同的文件中，也会提示同名name: string //小写image: ResourceStrprice: numberdiscount: numberconstructor(name: string, image: ResourceStr, price: number, discount: number = 0) {this.name = namethis.image = imagethis.price = pricethis.discount = discount}
}@Entry
@Component
struct ProductList {// 商品数据private items: Array<Item1> = [new Item1('华为Mate60', $r('app.media.mate60'), 6999, 500),new Item1('MateBookProX', $r('app.media.mate60'), 13999),new Item1('WatchGT4', $r('app.media.mate60'), 1438),new Item1('FreeBuds Pro3', $r('app.media.mate60'), 1499),new Item1('FreeBuds Pro3', $r('app.media.mate60'), 199),new Item1('Mate X5', $r('app.media.mate60'), 12999)]build() {Column({ space: 8 }) {// 标题Row() {Text('商品列表').fontSize(30).fontWeight(FontWeight.Bold)}.width('100%')// .height(30) //控制高度.margin({ bottom: 20 })// 商品列表List({ space: 8 }) {ForEach(this.items,(item: Item1) => {ListItem() {  //ListItem子元素必须用根元素包裹Row({ space: 10 }) {Image(item.image).width(100)Column({ space: 4 }) {if (item.discount) {Text(item.name).fontSize(20).fontWeight(FontWeight.Bold)Text('原价：￥' + item.price).fontColor('#CCC').fontSize(14).decoration({ type: TextDecorationType.LineThrough })Text('折扣价：￥' + (item.price - item.discount)).fontColor('#F36').fontSize(18)Text('补贴：￥' + item.discount).fontColor('#F36').fontSize(18)} else {Text(item.name).fontSize(20).fontWeight(FontWeight.Bold)Text('￥' + item.price).fontColor('#F36').fontSize(18)}}.height('100%').alignItems(HorizontalAlign.Start)}.width('100%').backgroundColor('#FFF').borderRadius(20).height(120).padding(10)}})}.width('100%')// .layoutWeight(1)}.width('100%').height('100%').backgroundColor('#EFEFEF').padding(20)}
}

这样，就可以通过拖动呈现超过屏幕区的内容。

二、列表布局详解

2.1 概述

List是一个功能强大的容器组件，使用List可以轻松高效地显示结构化、可滚动的列表信息，例如通讯录、新闻列表等等。

请添加图片描述

List容器的子组件为ListItem或者ListItemGroup，其中，ListItem表示单个列表项，ListItemGroup用于列表数据的分组展示，其子组件也是ListItem，具体用法如下

List() {// 列表项ListItem() {......}ListItem() {......}ListItem() {......}ListItem() {......}ListItem() {......}ListItem() {......}ListItem() {......}ListItem() {......}ListItem() {......}ListItem() {......}ListItem() {......}ListItem() {......}
}

效果
请添加图片描述

List() {// 列表组ListItemGroup(){//列表项ListItem(){......}ListItem(){......}}ListItemGroup(){ListItem(){......}ListItem(){......}}ListItemGroup(){ListItem(){......}ListItem(){......}}
}

效果
请添加图片描述

2.2 参数

List 组件的参数定义如下，下面逐一介绍每个参数

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

2.2.1 列表项间距

space参数用于设置列表项的间距，如下图所示

请添加图片描述

2.2.2 列表滚动控制器

scroller参数用于绑定列表滚动控制器（Scroller），Scroller可以控制列表的滚动，例如令列表返回顶部
请添加图片描述

示例：

拷贝icon-top.png到resources/base/media目录

pages /layout/list新建ScrollerPage.ets

@Entry
@Component
struct ScrollerPage {data: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]scroller: Scroller = new Scroller();build() {Stack({ alignContent: Alignment.BottomEnd }) {List({ space: 20, scroller: this.scroller }) {ForEach(this.data, (item) => {ListItem() {Text(item.toString()).itemTextStyle()}})}.listStyle().height('100%').width('100%')Button({ type: ButtonType.Circle }) {Image($r('app.media.icon_top')).width(40).height(40)}.width(60).height(60).backgroundColor(Color.Orange).offset({ x: -20, y: -100 }).onClick(() => {this.scroller.scrollToIndex(0)})}}
}@Extend(Text) function itemTextStyle() {.height(80).width('100%').textAlign(TextAlign.Center).fontColor(Color.White).fontSize(40).fontWeight(FontWeight.Bold).backgroundColor('#008a00').borderRadius(10)
}@Extend(List) function listStyle() {.backgroundColor(Color.White).padding(20)
}

2.3 常用属性

2.3.1 主轴方向

使用listDirection()方法可以设置列表的主轴方向（即列表的排列和滚动方向），其参数类型为枚举类型Axis，可选的枚举值如下
请添加图片描述

2.3.2 交叉轴对齐方式

使用alignListItem()方法可以设置子组件在交叉轴方向的对齐方式，其参数类型为枚举类型ListItemAlign，可选的枚举值有

请添加图片描述

示例代码

pages /layout/list新建AlignPage.ets

@Entry
@Component
struct AlignPage {data: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]build() {List({ space: 20 }) {ForEach(this.data, (item) => {ListItem() {Text(item.toString()).height(80).width(320).itemTextStyle1()}})}.listStyle1().height('100%').width('100%').alignListItem(ListItemAlign.Center)}
}@Extend(Text) function itemTextStyle1() {  //同一个命名空间下不能重复，否则会报错.textAlign(TextAlign.Center).fontColor(Color.White).fontSize(40).fontWeight(FontWeight.Bold).backgroundColor('#008a00').borderRadius(10)
}@Extend(List) function listStyle1() {.backgroundColor(Color.White).padding({ top: 20, bottom: 20 })
}

2.3.3 元素分割线

使用divider()属性可设置列表元素分割线样式，该方法的参数定义如下

divider(value: {strokeWidth: Length, color?: ResourceColor, startMargin?: Length, endMargin?: Length})

各参数的含义如下

参数	含义
`strokeWidth`	分割线线宽
`color`	分割线颜色
`startMargin`	分割线起始端到列表侧边距离（如下图所示）
`endMargin`	分割线末端到列表侧边距离（如下图所示）

请添加图片描述

示例代码

pages /layout/list新建DividerPage.ets

@Entry
@Component
struct DividerPage {data: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]build() {List({ space: 20 }) {ForEach(this.data, (item) => {ListItem() {Text(item.toString()).height(80).width(320).itemTextStyle2()}})}.listStyle2().height('100%').width('100%').alignListItem(ListItemAlign.Center).divider({strokeWidth: 1,color: Color.Orange,startMargin: 30,endMargin: 30})}
}@Extend(Text) function itemTextStyle2() {.textAlign(TextAlign.Center).fontColor(Color.White).fontSize(40).fontWeight(FontWeight.Bold).backgroundColor('#008a00').borderRadius(10)
}@Extend(List) function listStyle2() {.backgroundColor(Color.White).padding({ top: 20, bottom: 20 })
}

2.3.4 滚动条样式

使用scrollBar()方法可以设置滚动条状态，该方法的参数类型为枚举类型BarState，可选的枚举值如下

名称	描述
`BarState.Off`	不显示
`BarState.On`	常驻显示
`BarState.Auto`	按需显示(触摸时显示，2s后消失)

示例代码

pages /layout/list新建ScrollBarPage.ets

@Entry
@Component
struct ScrollBarPage {data: number[] = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]build() {List({ space: 20 }) {ForEach(this.data, (item) => {ListItem() {Text(item.toString()).height(80).width(320).itemTextStyle3()}})}.listStyle3().height('100%').width('100%').alignListItem(ListItemAlign.Center).scrollBar(BarState.Auto)}
}@Extend(Text) function itemTextStyle3() {.textAlign(TextAlign.Center).fontColor(Color.White).fontSize(40).fontWeight(FontWeight.Bold).backgroundColor('#008a00').borderRadius(10)
}@Extend(List) function listStyle3() {.backgroundColor(Color.White).padding({ top: 20, bottom: 20 })
}