《级联年度选择》一、List使用指南-北京尧图网络

HarmonyOS ArkTS List 列表组件使用指南本文基于 HarmonyOS NEXT 开发环境详细讲解 ArkTS 中 List 列表容器组件的核心概念、常用 API 及实战用法。通过一个完整的简约示例帮助你从零掌握 List 组件的开发流程。效果一、List 组件概述1.1 什么是 ListList是 ArkUI 框架提供的列表容器组件用于包含一系列相同宽度的列表项ListItem。它天然支持滚动适合连续、多行呈现同类数据例如联系人列表、消息列表、商品清单等。核心特性特性说明自动滚动子项高度超出容器时自动出现滚动效果子组件限制仅支持ListItem、ListItemGroup及自定义组件布局方向默认垂直排列可通过listDirection设为水平数据驱动配合ForEach/LazyForEach实现动态渲染1.2 基本结构List(){ListItem(){Text(列表项 1)}ListItem(){Text(列表项 2)}ListItem(){Text(列表项 3)}}注意每个ListItem内部只能有一个根节点组件。如果需要多个组件组合必须将它们包裹在Row、Column、Flex等容器组件内。二、核心 API 详解2.1 构造参数参数类型说明spacenumber | string | Resource列表项之间的间距initialIndexnumber初始显示的列表项索引scrollerScroller可滚动组件的控制器用于程序化控制滚动2.2 常用属性属性说明.listDirection(direction)排列方向Axis.Vertical默认或Axis.Horizontal.scrollBar(state)滚动条状态BarState.On/BarState.Off/BarState.Auto.alignListItem(align)列表项对齐方式ListItemAlign.Start/Center/End.cachedCount(count)列表项缓存数量优化长列表滚动性能.layoutWeight(weight)在父容器中按权重分配剩余空间.divider(divider)列表项之间的分割线样式.edgeEffect(effect)滑动到边缘时的效果EdgeEffect.Spring/None2.3 常用事件事件说明.onAppear()列表项首次出现时触发.onDisAppear()列表项消失时触发.onScrollIndex(index)滑动到指定索引时触发.onReachStart()滑动到列表顶部时触发.onReachEnd()滑动到底部时触发三、动态渲染ForEach 与 LazyForEach3.1 ForEach 循环渲染ForEach是声明式循环渲染函数它遍历数据源并为每一项创建对应的ListItem。当数据源与State联动时数据变化会自动触发 UI 刷新。Stateitems:string[][苹果,香蕉,橙子]List(){ForEach(this.items,(item:string){ListItem(){Text(item).fontSize(16)}})}ForEach 三个参数说明参数说明arr数据源数组itemGenerator列表项生成函数(item, index) voidkeyGenerator唯一键生成函数(item, index) string可选但推荐最佳实践始终提供keyGenerator它可以帮助框架精确识别数据变化避免不必要的组件重建提升性能。3.2 LazyForEach 懒加载当列表数据量很大时使用LazyForEach配合IDataSource接口实现按需加载只渲染可见区域的列表项大幅提升性能。List(){LazyForEach(this.dataSource,(item:DataItem){ListItem(){Text(item.title)}},(item:DataItem)item.id.toString())}.cachedCount(5)// 缓存屏幕外 5 个列表项四、分组列表ListItemGroupListItemGroup用于将列表项分组显示配合sticky属性可实现分组标题吸顶效果。List(){ListItemGroup({header:this.groupHeader(水果)}){ForEach(this.fruits,(item:string){ListItem(){Text(item)}})}ListItemGroup({header:this.groupHeader(蔬菜)}){ForEach(this.vegetables,(item:string){ListItem(){Text(item)}})}}.sticky(StickyStyle.Header)BuildergroupHeader(title:string){Text(title).fontSize(16).fontWeight(FontWeight.Bold).backgroundColor(#F5F5F5).width(100%).padding(12)}五、完整实战示例课程清单下面通过一个完整的示例演示如何使用 List 组件构建一个课程清单页面。5.1 效果说明顶部显示标题栏中间使用 List 展示课程列表每项包含课程名称、讲师和时长支持滚动、分割线显示列表项带有选中高亮效果5.2 完整代码// 数据模型classCourseItem{id:numbername:stringteacher:stringduration:stringconstructor(id:number,name:string,teacher:string,duration:string){this.ididthis.namenamethis.teacherteacherthis.durationduration}}EntryComponentstruct CourseListPage{StateselectedIndex:number-1StatecourseList:CourseItem[][newCourseItem(0,HarmonyOS 应用开发入门,张老师,45分钟),newCourseItem(1,ArkTS 语言基础,李老师,60分钟),newCourseItem(2,ArkUI 组件详解,王老师,50分钟),newCourseItem(3,状态管理进阶,赵老师,55分钟),newCourseItem(4,路由与导航,孙老师,40分钟),newCourseItem(5,网络请求与数据持久化,周老师,65分钟),newCourseItem(6,性能优化实战,吴老师,70分钟),]build(){Column(){// 标题栏Text(课程清单).fontSize(22).fontWeight(FontWeight.Bold).width(100%).padding({left:16,top:16,bottom:12})// 列表区域List({space:0}){ForEach(this.courseList,(item:CourseItem,index:number){ListItem(){Row(){// 序号圆圈Text(${index1}).fontSize(14).fontColor(Color.White).width(28).height(28).borderRadius(14).backgroundColor(#4FC3F7).textAlign(TextAlign.Center)// 课程信息Column(){Text(item.name).fontSize(16).fontWeight(FontWeight.Medium).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis})Row({space:12}){Text(讲师${item.teacher}).fontSize(13).fontColor(#888888)Text(时长${item.duration}).fontSize(13).fontColor(#888888)}.margin({top:4})}.layoutWeight(1).alignItems(HorizontalAlign.Start).margin({left:12})}.width(100%).padding({left:16,right:16,top:12,bottom:12}).backgroundColor(this.selectedIndexitem.id?#E3F2FD:Color.White)}.onClick((){this.selectedIndexitem.id})},(item:CourseItem)item.id.toString())}.width(100%).layoutWeight(1).scrollBar(BarState.Off).edgeEffect(EdgeEffect.Spring).divider({strokeWidth:0.5,color:#E0E0E0,startMargin:56,endMargin:16})}.width(100%).height(100%).backgroundColor(#FAFAFA)}}5.3 关键代码解析1数据驱动渲染使用State装饰courseList数组配合ForEach实现数据驱动的列表渲染。当数组发生变化时UI 会自动刷新。2选中状态高亮通过State selectedIndex记录当前选中的课程 ID在ListItem中根据this.selectedIndex item.id动态设置背景色。3分割线配置.divider({strokeWidth:0.5,color:#E0E0E0,startMargin:56,// 左侧留白与序号圆圈对齐endMargin:16})startMargin和endMargin让分割线不与序号圆圈重叠视觉上更加整洁。4边缘回弹效果.edgeEffect(EdgeEffect.Spring)为列表添加了弹性回弹效果提升用户的滑动体验。六、最佳实践总结6.1 性能优化优化手段说明使用LazyForEach大数据量列表按需加载避免一次性创建所有组件设置cachedCount缓存屏幕外的列表项减少快速滑动时的创建开销提供keyGenerator帮助框架精确识别变化项减少不必要的组件重建避免在ListItem中使用复杂嵌套减少布局层级提升渲染速度6.2 常见问题问题原因及解决方案列表项不显示检查ListItem内是否只有一个根节点组件数据更新后 UI 不刷新使用State装饰数据源或通过keyGenerator精确控制刷新滚动不流畅使用LazyForEach替代ForEach设置合理的cachedCount水平列表无法滚动确保设置了.listDirection(Axis.Horizontal)且有足够宽度6.3 使用建议简单列表用ForEach数据量在几十条以内直接使用ForEach即可。长列表用LazyForEach数据量较大时配合IDataSource接口实现懒加载。分组场景用ListItemGroup配合sticky属性实现吸顶效果适合通讯录、分类列表等场景。善用ListScroller通过scroller参数可以在代码中控制列表滚动到指定位置。七、参考链接List 官方 API 文档ForEach 循环渲染LazyForEach 懒加载

《级联年度选择》一、List使用指南

相关推荐

计科毕设易上手项目选题分享

如何高效使用BG3ModManager：博德之门3模组管理完整指南

2026年选工业船型开关，这3家可靠供应商值得关注

更多资讯

华硕笔记本风扇噪音大？用 G-Helper 3 步完成风扇校准与曲线调优

7篇关键论文读懂AI论文周精选：2025年6月ML Papers of the Week完整解读

SKP转GLTF全攻略：原理、在线工具与实操避坑指南

提示词工程实战指南：10个技巧让AI输出质量翻倍

从Grok Bot看Agent技术：大模型工具调用与私有化部署实战

GB/T 15532-2008 软件测试规范解读：从测试过程到文档落地的完整指南

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？