HarmonyOS应用开发实战：小事记 - List 组件与 ListItem 复用：@Reusable 装饰器与全局复用池

前言List是 ArkUI 中最常用的长列表组件支持垂直和水平方向的高性能滚动。当列表项数量庞大时组件复用成为提升性能的关键。HarmonyOS 提供了Reusable装饰器来实现 ListItem 的复用并通过cachedCount控制缓存策略。本文以小事记xiaoshiji_ohos_app 的WitnessListPage.ets和RelatedPeoplePage.ets为分析对象深入解析 List 组件的复用机制和性能优化。本文参考 HarmonyOS 官方文档arkts-common-list-flow.md 和 arkts-component-reusable.md。一、List 的基本用法1.1 基本结构// List 容器的基本结构 List({ space: 12 }) { ForEach(this.items, (item) { ListItem() { Text(item.name) } }) } .width(100%) .edgeEffect(EdgeEffect.Spring) }1.2 List 与 Scroll 的对比对比维度ListScroll渲染方式懒加载只渲染可见项全量渲染性能适合长列表适合短内容复用机制支持Reusable不支持布局方向垂直/水平垂直/水平/双向分组支持支持ListItemGroup不支持二、Reusable 组件复用2.1 基本用法// 定义可复用的列表项组件 Reusable Component export struct WitnessItem { Prop name: string ; Prop relationship: string ; Prop isSelected: boolean false; aboutToReuse(params: Recordstring, Object): void { // 复用前重置数据 this.name params.name as string; this.relationship params.relationship as string; this.isSelected params.isSelected as boolean; } build() { Row() { Circle().width(44).height(44).fill(#E5E7EB) Column({ space: 2 }) { Text(this.name) .fontSize(15) .fontWeight(FontWeight.Medium) Text(this.relationship) .fontSize(12) .fontColor(#9CA3AF) } .margin({ left: 12 }) Blank() if (this.isSelected) { Circle().width(24).height(24).fill(#7B68EE) } } .width(100%) .height(64) .padding({ left: 20, right: 20 }) } }2.2 在 List 中使用// 在 List 中使用可复用的列表项 Entry Component export struct WitnessListPage { State witnesses: Witness[] getMockWitnesses(); build() { Column() { List() { LazyForEach(new WitnessDataSource(this.witnesses), (witness: Witness) { ListItem() { WitnessItem({ name: witness.name, relationship: witness.relationship, isSelected: witness.isSelected }) } }, (witness: Witness) witness.id) } .width(100%) .layoutWeight(1) .cachedCount(10) // 预缓存 10 个列表项 } .width(100%) .height(100%) .backgroundColor(Color.White) } }三、LazyForEach 数据源3.1 实现数据源// 实现 LazyForEach 的数据源 class WitnessDataSource implements IDataSource { private dataArray: Witness[] []; constructor(data: Witness[]) { this.dataArray data; } totalCount(): number { return this.dataArray.length; } getData(index: number): Witness { return this.dataArray[index]; } registerDataChangeListener(listener: DataChangeListener): void { // 注册数据变化监听 } unregisterDataChangeListener(listener: DataChangeListener): void { // 取消数据变化监听 } }3.2 cachedCount 缓存策略// 缓存策略配置 List() { // 列表项 } .cachedCount(10) // 预缓存 10 个列表项cachedCount 值效果适用场景0不缓存列表项很少5少量缓存中等列表10标准缓存长列表推荐20大量缓存快速滚动场景四、多类型列表项4.1 多类型渲染// 多类型列表项 List() { // 轮播图类型 ListItem() { Swiper() { // 轮播内容 } } // 普通列表项 ForEach(this.items, (item) { ListItem() { Text(item.name) } }) }五、分组吸顶5.1 ListItemGroup 分组// 分组列表 List() { ListItemGroup({ header: this.buildGroupHeader(5月) }) { ListItem() { Text(我们结婚了) } ListItem() { Text(第一次旅行) } } ListItemGroup({ header: this.buildGroupHeader(3月) }) { ListItem() { Text(新年愿望) } } } .sticky(StickyStyle.Header) // 分组头吸顶六、性能优化6.1 优化策略对比策略效果实现方式Reusable组件复用减少组件创建使用Reusable装饰器LazyForEach懒加载只渲染可见项使用IDataSourcecachedCount缓存减少空白期配置缓存数量固定列表项高度提高滚动性能设置固定高度6.2 使用建议列表项超过 20 个时使用LazyForEach替代ForEach列表项结构复杂时使用Reusable装饰器设置cachedCount为 5-10平衡内存和体验使用ListItemGroup实现分组吸顶效果十、最佳实践与优化建议在实际开发中合理运用上述技术可以显著提升应用的性能和用户体验。以下是几个关键的最佳实践建议10.1 性能优化要点优化方向具体措施预期效果渲染性能减少不必要的组件重建提升帧率内存管理及时释放不再使用的资源降低内存占用响应速度避免在主线程执行耗时操作提升交互流畅度10.2 推荐实践步骤按照以下步骤进行优化使用 DevEco Studio 的 Profiler 工具分析当前性能瓶颈针对识别出的热点进行针对性优化通过单元测试和集成测试验证优化效果在真机环境下进行回归测试10.3 代码示例// 推荐的最佳实践示例 Component export struct OptimizedComponent { // 使用 State 管理最小粒度的状态 State private isActive: boolean false; build() { Column() { Text(this.isActive ? 激活 : 未激活) .fontSize(16) } .onClick(() { // 使用 animateTo 实现平滑过渡 animateTo({ duration: 300 }, () { this.isActive !this.isActive; }); }); } }最佳实践提示在编写代码时始终遵循 ArkUI 的性能优化原则避免在 build() 方法中执行复杂计算或频繁的状态更新。十、进一步学习与拓展掌握以上内容后可以进一步探索以下相关主题深化对 HarmonyOS 开发的理解10.1 推荐学习路径学习阶段主题预期目标基础阶段掌握核心概念和 API 用法能够独立完成基本功能开发进阶阶段理解底层原理和最佳实践能够优化应用性能和用户体验高级阶段掌握架构设计和性能调优能够主导复杂项目的技术方案10.2 实践项目建议建议通过以下实践项目巩固所学知识基于小事记项目尝试独立实现一个类似的功能模块阅读 HarmonyOS 官方 Sample 代码学习最佳实践参与开源社区贡献代码或文档10.3 相关资源HarmonyOS 官方文档提供完整的 API 参考和开发指南DevEco Studio 文档包含 IDE 使用技巧和调试方法开源社区获取项目源码和开发经验学习建议理论与实践相结合在阅读文档的同时动手编写代码才能更好地掌握 HarmonyOS 应用开发技能。总结本文深入解析了 List 组件和 ListItem 复用机制。核心要点如下Reusable 装饰器通过aboutToReuse重置数据实现列表项复用LazyForEach 懒加载只渲染可见区域减少内存占用cachedCount 缓存预缓存列表项减少滚动时的空白期ListItemGroup 分组支持分组头吸顶效果性能优化组合使用ReusableLazyForEachcachedCount如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力九、完整示例代码9.1 完整组件实现以下是一个完整的组件实现示例展示了本文介绍的各个技术点的综合运用import { Component, State, Prop } from kit.ArkUI; Component export struct DemoComponent { Prop title: string ; State count: number 0; build() { Column({ space: 12 }) { // 标题区域 Text(this.title) .fontSize(18) .fontWeight(FontWeight.Bold) .fontColor(#1A1A2E) .width(100%) // 内容区域 Text(当前计数: ${this.count}) .fontSize(14) .fontColor(#6B7280) // 交互按钮 Button(点击增加) .width(120) .height(40) .backgroundColor(#7B68EE) .borderRadius(20) .fontColor(Color.White) .onClick(() { this.count; }) } .width(100%) .padding(16) .backgroundColor(Color.White) .borderRadius(12) .shadow({ radius: 4, color: #00000008, offsetX: 0, offsetY: 2 }) } }9.2 使用方式在页面中引入并使用该组件Entry Component struct Index { build() { Column() { DemoComponent({ title: 示例组件 }) } .width(100%) .height(100%) .backgroundColor(#F8F9FA) } }9.3 代码说明组件封装使用Component装饰器定义可复用的组件状态管理使用State管理组件内部状态参数传递使用Prop接收外部传入的参数事件处理使用onClick处理用户交互样式优化使用borderRadius、shadow等属性美化 UI相关资源官方文档 - 开发者指南HarmonyOS 应用开发官方文档 - ArkUI 组件参考ArkUI 组件官方文档 - API 参考API 参考官方文档 - 状态管理状态管理概述官方文档 - 动画动画概述官方文档 - 网络管理网络管理官方文档 - 数据管理数据管理开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net