跨平台开发 / 系统课时

接入页码分页接口

接入页码分页接口

页码分页的关键不是把 page 加一,而是让请求参数、已加载数据和“是否还有下一页”保持一致。本节用一个可运行的 Dart 示例建立分页状态,再说明如何把同一套状态接到真实 HTTP 接口。

学习目标

  • 用 page、pageSize 和 total 维护当前分页位置。
  • 在请求成功后安全更新页码,避免失败请求跳页。
  • 根据服务端返回结果判断 hasMore,阻止无意义的下一页请求。

先约定分页接口契约

假设接口接收 page 和 pageSize,响应同时返回当前页数据与总记录数。总数比“本页是否刚好等于 pageSize”更可靠,因为最后一页也可能恰好装满。

json
{
  "items": [
    {"id": 1, "name": "A"},
    {"id": 2, "name": "B"},
    {"id": 3, "name": "C"}
  ],
  "page": 1,
  "pageSize": 3,
  "total": 7
}

这类响应不需要单独的控制台输出。接入真实接口时,应先确认后端的页码是否从 0 还是 1 开始,以及 total 表示总记录数还是总页数。

用状态对象维护分页位置

分页控制器至少要保存已加载数据、当前成功页、页大小和 hasMore。页码只在请求成功后提交;如果第二页失败,当前页仍然保持为 1,下一次重试仍请求第二页。

下面的程序用内存数据模拟分页接口,因此无需额外依赖即可直接执行。把 fetchPage 替换成实际 HTTP 请求后,状态更新逻辑仍然相同。

dart
import 'dart:async';

class PageResult<T> {
  final List<T> items;
  final int page;
  final int pageSize;
  final int total;

  PageResult({
    required this.items,
    required this.page,
    required this.pageSize,
    required this.total,
  });
}

class PaginationController {
  final int pageSize;
  final List<String> items = [];
  int currentPage = 0;
  bool hasMore = true;
  bool isLoading = false;

  PaginationController({this.pageSize = 3});

  Future<void> loadNextPage() async {
    if (isLoading || !hasMore) return;

    isLoading = true;
    final nextPage = currentPage + 1;

    try {
      final result = await fetchPage(nextPage, pageSize);
      items.addAll(result.items);
      currentPage = result.page;
      hasMore = items.length < result.total;

      print(
        'page=$currentPage items=${items.length} hasMore=$hasMore data=$items',
      );
    } finally {
      isLoading = false;
    }
  }
}

Future<PageResult<String>> fetchPage(int page, int pageSize) async {
  const allItems = ['A', 'B', 'C', 'D', 'E', 'F', 'G'];
  await Future<void>.delayed(const Duration(milliseconds: 10));

  final start = (page - 1) * pageSize;
  if (start >= allItems.length) {
    return PageResult(
      items: const [],
      page: page,
      pageSize: pageSize,
      total: allItems.length,
    );
  }

  final end = start + pageSize > allItems.length
      ? allItems.length
      : start + pageSize;
  return PageResult(
    items: allItems.sublist(start, end),
    page: page,
    pageSize: pageSize,
    total: allItems.length,
  );
}

Future<void> main() async {
  final controller = PaginationController(pageSize: 3);
  await controller.loadNextPage();
  await controller.loadNextPage();
  await controller.loadNextPage();
  await controller.loadNextPage(); // hasMore 已为 false,不再发起请求
}

预期输出

text
page=1 items=3 hasMore=true data=[A, B, C]
page=2 items=6 hasMore=true data=[A, B, C, D, E, F]
page=3 items=7 hasMore=false data=[A, B, C, D, E, F, G]

最后一次调用不会产生输出,因为第三页成功后 hasMore 已变为 false。

替换为真实 HTTP 请求

片段示例:下面只展示 fetchPage 中构造分页 URL 的部分,依赖你项目已有的 HTTP 客户端和 JSON 解析代码。<HOST> 需要替换为实际服务地址。

dart
final uri = Uri.parse('https://<HOST>/items').replace(
  queryParameters: {
    'page': page.toString(),
    'pageSize': pageSize.toString(),
  },
);

// 使用项目中的 HTTP 客户端请求 uri,
// 再把响应映射为 PageResult<Item>。

验证时检查网络请求应分别带上 page=1&pageSize=3、page=2&pageSize=3 等参数;如果一次请求失败,不应提前把 currentPage 改成下一页。

刷新时重置整套分页状态

重新搜索、下拉刷新或切换筛选条件都代表一条新的分页序列。此时应先清空旧数据,把 currentPage 还原为 0,并把 hasMore 恢复为 true,再请求第一页。

不要在发送请求前执行 currentPage++。一旦网络失败,这种写法会让重试直接跳到更后的页,造成数据缺口。页码应代表“最后一个成功落地的页”,而不是“最后一次尝试请求的页”。

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

目录与阅读设置

阅读设置

17

记录一个想法

接入页码分页接口

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

登录哪都通