跨平台开发 / 系统课时

管理分页列表的加载状态

管理分页列表的加载状态

本篇解决分页列表中加载状态混乱的问题,将已有数据、下一页加载、没有更多数据和请求失败统一建模,让列表滚动加载时保持稳定行为。

学习目标

  • 设计分页列表需要维护的核心状态
  • 使用 Riverpod 管理分页请求和追加数据流程
  • 处理加载中、失败和无更多数据等边界情况

分页状态需要表达什么

普通异步请求只关心成功或失败,但分页列表需要同时保存已有数据和下一次请求状态。例如第一页加载完成后,用户继续滑动触发第二页请求,此时列表不能清空旧数据。

一个实用的分页状态通常包含当前数据列表、是否正在加载下一页、是否还有更多数据以及错误信息。

使用 AsyncNotifier 管理分页数据

下面示例使用 Riverpod 的 AsyncNotifier 保存分页列表。代码中的接口请求使用模拟数据,实际项目中替换为 HTTP 请求即可。

dart
import 'package:flutter_riverpod/flutter_riverpod.dart';

class PageState {
  final List<String> items;
  final bool hasMore;

  const PageState({required this.items, required this.hasMore});
}

class ProductPager extends AsyncNotifier<PageState> {
  @override
  Future<PageState> build() async {
    return _loadPage(1);
  }

  Future<void> loadNextPage() async {
    final current = state.value;
    if (current == null || !current.hasMore) return;

    // 保留已有列表,只更新加载过程中的状态。
    state = const AsyncLoading();
    final next = await _loadPage(2);
    state = AsyncData(PageState(
      items: [...current.items, ...next.items],
      hasMore: next.hasMore,
    ));
  }

  Future<PageState> _loadPage(int page) async {
    await Future.delayed(const Duration(milliseconds: 300));
    return PageState(
      items: ['item-$page'],
      hasMore: page < 3,
    );
  }
}

final productPagerProvider = AsyncNotifierProvider<ProductPager, PageState>(
  ProductPager.new,
);

预期输出

text
首次加载返回 item-1。
调用 loadNextPage 后列表追加 item-2,并继续保持分页状态。

处理分页失败和重复请求

实际项目中需要避免用户快速触发多次加载。请求开始前检查加载状态,并在异常时恢复已有数据,同时显示错误提示。

分页状态可以按下面方式区分:

状态 列表表现 用户操作
首次加载中 显示占位内容 等待请求完成
已有数据加载下一页 保留列表并显示底部加载 继续等待
加载失败 保留旧数据并提示错误 点击重试
没有更多数据 保持当前列表 不再请求

什么时候使用分页状态对象

如果页面只展示简单列表,可以直接使用 FutureProvider。需要连续加载、刷新、重试或缓存历史数据时,应该使用 AsyncNotifier 或类似状态模型,将列表数据和加载流程放在同一个状态管理层中。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

管理分页列表的加载状态

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通