鸿蒙App下拉刷新与上拉加载更多（列表数据分页）技术详解

一、引言​

二、技术背景​

1. 核心组件与机制

• Refresh组件：鸿蒙官方下拉刷新容器，支持自定义刷新头（Header）和触发阈值。
• List组件：高性能滚动列表，内置onReachEnd事件（滚动到底部时触发）。
• 状态管理：通过@State、@Prop等装饰器管理加载状态（如isRefreshing、isLoadingMore）、分页参数（页码pageNum、页大小pageSize）。
• 分页模式：主流采用“页码+页大小”（如pageNum=1&pageSize=10），首次加载第1页，上拉加载下一页（pageNum++）。

2. 行业痛点

• 体验割裂：下拉/上拉无反馈（如无loading动画）、加载失败无重试。
• 性能问题：大数据列表滚动卡顿、重复请求（如快速滑动触发多次加载）。
• 状态混乱：分页参数（页码、总数）与UI不同步（如加载中再次触发加载）。

三、应用场景​

四、核心原理与流程图​

1. 原理解释

• 下拉刷新：用户下拉列表超过阈值（默认50vp），触发Refresh的onRefresh事件，重置页码为1，请求最新数据并替换列表。
• 上拉加载：List滚动到底部时触发onReachEnd事件，页码递增（pageNum++），请求下一页数据并追加到列表。
• 状态控制：通过isRefreshing（下拉中）、isLoadingMore（加载更多中）避免重复请求；通过hasMore（是否有更多数据）控制加载终止。

2. 原理流程图

graph TD
    subgraph 下拉刷新流程
        A[用户下拉列表] --> B{下拉距离>阈值?}
        B -->|是| C[显示刷新头动画]
        B -->|否| D[恢复原状]
        C --> E[松手触发onRefresh]
        E --> F[设置isRefreshing=true]
        F --> G[请求第1页数据]
        G --> H{成功?}
        H -->|是| I[更新列表数据<br>重置页码pageNum=1]
        H -->|否| J[显示错误提示]
        I & J --> K[设置isRefreshing=false]
    end

    subgraph 上拉加载流程
        L[List滚动到底部] --> M[触发onReachEnd]
        M --> N{isLoadingMore=false且hasMore=true?}
        N -->|是| O[设置isLoadingMore=true]
        O --> P[请求第pageNum+1页数据]
        P --> Q{成功?}
        Q -->|是| R[追加数据到列表<br>pageNum++]
        Q -->|否| S[显示错误提示<br>pageNum--]
        R & S --> T[设置isLoadingMore=false]
        N -->|否| U[忽略触发]
    end

五、核心特性​

• 原生流畅性：Refresh和List组件基于鸿蒙图形引擎优化，滚动无卡顿。
• 灵活定制：支持自定义刷新头（如箭头旋转动画）、加载更多Footer（如“加载中...”文本）。
• 状态可视化：内置LoadingProgress组件显示加载状态，支持空数据（Empty组件）、错误重试（Button组件）。
• 分布式适配：跨设备（手机/平板/折叠屏）列表布局自适应，分页状态同步。

六、环境准备​

1. 开发环境

• DevEco Studio：3.1+（支持API 9+，ArkUI声明式开发范式）
• HarmonyOS SDK：API Version 9及以上
• 设备：HarmonyOS 3.0+真机或模拟器（推荐P40 Pro模拟器测试折叠屏）

2. 项目配置

// entry/build.gradle（确保SDK版本正确）
android {
    compileSdkVersion 9
    defaultConfig {
        compatibleSdkVersion 9
    }
}

七、详细代码实现​

1. 页面结构与状态定义（NewsListPage.ets）

@Entry
@Component
struct NewsListPage {
  // 列表数据（分页存储）
  @State newsList: Array<NewsItem> = []
  // 分页参数
  @State pageNum: number = 1  // 当前页码（初始第1页）
  @State pageSize: number = 10 // 页大小（每页10条）
  @State total: number = 0     // 总数据量（从接口获取）
  // 加载状态
  @State isRefreshing: boolean = false  // 下拉刷新中
  @State isLoadingMore: boolean = false // 上拉加载中
  // 错误信息
  @State errorMsg: string = ''

  // 模拟网络请求（实际项目中替换为真实API）
  private async fetchNews(pageNum: number, pageSize: number): Promise<{ list: NewsItem[], total: number }> {
    return new Promise(resolve => {
      setTimeout(() => {
        // 模拟10条/页数据，共25条（第3页仅5条）
        const mockData: NewsItem[] = [];
        const startId = (pageNum - 1) * pageSize + 1;
        const endId = Math.min(startId + pageSize - 1, 25); // 总25条数据
        for (let i = startId; i <= endId; i++) {
          mockData.push({
            id: i,
            title: `新闻标题 ${i}（第${pageNum}页）`,
            content: `这是第${i}条新闻的内容摘要...`,
            time: `2024-05-${String(10 + (i % 20)).padStart(2, '0')}`
          });
        }
        resolve({ list: mockData, total: 25 });
      }, 1000); // 模拟网络延迟1秒
    });
  }

  // 下拉刷新：加载第1页数据
  private async onRefresh() {
    this.isRefreshing = true;
    this.errorMsg = '';
    try {
      const { list, total } = await this.fetchNews(1, this.pageSize);
      this.newsList = list; // 替换旧数据
      this.total = total;
      this.pageNum = 1; // 重置页码
    } catch (err) {
      this.errorMsg = '刷新失败，请重试';
    } finally {
      this.isRefreshing = false;
    }
  }

  // 上拉加载更多：加载下一页数据
  private async onLoadMore() {
    if (this.isLoadingMore || !this.hasMore) return; // 避免重复加载或无更多数据
    this.isLoadingMore = true;
    this.errorMsg = '';
    try {
      const nextPage = this.pageNum + 1;
      const { list, total } = await this.fetchNews(nextPage, this.pageSize);
      this.newsList = [...this.newsList, ...list]; // 追加新数据
      this.total = total;
      this.pageNum = nextPage; // 更新页码
    } catch (err) {
      this.errorMsg = '加载更多失败，请重试';
      this.pageNum--; // 加载失败回滚页码
    } finally {
      this.isLoadingMore = false;
    }
  }

  // 计算是否有更多数据（当前数据量 < 总量）
  private get hasMore(): boolean {
    return this.newsList.length < this.total;
  }

  build() {
    Refresh({
      refreshing: this.isRefreshing,
      onRefresh: () => this.onRefresh() // 绑定下拉刷新事件
    }) {
      List() {
        // 列表项
        ForEach(this.newsList, (item: NewsItem) => {
          ListItem() {
            NewsItemCard({ item: item }) // 自定义列表项组件
          }
        }, (item: NewsItem) => item.id.toString())

        // 加载更多Footer（滚动到底部时显示）
        ListItem() {
          this.LoadMoreFooter()
        }.height(60).margin({ top: 10 })
      }
      .onReachEnd(() => this.onLoadMore()) // 绑定滚动到底部事件
      .width('100%')
      .height('100%')
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }

  // 加载更多Footer组件
  @Builder LoadMoreFooter() {
    Row() {
      if (this.isLoadingMore) {
        LoadingProgress().size({ width: 24, height: 24 }).color('#007DFF')
        Text('加载中...').fontSize(14).margin({ left: 8 })
      } else if (this.errorMsg) {
        Text(this.errorMsg).fontSize(14).fontColor('#FF0000')
        Button('重试').fontSize(14).margin({ left: 8 }).onClick(() => this.onLoadMore())
      } else if (!this.hasMore) {
        Text('没有更多数据了').fontSize(14).fontColor('#999999')
      } else {
        Text('上拉加载更多').fontSize(14).fontColor('#666666')
      }
    }
    .justifyContent(FlexAlign.Center)
    .width('100%')
    .padding(10)
  }
}

// 新闻项数据类型
interface NewsItem {
  id: number;
  title: string;
  content: string;
  time: string;
}

// 自定义列表项卡片组件
@Component
struct NewsItemCard {
  @Prop item: NewsItem
  build() {
    Column() {
      Text(this.item.title).fontSize(16).fontWeight(FontWeight.Bold).margin({ bottom: 5 })
      Text(this.item.content).fontSize(14).fontColor('#666666').maxLines(2).textOverflow({ overflow: TextOverflow.Ellipsis })
      Text(this.item.time).fontSize(12).fontColor('#999999').margin({ top: 5 })
    }
    .padding(15)
    .width('100%')
    .backgroundColor(Color.White)
    .borderRadius(8)
    .margin({ top: 5, bottom: 5 })
  }
}

2. 关键逻辑说明

• 分页参数：pageNum（当前页码）、pageSize（页大小）、total（总数据量），通过接口返回更新。
• 状态锁：isRefreshing和isLoadingMore防止重复请求（如下拉时禁止上拉加载）。
• 数据追加：上拉加载成功后用[...this.newsList, ...list]合并新旧数据，避免直接修改原数组（确保UI刷新）。
• 边界判断：hasMore通过newsList.length < total判断是否还有数据，无更多时显示“没有更多数据了”。

八、运行结果与测试步骤​

1. 预期效果

• 下拉刷新：下拉列表显示刷新头，松手后顶部显示“加载中”，1秒后更新为最新10条数据（第1页）。
• 上拉加载：滚动到底部显示“加载中...”，1秒后追加下10条数据；加载完第3页（共25条）后显示“没有更多数据了”。
• 错误处理：断网时点击“重试”按钮重新加载。

2. 测试步骤

1. 基础功能测试：
   • 启动应用，自动加载第1页数据（10条）。
   • 下拉列表至阈值，松手触发刷新，观察数据是否重置为第1页。
   • 滚动到底部，触发加载更多，观察数据是否追加（第2页10条，第3页5条）。
2. 边界测试：
   • 加载完所有数据（25条）后，滚动到底部显示“没有更多数据了”。
   • 快速连续下拉/上拉，观察是否仅触发一次请求（状态锁生效）。
3. 异常测试：
   • 模拟网络错误（注释fetchNews的resolve，保留reject），观察是否显示错误提示及“重试”按钮。

九、部署场景​

十、疑难解答​

十一、未来展望与技术挑战​

1. 趋势

• 智能预加载：基于用户滚动速度预测，提前加载下一页数据（如滚动加速时预加载）。
• 分布式列表：跨设备同步列表滚动位置与加载状态（如手机加载后，平板自动同步数据）。
• AI优化排序：根据用户行为（点击、停留）动态调整列表项排序（如热门新闻置顶）。

2. 挑战

• 弱网体验：低带宽下加载超时、数据压缩（如Protobuf替代JSON）。
• 大数据性能：万级数据列表的渲染优化（虚拟滚动，仅渲染可见项）。
• 多端一致性：手机/平板/车机等多设备的分页参数与UI适配。

十二、总结​

1. 组件选型：用Refresh实现下拉刷新，List的onReachEnd实现上拉加载。
2. 状态管理：通过@State维护分页参数（pageNum、total）、加载状态（isRefreshing、isLoadingMore）。
3. 逻辑闭环：下拉刷新重置页码，上拉加载递增页码，通过isLoadingMore避免重复请求，hasMore控制加载终止。

• 加载状态可视化（loading动画、错误重试按钮）。
• 分页参数与服务端对齐（明确页码从1还是0开始）。
• 大数据列表结合虚拟滚动（如LazyForEach）优化性能。