HarmonyOS 鸿蒙Next通用列表组件的封装实践

HarmonyOS 鸿蒙Next通用列表组件的封装实践

基于最近项目开发中发现模块业务需求，抽离封装的通用列表组件，已应用到app下消息、发现等多个模块。

概述

DiscoverList 是一个封装良好的鸿蒙列表组件，用于支持多种类型的列表渲染和数据加载功能。它不仅提供了基本的列表展示能力，还扩展了下拉刷新、触底加载、瀑布流布局等高级特性，适用于需要高效展示内容的场景。该组件通过参数化设计实现了高度可配置性，开发者可以灵活控制列表类型（普通列表或瀑布流）、是否启用自动加载、下拉刷新等功能。此外，结合 ArkUI 的声明式语法和动画机制，DiscoverList 在交互体验上也表现得非常流畅。

一、组件设计目标

• 统一接口：提供一致的 API 接口，简化使用。
• 多类型支持：支持普通列表与瀑布流列表。
• 数据加载能力：内置下拉刷新、触底加载逻辑。
• 状态管理与动画反馈：增强用户交互体验。
• 可扩展性强：便于后续功能拓展或样式定制。

二、技术架构与实现细节

1. 组件结构设计

DiscoverList 是基于 ArkUI 框架构建的声明式组件，其核心由以下几部分构成：

• 参数定义：通过 @Prop 和 @State 控制外部传入的状态和内部状态变化。
• 条件渲染：根据当前状态展示不同的 UI 内容（如加载中、无更多数据等）。
• 构建器模式：使用 @Builder 实现灵活的内容插入机制，提升组件可扩展性。
• 事件绑定：监听滚动、刷新、触底等事件，驱动业务逻辑。

export struct DiscoverList {
  // 列表类型
  listType: ListType = ListType.NORMAL
  // 是否启用自动加载
  @Prop autoLoad: boolean = true
  // 是否加载完成
  @Prop finished: boolean = false
  // 触发刷新回调
  refresh(): void = () => {}
  // 触发加载回调
  load(): void = () => {}
}

2. 多类型列表支持

通过枚举 ListType 定义不同类型的列表，并在 build() 方法中根据类型选择对应的布局组件：

• 普通列表：使用 List + ListItem 构建线性列表。
• 瀑布流列表：使用 WaterFlow 实现列分布布局。

if (this.listType === ListType.WATER) {
  WaterFlow({ scroller: this.scroller, layoutMode: this.layoutMode }) {
    this.listContent()
  }
} else if (this.listType === ListType.NORMAL) {
  List({ scroller: this.scroller }) {
    this.listContent()
  }
}

💡 提示：通过配置 columnsTemplate 和 columnsGap 可自定义瀑布流列数及间距。

3. 下拉刷新与触底加载

下拉刷新

使用系统提供的 Refresh 组件实现下拉刷新功能，并结合 onStateChange 和 onRefreshing 回调更新状态和触发数据请求。

Refresh({
  refreshing: $$this.isRefreshing,
  refreshingContent: this.contentNode
}) {
  this.switchList()
}
.onStateChange((refreshStatus: RefreshStatus) => {
  this.refreshStatus = refreshStatus
})
.onRefreshing(() => {
  this.refresh()
})

触底加载

通过 onReachEnd 监听滚动到底部事件，执行 load 回调加载更多数据。

.onReachEnd(() => {
  this.autoLoad && this.load()
})

此外还提供了 onScrollIndex，用于提前加载数据，避免空白等待。

4. 动画与 Lottie 支持

为提升用户体验，组件集成了 Lottie 动画库来实现刷新和加载动画。

• 使用 LottieComponent 封装动画播放逻辑。
• 动画资源路径可通过参数配置，方便替换。

LottieComponent({
  path: 'lottie/refresh.json',
  wh: 108,
  hg: 40,
  cb: (ai) => {
    context.animateRefresh = ai
    ai?.setSpeed(0.5)
  }
})

5. 构建器与内容注入

通过 @BuilderParam 和 @Builder 装饰器实现内容注入机制，允许开发者自定义列表项内容。

@BuilderParam
listContent(): void = this.DefaultListContent

@Builder
DefaultListContent() {
  // 默认空内容
}

这样使用者可以通过传递 listContent 来渲染自己的列表项，极大增强了组件灵活性。

6. 状态管理与生命周期处理

组件使用了多种状态装饰器来管理 UI 状态：

• @State：控制本地状态（如刷新状态、加载状态）。
• @Prop：接收父组件传递的状态。
• @Link：实现双向绑定，同步刷新状态。

同时，在 aboutToAppear 生命周期中初始化动画节点，确保组件首次渲染时即可使用动画资源。

三、性能优化

• 使用 layoutMode: WaterFlowLayoutMode.SLIDING_WINDOW 减少一次性渲染的数据量。
• 利用 onScrollIndex 实现预加载策略，减少空白区域。
• 动画资源懒加载，避免启动阶段资源占用过高。

四、总结

DiscoverList 是一个功能丰富、结构清晰、扩展性强的鸿蒙列表组件。它融合了现代前端开发中的诸多最佳实践，包括：

• 多态设计：支持不同列表类型。
• 动画交互：使用 Lottie 提升视觉体验。
• 构建器模式：增强组件复用性和可维护性。
• 状态管理：通过装饰器实现高效的响应式 UI。
• 滚动优化：减少不必要的渲染，提高性能。