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

9.ArkUI List的介绍和使用

news 来源：原创 2025/4/27 8:38:13

ArkUI List 组件详解与使用指南

List 是 ArkUI（HarmonyOS 开发框架）中用于展示长列表数据的高性能滚动容器组件。以下是 List 的详细介绍和使用方法。

基本介绍

List 组件特点：

支持垂直/水平滚动
高性能渲染（仅渲染可视区域内的项）
支持多种布局方式
内置多种滑动操作和交互效果

基本使用

1. 简单列表

@Entry
@Component
struct SimpleListExample {private data: string[] = ['Apple', 'Banana', 'Orange', 'Pear', 'Grape']build() {Column() {List({ space: 10 }) {ForEach(this.data, (item: string) => {ListItem() {Text(item).fontSize(20).width('100%').textAlign(TextAlign.Center).backgroundColor('#f0f0f0').padding(10)}}, (item: string) => item)}.width('100%').height('100%')}}
}

2. 复杂列表项

@Entry
@Component
struct ComplexListExample {private contacts = [{ name: '张三', phone: '13800138000', avatar: 'user1.png' },{ name: '李四', phone: '13900139000', avatar: 'user2.png' },// 更多数据...]build() {List({ space: 5 }) {ForEach(this.contacts, (contact) => {ListItem() {Row() {Image(contact.avatar).width(50).height(50).borderRadius(25)Column() {Text(contact.name).fontSize(18).fontWeight(FontWeight.Bold)Text(contact.phone).fontSize(14).fontColor('#666')}.margin({ left: 10 })}.width('100%').padding(10)}}, contact => contact.phone)}.width('100%').height('100%')}
}

核心功能

1. 列表方向

List() {// 列表项
}
.layoutDirection(Axis.Vertical) // 垂直列表（默认）List() {// 列表项
}
.layoutDirection(Axis.Horizontal) // 水平列表

2. 列表分隔线

List() {// 列表项
}
.divider({strokeWidth: 1,color: '#f0f0f0',startMargin: 20,endMargin: 20
})

3. 列表滚动控制

@State scroller: Scroller = new Scroller()build() {List({ scroller: this.scroller }) {// 列表项}// 滚动到指定位置Button('滚动到底部').onClick(() => {this.scroller.scrollTo({ x: 0, y: 1000 })})
}

4. 下拉刷新和上拉加载

@State isRefreshing: boolean = false
@State isLoadingMore: boolean = falsebuild() {List() {// 列表项}.onScrollIndex((start, end) => {// 滚动到接近底部时触发加载更多if (end >= this.data.length - 5) {this.loadMore()}}).refresh({refreshing: this.isRefreshing,onRefresh: () => {this.refreshData()}})
}private refreshData() {this.isRefreshing = true// 模拟异步请求setTimeout(() => {this.isRefreshing = false}, 1000)
}private loadMore() {if (this.isLoadingMore) returnthis.isLoadingMore = true// 模拟异步加载setTimeout(() => {// 添加新数据this.isLoadingMore = false}, 1000)
}

性能优化

1. 复用标识

ForEach(this.data, (item) => {ListItem() {// 内容}
}, (item) => item.id) // 提供唯一键提高复用效率

2. 懒加载

ListItem() {LazyForEach(this.dataSource, (item) => {// 列表项内容}, (item) => item.id)
}

3. 固定高度

ListItem() {// 内容
}
.height(80) // 指定固定高度提高性能

高级功能

1. 分组列表

@Entry
@Component
struct SectionListExample {private sections = [{title: 'A',data: ['Apple', 'Apricot', 'Avocado']},{title: 'B',data: ['Banana', 'Blackberry', 'Blueberry']}// 更多分组...]build() {List() {ForEach(this.sections, (section) => {ListItemGroup({ header: this.renderHeader(section.title) }) {ForEach(section.data, (item) => {ListItem() {Text(item).padding(10)}})}})}}@Builder renderHeader(title: string) {Text(title).fontSize(18).fontWeight(FontWeight.Bold).backgroundColor('#f0f0f0').width('100%').padding(10)}
}

2. 滑动操作

ListItem() {// 主内容
}
.swipeAction({ end: this.DeleteButton(),start: this.MarkButton() 
})@Builder DeleteButton() {Button('删除').width(80).height('100%').backgroundColor(Color.Red).onClick(() => {// 删除操作})
}@Builder MarkButton() {Button('标记').width(80).height('100%').backgroundColor(Color.Green).onClick(() => {// 标记操作})
}