HarmonyOS ArkUI List组件完全使用指南从入门到实战导语List是HarmonyOS ArkUI中最常用的列表容器组件它提供了高效的列表渲染能力、丰富的配置选项和灵活的事件系统。本文将从基础概念到高级用法带你全面掌握List组件的使用方法并通过一个完整示例帮助你快速上手。效果一、List组件概述1.1 什么是ListList是ArkUI中的列表容器组件用于在垂直或水平方向上展示一系列子组件。与Scroll嵌套Column的方式不同List具备以下优势懒加载能力配合LazyForEach可实现按需加载大幅提升长列表性能内置滚动管理自带滚动能力管理无需手动处理滚动逻辑丰富的交互支持分割线、滚动条、对齐方式等配置分组能力配合ListItemGroup可实现分组列表1.2 List的基本结构List(){ListItem(){// 列表项内容}ListItem(){// 列表项内容}}List中只能包含ListItem和ListItemGroup两种子组件不能直接放置其他组件。二、List核心属性详解2.1 列表方向listDirection控制列表的滚动方向默认值为Axis.Vertical。List(){// ...}.listDirection(Axis.Horizontal)// 水平滚动列表值说明Axis.Vertical垂直方向默认上下滚动Axis.Horizontal水平方向左右滚动2.2 分割线divider为列表项之间添加分割线支持样式、颜色、边距配置。List(){// ...}.divider({strokeWidth:1,// 分割线宽度color:#E5E5E5,// 分割线颜色startMargin:16,// 起始边距endMargin:16// 结束边距})2.3 滚动条控制scrollBar控制滚动条的显示状态。List(){// ...}.scrollBar(BarState.Auto)// 自动显示/隐藏.scrollBar(BarState.Off)// 隐藏滚动条.scrollBar(BarState.On)// 始终显示2.4 列表项对齐方式alignListItem控制列表项在交叉轴方向上的对齐方式。List(){// ...}.alignListItem(ListItemAlign.Center)// 居中对齐.alignListItem(ListItemAlign.Start)// 起始对齐.alignListItem(ListItemAlign.End)// 末尾对齐2.5 缓存数量cachedCount设置列表在可视区域外缓存的列表项数量影响滚动流畅度。List(){// ...}.cachedCount(5)// 缓存5个屏幕外的列表项2.6 滚动事件onScroll监听列表滚动事件获取滚动偏移量和距离。List(){// ...}.onScroll((xOffset:number,yOffset:number){console.log(滚动偏移: x${xOffset}, y${yOffset})})2.7 滚动到底部/顶部事件.onReachStart((){// 滚动到顶部时触发可用于下拉刷新}).onReachEnd((){// 滚动到底部时触发可用于上拉加载更多})三、List数据驱动ForEach与LazyForEach3.1 ForEach静态渲染适用于数据量较小且不会动态变化的列表。Stateitems:string[][苹果,香蕉,橙子,葡萄]build(){List(){ForEach(this.items,(item:string){ListItem(){Text(item).fontSize(16).padding(12)}})}}3.2 LazyForEach动态懒加载适用于数据量较大的列表按需创建组件显著提升性能。classMyDataSourceimplementsIDataSource{privatedata:string[][]privatelisteners:DataChangeListener[][]constructor(data:string[]){this.datadata}totalCount():number{returnthis.data.length}getData(index:number):string{returnthis.data[index]}registerDataChangeListener(listener:DataChangeListener):void{this.listeners.push(listener)}unregisterDataChangeListener(listener:DataChangeListener):void{constidxthis.listeners.indexOf(listener)if(idx0){this.listeners.splice(idx,1)}}}// 使用StatedataSource:MyDataSourcenewMyDataSource([项目1,项目2,项目3])build(){List(){LazyForEach(this.dataSource,(item:string){ListItem(){Text(item).fontSize(16).padding(12)}})}}四、Scroller滚动控制器通过Scroller对象可以程序化地控制滚动行为。需要注意的是Scroller主要用于Scroll容器而List组件通过事件和属性来管理滚动。// 在Scroll容器中使用Scrollerprivatescroller:ScrollernewScroller()build(){Scroll(this.scroller){Column(){// 内容...}}}// 滚动到指定位置scrollToTop(){this.scroller.scrollTo({xOffset:0,yOffset:0})}注意List组件本身不支持.scroller()属性如需程序化控制List滚动应使用Scroll组件包裹或结合LazyForEach的DataSourceAPI实现。五、完整示例个人收藏夹列表下面通过一个「个人收藏夹」示例展示List组件的综合使用方法。5.1 功能说明垂直滚动列表展示收藏内容每个列表项包含图标、标题和描述支持列表项点击事件滚动到底部时显示加载更多提示使用分割线美化界面5.2 完整代码// 收藏项数据模型interfaceFavoriteItem{id:numbertitle:stringdescription:stringicon:Resource isRead:boolean}EntryComponentstruct FavoriteListPage{StatefavoriteList:FavoriteItem[][{id:1,title:ArkUI布局指南,description:学习Flex、Column、Row等布局,icon:$r(app.media.ic_book),isRead:false},{id:2,title:状态管理最佳实践,description:State、Prop、Link详解,icon:$r(app.media.ic_star),isRead:true},{id:3,title:动画效果实现,description:animateTo与属性动画,icon:$r(app.media.ic_animation),isRead:false},{id:4,title:网络请求封装,description:HTTP模块使用指南,icon:$r(app.media.ic_network),isRead:false},{id:5,title:数据库操作,description:关系型数据库RDB使用,icon:$r(app.media.ic_database),isRead:true},]StateisLoading:booleanfalsebuild(){Column(){// 页面标题Text(我的收藏).fontSize(24).fontWeight(FontWeight.Bold).width(100%).padding({left:20,top:16,bottom:8})// 列表主体List(){ForEach(this.favoriteList,(item:FavoriteItem){ListItem(){Row({space:12}){// 图标Image(item.icon).width(40).height(40).borderRadius(8).backgroundColor(#F0F0F0).padding(8)// 文本内容Column({space:4}){Text(item.title).fontSize(16).fontWeight(FontWeight.Medium).fontColor(item.isRead?#999999:#333333)Text(item.description).fontSize(13).fontColor(#999999).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis})}.layoutWeight(1).alignItems(HorizontalAlign.Start)// 未读标记if(!item.isRead){Circle().width(8).height(8).fill(#FF4444)}}.width(100%).padding({left:16,right:16,top:12,bottom:12}).onClick((){// 标记为已读item.isReadtrue})}},(item:FavoriteItem)item.id.toString())}.width(100%).layoutWeight(1).divider({strokeWidth:0.5,color:#F0F0F0,startMargin:68,endMargin:16}).scrollBar(BarState.Off).alignListItem(ListItemAlign.Center).onReachEnd((){this.loadMore()}).onScroll((){// 可在此处监听滚动做更多操作})// 加载更多提示if(this.isLoading){Text(加载中...).fontSize(14).fontColor(#999999).padding(16)}}.width(100%).height(100%).backgroundColor(#FFFFFF)}// 模拟加载更多loadMore(){this.isLoadingtruesetTimeout((){constnewItems:FavoriteItem[][{id:Date.now(),title:新增收藏项,description:这是新加载的内容,icon:$r(app.media.ic_book),isRead:false}]this.favoriteList[...this.favoriteList,...newItems]this.isLoadingfalse},1000)}}5.3 代码要点解析要点说明ForEach keyGenerator第三个参数为唯一键生成器提升diff效率divider通过startMargin避开图标区域分割线更美观scrollBar(BarState.Off)隐藏滚动条界面更简洁onReachEnd滚动到底部触发加载更多layoutWeight(1)文本区域自适应填充剩余空间六、List使用注意事项6.1 性能优化建议大数据量务必使用LazyForEach避免一次性创建所有列表项组件设置合理的cachedCount默认值为1数据项复杂时可适当增大ForEach必须提供唯一key帮助框架精准diff减少不必要的重建6.2 常见误区List不支持.scroller()属性这是一个很常见的错误List组件没有scroller属性程序化滚动控制应使用Scroll容器List内不能直接放非ListItem组件所有子组件必须包裹在ListItem或ListItemGroup中List不支持嵌套滚动同方向垂直List嵌套垂直List会导致滚动冲突避免在build()中做耗时操作build函数应保持纯净数据准备放在aboutToAppear中6.3 List与其他容器对比特性ListScrollColumnLazyForEach懒加载原生支持不支持支持分割线内置支持需手动实现需手动实现分组ListItemGroup手动分组配合List使用性能大数据优差优七、总结List组件是ArkUI列表展示的核心容器掌握以下要点即可应对大部分开发场景基础列表用ListListItemForEach大数据列表用ListListItemLazyForEach分组列表用ListListItemGroupListItem通过divider、scrollBar、alignListItem等属性美化界面通过onReachEnd、onScroll等事件实现交互逻辑下一篇文章我们将深入讲解ListItemGroup的使用方法实现更复杂的分组列表效果。关键词HarmonyOS、ArkUI、List组件、列表容器、LazyForEach、ArkTS、鸿蒙开发
《宝宝成长记录时间轴》一、List组件使用指南
HarmonyOS ArkUI List组件完全使用指南从入门到实战导语List是HarmonyOS ArkUI中最常用的列表容器组件它提供了高效的列表渲染能力、丰富的配置选项和灵活的事件系统。本文将从基础概念到高级用法带你全面掌握List组件的使用方法并通过一个完整示例帮助你快速上手。效果一、List组件概述1.1 什么是ListList是ArkUI中的列表容器组件用于在垂直或水平方向上展示一系列子组件。与Scroll嵌套Column的方式不同List具备以下优势懒加载能力配合LazyForEach可实现按需加载大幅提升长列表性能内置滚动管理自带滚动能力管理无需手动处理滚动逻辑丰富的交互支持分割线、滚动条、对齐方式等配置分组能力配合ListItemGroup可实现分组列表1.2 List的基本结构List(){ListItem(){// 列表项内容}ListItem(){// 列表项内容}}List中只能包含ListItem和ListItemGroup两种子组件不能直接放置其他组件。二、List核心属性详解2.1 列表方向listDirection控制列表的滚动方向默认值为Axis.Vertical。List(){// ...}.listDirection(Axis.Horizontal)// 水平滚动列表值说明Axis.Vertical垂直方向默认上下滚动Axis.Horizontal水平方向左右滚动2.2 分割线divider为列表项之间添加分割线支持样式、颜色、边距配置。List(){// ...}.divider({strokeWidth:1,// 分割线宽度color:#E5E5E5,// 分割线颜色startMargin:16,// 起始边距endMargin:16// 结束边距})2.3 滚动条控制scrollBar控制滚动条的显示状态。List(){// ...}.scrollBar(BarState.Auto)// 自动显示/隐藏.scrollBar(BarState.Off)// 隐藏滚动条.scrollBar(BarState.On)// 始终显示2.4 列表项对齐方式alignListItem控制列表项在交叉轴方向上的对齐方式。List(){// ...}.alignListItem(ListItemAlign.Center)// 居中对齐.alignListItem(ListItemAlign.Start)// 起始对齐.alignListItem(ListItemAlign.End)// 末尾对齐2.5 缓存数量cachedCount设置列表在可视区域外缓存的列表项数量影响滚动流畅度。List(){// ...}.cachedCount(5)// 缓存5个屏幕外的列表项2.6 滚动事件onScroll监听列表滚动事件获取滚动偏移量和距离。List(){// ...}.onScroll((xOffset:number,yOffset:number){console.log(滚动偏移: x${xOffset}, y${yOffset})})2.7 滚动到底部/顶部事件.onReachStart((){// 滚动到顶部时触发可用于下拉刷新}).onReachEnd((){// 滚动到底部时触发可用于上拉加载更多})三、List数据驱动ForEach与LazyForEach3.1 ForEach静态渲染适用于数据量较小且不会动态变化的列表。Stateitems:string[][苹果,香蕉,橙子,葡萄]build(){List(){ForEach(this.items,(item:string){ListItem(){Text(item).fontSize(16).padding(12)}})}}3.2 LazyForEach动态懒加载适用于数据量较大的列表按需创建组件显著提升性能。classMyDataSourceimplementsIDataSource{privatedata:string[][]privatelisteners:DataChangeListener[][]constructor(data:string[]){this.datadata}totalCount():number{returnthis.data.length}getData(index:number):string{returnthis.data[index]}registerDataChangeListener(listener:DataChangeListener):void{this.listeners.push(listener)}unregisterDataChangeListener(listener:DataChangeListener):void{constidxthis.listeners.indexOf(listener)if(idx0){this.listeners.splice(idx,1)}}}// 使用StatedataSource:MyDataSourcenewMyDataSource([项目1,项目2,项目3])build(){List(){LazyForEach(this.dataSource,(item:string){ListItem(){Text(item).fontSize(16).padding(12)}})}}四、Scroller滚动控制器通过Scroller对象可以程序化地控制滚动行为。需要注意的是Scroller主要用于Scroll容器而List组件通过事件和属性来管理滚动。// 在Scroll容器中使用Scrollerprivatescroller:ScrollernewScroller()build(){Scroll(this.scroller){Column(){// 内容...}}}// 滚动到指定位置scrollToTop(){this.scroller.scrollTo({xOffset:0,yOffset:0})}注意List组件本身不支持.scroller()属性如需程序化控制List滚动应使用Scroll组件包裹或结合LazyForEach的DataSourceAPI实现。五、完整示例个人收藏夹列表下面通过一个「个人收藏夹」示例展示List组件的综合使用方法。5.1 功能说明垂直滚动列表展示收藏内容每个列表项包含图标、标题和描述支持列表项点击事件滚动到底部时显示加载更多提示使用分割线美化界面5.2 完整代码// 收藏项数据模型interfaceFavoriteItem{id:numbertitle:stringdescription:stringicon:Resource isRead:boolean}EntryComponentstruct FavoriteListPage{StatefavoriteList:FavoriteItem[][{id:1,title:ArkUI布局指南,description:学习Flex、Column、Row等布局,icon:$r(app.media.ic_book),isRead:false},{id:2,title:状态管理最佳实践,description:State、Prop、Link详解,icon:$r(app.media.ic_star),isRead:true},{id:3,title:动画效果实现,description:animateTo与属性动画,icon:$r(app.media.ic_animation),isRead:false},{id:4,title:网络请求封装,description:HTTP模块使用指南,icon:$r(app.media.ic_network),isRead:false},{id:5,title:数据库操作,description:关系型数据库RDB使用,icon:$r(app.media.ic_database),isRead:true},]StateisLoading:booleanfalsebuild(){Column(){// 页面标题Text(我的收藏).fontSize(24).fontWeight(FontWeight.Bold).width(100%).padding({left:20,top:16,bottom:8})// 列表主体List(){ForEach(this.favoriteList,(item:FavoriteItem){ListItem(){Row({space:12}){// 图标Image(item.icon).width(40).height(40).borderRadius(8).backgroundColor(#F0F0F0).padding(8)// 文本内容Column({space:4}){Text(item.title).fontSize(16).fontWeight(FontWeight.Medium).fontColor(item.isRead?#999999:#333333)Text(item.description).fontSize(13).fontColor(#999999).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis})}.layoutWeight(1).alignItems(HorizontalAlign.Start)// 未读标记if(!item.isRead){Circle().width(8).height(8).fill(#FF4444)}}.width(100%).padding({left:16,right:16,top:12,bottom:12}).onClick((){// 标记为已读item.isReadtrue})}},(item:FavoriteItem)item.id.toString())}.width(100%).layoutWeight(1).divider({strokeWidth:0.5,color:#F0F0F0,startMargin:68,endMargin:16}).scrollBar(BarState.Off).alignListItem(ListItemAlign.Center).onReachEnd((){this.loadMore()}).onScroll((){// 可在此处监听滚动做更多操作})// 加载更多提示if(this.isLoading){Text(加载中...).fontSize(14).fontColor(#999999).padding(16)}}.width(100%).height(100%).backgroundColor(#FFFFFF)}// 模拟加载更多loadMore(){this.isLoadingtruesetTimeout((){constnewItems:FavoriteItem[][{id:Date.now(),title:新增收藏项,description:这是新加载的内容,icon:$r(app.media.ic_book),isRead:false}]this.favoriteList[...this.favoriteList,...newItems]this.isLoadingfalse},1000)}}5.3 代码要点解析要点说明ForEach keyGenerator第三个参数为唯一键生成器提升diff效率divider通过startMargin避开图标区域分割线更美观scrollBar(BarState.Off)隐藏滚动条界面更简洁onReachEnd滚动到底部触发加载更多layoutWeight(1)文本区域自适应填充剩余空间六、List使用注意事项6.1 性能优化建议大数据量务必使用LazyForEach避免一次性创建所有列表项组件设置合理的cachedCount默认值为1数据项复杂时可适当增大ForEach必须提供唯一key帮助框架精准diff减少不必要的重建6.2 常见误区List不支持.scroller()属性这是一个很常见的错误List组件没有scroller属性程序化滚动控制应使用Scroll容器List内不能直接放非ListItem组件所有子组件必须包裹在ListItem或ListItemGroup中List不支持嵌套滚动同方向垂直List嵌套垂直List会导致滚动冲突避免在build()中做耗时操作build函数应保持纯净数据准备放在aboutToAppear中6.3 List与其他容器对比特性ListScrollColumnLazyForEach懒加载原生支持不支持支持分割线内置支持需手动实现需手动实现分组ListItemGroup手动分组配合List使用性能大数据优差优七、总结List组件是ArkUI列表展示的核心容器掌握以下要点即可应对大部分开发场景基础列表用ListListItemForEach大数据列表用ListListItemLazyForEach分组列表用ListListItemGroupListItem通过divider、scrollBar、alignListItem等属性美化界面通过onReachEnd、onScroll等事件实现交互逻辑下一篇文章我们将深入讲解ListItemGroup的使用方法实现更复杂的分组列表效果。关键词HarmonyOS、ArkUI、List组件、列表容器、LazyForEach、ArkTS、鸿蒙开发
