HarmonyOS 6实战：简单列表折叠和展开

问题现象在HarmonyOS应用开发中开发者经常需要实现可折叠和展开的列表功能这种交互模式在多种场景中都有广泛应用典型应用场景设置界面中分类设置项的展开与收起文件管理器中目录树的展开与收起聊天应用中消息记录的折叠展示电商应用中商品分类的层级展示新闻应用中长评论的展开与收起交互需求用户点击展开按钮显示更多内容用户点击收起按钮隐藏详细内容需要平滑的展开/收起动画效果支持多级嵌套的折叠结构保持列表滚动时的性能流畅背景知识在深入解决方案之前我们先了解HarmonyOS中相关的组件特性List组件基础特性List组件是HarmonyOS中用于展示连续、多行同类数据的核心组件支持垂直滚动适合长列表展示支持ListItem、ListItemGroup和自定义组件作为子项内置虚拟化技术优化大数据量性能支持滚动事件监听和定制TreeView组件特性TreeView是专门为层级数据设计的组件专门用于显示嵌套结构数据支持父节点和子节点的展开/折叠适用于效率型应用如文件管理器、侧边导航栏内置展开/收起动画效果折叠展开的核心原理无论使用哪种组件折叠展开的核心原理都是状态管理记录每个列表项的展开状态条件渲染根据状态决定是否渲染子内容动画过渡在状态切换时添加平滑动画布局计算动态计算容器高度变化解决方案基于HarmonyOS的特性我们提供两种实现方案方案一使用TreeView组件推荐TreeView是HarmonyOS官方提供的树形结构组件专门为层级数据设计提供了开箱即用的折叠展开功能。// TreeView实现示例 import { TreeView, TreeNodeData } from ohos.arkui.treeview; Component struct TreeViewExample { // 树形结构数据 private treeData: TreeNodeData[] [ { value: 父节点1, isExpanded: false, children: [ { value: 子节点1-1 }, { value: 子节点1-2 } ] }, { value: 父节点2, isExpanded: true, children: [ { value: 子节点2-1 }, { value: 子节点2-2, children: [ { value: 孙节点2-2-1 } ] } ] } ]; build() { Column() { // 使用TreeView组件 TreeView({ data: this.treeData, itemTemplate: (item: TreeNodeData) { // 自定义节点渲染 return this.renderTreeNode(item); } }) .width(100%) .height(100%) } } // 自定义树节点渲染 Builder renderTreeNode(item: TreeNodeData) { Row() { // 展开/收起图标 if (item.children item.children.length 0) { Image($r(app.media.ic_arrow)) .width(20) .height(20) .rotate({ angle: item.isExpanded ? 90 : 0 }) .animation({ duration: 200, curve: Curve.Ease }) } Text(item.value) .fontSize(16) .margin({ left: 10 }) } .width(100%) .padding(10) } }TreeView方案的优势✅ 内置展开/收起动画效果✅ 支持多级嵌套结构✅ 性能优化大数据量表现良好✅ 代码简洁易于维护适用场景文件浏览器组织架构图多级分类菜单复杂的层级数据展示方案二使用List组件自定义实现当需要更灵活的定制或项目已大量使用List组件时可以使用List结合条件渲染来实现折叠展开功能。// 完整实现代码 Entry Component struct ExpandableListExample { // 列表数据 private dataItems: number[] [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; // 记录每个列表项的展开状态 State isExpanded: boolean[] new Array(this.dataItems.length).fill(false); // 获取UI上下文 private uiContext: UIContext getUIContext(); build() { Column() { // 列表标题 Text(可折叠列表示例) .fontSize(24) .fontWeight(FontWeight.Bold) .margin({ top: 40, bottom: 20 }); // 主列表容器 List({ space: 10, initialIndex: 0 }) { ForEach(this.dataItems, (item: number, index: number) { ListItem() { this.renderListItem(item, index) } }, (item: number) item.toString()) } .width(100%) .height(100%) .scrollBar(BarState.Auto) } .width(100%) .height(100%) .padding(16) .backgroundColor(#F8F9FA) } // 构建列表项 Builder renderListItem(item: number, index: number) { Column({ space: 0 }) { // 顶部控制区域 Row() { // 项目序号 Text(项目 ${item}) .fontSize(18) .fontWeight(FontWeight.Medium) .fontColor(#1A1A1A) // 右侧占位用于对齐按钮 Blank() // 展开/收起按钮 Button(this.isExpanded[index] ? 收起 ▲ : 展开 ▼) .fontSize(14) .fontColor(#0066CC) .backgroundColor(#FFFFFF) .borderRadius(20) .padding({ left: 12, right: 12, top: 6, bottom: 6 }) .border({ width: 1, color: #0066CC }) .onClick(() { this.toggleExpand(index); }) } .width(100%) .padding({ left: 16, right: 16, top: 12, bottom: 12 }) .justifyContent(FlexAlign.SpaceBetween) // 分隔线 Divider() .color(#E0E0E0) .strokeWidth(1) .margin({ left: 16, right: 16 }) // 可展开的内容区域 if (this.isExpanded[index]) { this.renderExpandableContent(item, index) } } .width(100%) .backgroundColor(#FFFFFF) .borderRadius(12) .shadow({ radius: 4, color: #1A1A1A, offsetX: 0, offsetY: 2 }) } // 构建可展开的内容 Builder renderExpandableContent(item: number, index: number) { Column({ space: 8 }) { // 内容标题 Text(详细内容) .fontSize(16) .fontWeight(FontWeight.Medium) .fontColor(#333333) .margin({ top: 12, left: 16, right: 16 }) // 内容正文 Text(这是项目 item 的详细内容区域可以放置任何需要展开显示的内容。这里可以包含文本、图片、按钮等任何组件。折叠展开功能让界面更加简洁同时不丢失信息的完整性。) .fontSize(14) .fontColor(#666666) .lineHeight(20) .textOverflow({ overflow: TextOverflow.Ellipsis }) .maxLines(3) .margin({ left: 16, right: 16, bottom: 8 }) // 内容操作按钮区域 Row({ space: 12 }) { Button(操作1) .fontSize(12) .backgroundColor(#F0F7FF) .fontColor(#0066CC) .borderRadius(6) Button(操作2) .fontSize(12) .backgroundColor(#F0F7FF) .fontColor(#0066CC) .borderRadius(6) } .margin({ left: 16, right: 16, bottom: 16 }) .justifyContent(FlexAlign.Start) } .width(100%) } // 切换展开状态带动画 private toggleExpand(index: number): void { this.uiContext.animateTo({ duration: 300, // 动画持续时间300ms curve: Curve.EaseInOut, // 缓动曲线 onFinish: () { // 动画完成回调 console.info(第${index}项的${this.isExpanded[index] ? 收起 : 展开}动画完成); } }, () { // 在动画上下文中更新状态 this.isExpanded[index] !this.isExpanded[index]; }); } }关键点分析1. 状态管理的实现折叠展开功能的核心是状态管理。我们使用State装饰器来管理每个列表项的展开状态// 创建与数据项相同长度的布尔数组 State isExpanded: boolean[] new Array(dataItems.length).fill(false); // 初始化所有项为收起状态 // true表示展开false表示收起状态管理的最佳实践使用数组存储每个列表项的状态便于通过索引访问初始状态设为false默认收起状态变化触发UI自动刷新2. 条件渲染的实现HarmonyOS使用条件渲染语句来控制组件的显示与隐藏// 条件渲染语法 if (this.isExpanded[index]) { // 当条件为true时渲染的内容 this.renderExpandableContent(item, index) }条件渲染的特点基于布尔值的动态渲染支持复杂的条件表达式可以与动画效果结合使用性能优化不渲染隐藏的组件3. 动画效果的实现平滑的动画效果能显著提升用户体验。我们使用animateTo方法实现// 创建动画上下文 this.uiContext.animateTo({ duration: 300, // 动画持续时间 curve: Curve.EaseInOut, // 缓动曲线 onFinish: () { // 动画完成后的回调 } }, () { // 在动画上下文中更新状态 this.isExpanded[index] !this.isExpanded[index]; });动画参数详解duration: 动画持续时间单位毫秒curve: 动画曲线控制动画速度变化Curve.Linear: 线性Curve.Ease: 缓入缓出Curve.EaseIn: 缓入Curve.EaseOut: 缓出Curve.EaseInOut: 缓入缓出onFinish: 动画完成回调函数4. 性能优化考虑在处理大量列表项时性能优化至关重要// 使用LazyForEach优化大数据量 LazyForEach(this.dataSource, (item: DataItem) { ListItem() { this.renderListItem(item) } }, (item: DataItem) item.id.toString()) // 虚拟化技术 List({ scroller: this.listScroller }) .cachedCount(5) // 预加载数量 .edgeEffect(EdgeEffect.None) // 禁用边缘效果提升性能扩展应用场景一多级嵌套折叠在实际应用中我们经常需要多级嵌套的折叠结构Component struct MultiLevelExpandableList { State expandedLevel1: boolean[] [false, false, false]; State expandedLevel2: boolean[][]; aboutToAppear() { // 初始化二级展开状态 this.expandedLevel2 [ [false, false], [false, false, false], [false] ]; } build() { List() { ForEach(this.expandedLevel1, (_, level1Index) { ListItem() { Column() { // 一级项目 this.renderLevel1Item(level1Index) // 二级项目条件渲染 if (this.expandedLevel1[level1Index]) { ForEach(this.expandedLevel2[level1Index], (_, level2Index) { this.renderLevel2Item(level1Index, level2Index) }) } } } }) } } }场景二手风琴效果同时只展开一项某些场景需要手风琴效果即同时只能展开一个项目Component struct AccordionList { State expandedIndex: number -1; // -1表示没有展开项 toggleExpand(index: number): void { this.uiContext.animateTo({ duration: 300, curve: Curve.EaseInOut }, () { if (this.expandedIndex index) { // 点击已展开的项收起 this.expandedIndex -1; } else { // 点击其他项展开新项 this.expandedIndex index; } }); } build() { List() { ForEach(this.dataItems, (item, index) { ListItem() { Column() { // 列表项标题 this.renderItemHeader(item, index) // 内容区域 if (index this.expandedIndex) { this.renderItemContent(item) } } } }) } } }场景三记住展开状态在应用重启后保持用户的展开状态import { PersistentStorage } from ohos.data.preferences; Component struct RememberExpandedState { State isExpanded: boolean[] []; private preferences: PersistentStorage.Preferences | null null; async aboutToAppear() { // 初始化Preferences this.preferences await PersistentStorage.getPreferences(this.context, expandState); // 从持久化存储加载状态 const savedState await this.preferences.get(expandedStates, []); this.isExpanded JSON.parse(savedState); } async toggleExpand(index: number) { this.uiContext.animateTo({ duration: 300 }, () { this.isExpanded[index] !this.isExpanded[index]; // 保存状态到持久化存储 this.saveExpandedState(); }); } async saveExpandedState() { if (this.preferences) { await this.preferences.put(expandedStates, JSON.stringify(this.isExpanded)); await this.preferences.flush(); } } }常见问题与解决方案Q1: 展开内容时列表跳动或闪烁问题原因高度计算不准确动画与布局更新不同步条件渲染触发时机问题解决方案// 1. 使用固定高度或最大高度 if (this.isExpanded[index]) { Column() { // 展开内容 } .height(200) // 固定高度 .clip(false) // 允许内容溢出 } // 2. 使用布局过渡动画 .animation({ duration: 300, curve: Curve.EaseInOut, delay: 0, iterations: 1, playMode: PlayMode.Normal }) // 3. 确保状态更新在动画上下文中 this.uiContext.animateTo({ duration: 300 }, () { this.isExpanded[index] !this.isExpanded[index]; });Q2: 大数据量时性能下降优化策略// 1. 使用LazyForEach懒加载 LazyForEach(this.dataSource, (item) { ListItem() { // 列表项内容 } }) // 2. 设置合理的缓存数量 List({ initialIndex: 0 }) .cachedCount(10) // 预渲染前后10个项目 // 3. 避免复杂计算在渲染过程中 aboutToAppear() { // 在组件出现前预处理数据 this.preprocessData(); } // 4. 使用shouldComponentUpdate优化 shouldComponentUpdate(params: Recordstring, unknown): boolean { // 只在自己相关的状态变化时更新 return params.index this.index; }Q3: 嵌套滚动冲突问题场景展开内容内部有可滚动区域与外部List滚动冲突。解决方案// 内部滚动区域禁用滚动由外部List统一控制 Scroll() { // 内部内容 } .scrollable(ScrollDirection.Vertical) .scrollBar(BarState.Off) .onScrollEdge((side: ScrollEdge) { // 滚动到边缘时传递给外部 if (side ScrollEdge.Top || side ScrollEdge.Bottom) { return; // 允许外部List继续滚动 } })Q4: 展开动画不流畅优化方法// 1. 使用硬件加速 .transform({ translate: { x: 0, y: 0, z: 0 } }) .backdropBlur(0) // 启用硬件加速 // 2. 优化动画曲线 animateTo({ duration: 300, curve: Curve.Friction // 物理曲线更自然 }) // 3. 减少重绘区域 .clip(true) // 裁剪超出部分 .opacity(1) // 避免透明度变化总结与最佳实践方案选择建议场景特点推荐方案理由简单的展开收起List 条件渲染灵活控制代码简单多级嵌套结构TreeView内置支持开发效率高大数据量List LazyForEach性能优化内存占用低需要复杂动画List animateTo动画控制更精细需要记住状态任意方案 PersistentStorage状态持久化性能优化清单数据层面使用懒加载LazyForEach分页加载大数据集避免在渲染过程中进行复杂计算渲染层面设置合理的cachedCount使用shouldComponentUpdate避免不必要渲染简化组件结构减少嵌套动画层面使用硬件加速优化动画曲线避免同时执行多个复杂动画内存层面及时清理不需要的状态使用轻量级数据格式监控内存使用情况代码规范建议// ✅ 推荐写法 Component struct ExpandableList { // 明确的命名 State private expandedStates: boolean[] []; // 单一职责的方法 private toggleItem(index: number): void { this.uiContext.animateTo({ duration: 300, curve: Curve.EaseInOut }, () { this.expandedStates[index] !this.expandedStates[index]; }); } // 清晰的组件结构 Builder renderListItem(item: DataItem, index: number) { Column() { this.renderHeader(item, index) this.renderContent(item, index) } } } // ❌ 不推荐写法 Component struct BadExample { State flag: boolean[] []; // 命名不清晰 // 方法职责不单一 // 组件结构混乱 }测试要点在实现折叠展开功能后需要进行全面测试功能测试点击展开/收起按钮功能正常动画流畅无卡顿多级嵌套展开正确手风琴模式工作正常性能测试100项目流畅滚动展开收起响应迅速内存占用合理动画帧率稳定兼容性测试不同设备尺寸适配横竖屏切换正常深色/浅色主题适配不同HarmonyOS版本兼容用户体验测试动画自然流畅交互反馈及时状态记忆正确无障碍功能支持通过本文的详细介绍相信你已经掌握了在HarmonyOS 6中实现列表折叠展开功能的多种方法。无论选择TreeView还是自定义List方案关键是根据实际业务需求选择最合适的方案并结合性能优化和用户体验考虑打造出既美观又实用的列表交互体验。在实际开发中建议先使用TreeView快速实现基础功能如果需要更复杂的定制再考虑使用List自定义实现。同时不要忘记性能优化和用户体验的细节这些都是打造高质量应用的关键。