Flutter中未知itemCount时异步加载ListView分页数据的解决方案

核心思路 #

放弃在itemBuilder里嵌套FutureBuilder的不合理方式，改用状态管理维护分页缓存与实时总数据量，通过滚动监听触发分页请求，每次请求同步更新服务器返回的最新总数据量，确保itemCount始终与服务器端一致，从根源避免越界问题。

具体实现步骤 #

1. 维护本地核心状态

   • 用Map<int, List<Transaction>>缓存已加载的分页数据，避免重复请求
   • 用变量存储当前最新的总数据量totalCount
   • 用ScrollController监听滚动位置，触发下一页加载
   • 用Set<int>记录已请求过的页码，防止重复发起请求

2. 初始加载逻辑

   • 页面初始化时先请求第一页数据，同时获取服务器返回的total值
   • 拿到数据后更新本地缓存、totalCount，并通过setState刷新列表，此时itemCount设为totalCount

3. 滚动加载与总数据量同步

   • 监听滚动事件，当滚动到列表底部（比如剩余item数量小于limit的1.5倍）时，触发下一页请求
   • 每次请求分页数据时，服务器会返回最新的total值，立即更新本地的totalCount并调用setState
   • 如果新的totalCount小于之前的数值，列表会自动调整长度，不会出现越界的index

4. 处理加载状态与边界情况

   • 若当前已加载的总数据量（已加载页数 * limit）小于totalCount，则在列表底部添加一个"加载中"的item（此时itemCount = totalCount + 1）
   • 当已加载总数据量 >= totalCount时，底部显示"暂无更多数据"
   • 在itemBuilder中，先判断index是否超出totalCount，如果是则返回底部提示组件；否则根据index计算对应的页码和本地缓存中的数据，返回item组件

代码示例 #

import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

class Transaction {
  final String id;
  final String amount;

  Transaction({required this.id, required this.amount});

  factory Transaction.fromJson(Map<String, dynamic> json) {
    return Transaction(
      id: json['id'],
      amount: json['amount'],
    );
  }
}

class TransactionList extends StatefulWidget {
  const TransactionList({super.key});

  @override
  State<TransactionList> createState() => _TransactionListState();
}

class _TransactionListState extends State<TransactionList> {
  final ScrollController _scrollController = ScrollController();
  final Map<int, List<Transaction>> _pageCache = {};
  final Set<int> _loadedPages = {};
  int _totalCount = 0;
  final int _limit = 100;
  bool _isLoading = false;

  @override
  void initState() {
    super.initState();
    _loadPage(1);
    _scrollController.addListener(_onScroll);
  }

  @override
  void dispose() {
    _scrollController.dispose();
    super.dispose();
  }

  Future<void> _loadPage(int page) async {
    if (_loadedPages.contains(page) || _isLoading) return;
    setState(() => _isLoading = true);

    try {
      final response = await http.get(
        Uri.parse('https://your-api-url/transactions?page=$page&limit=$_limit'),
      );
      final data = json.decode(response.body);
      final transactions = (data['transactions'] as List)
          .map((json) => Transaction.fromJson(json))
          .toList();
      final newTotal = data['pagination']['total'] as int;

      setState(() {
        _pageCache[page] = transactions;
        _loadedPages.add(page);
        _totalCount = newTotal;
        _isLoading = false;
      });
    } catch (e) {
      setState(() => _isLoading = false);
      // 这里可以添加错误提示逻辑，比如Toast
    }
  }

  void _onScroll() {
    final maxScroll = _scrollController.position.maxScrollExtent;
    final currentScroll = _scrollController.position.pixels;
    if (currentScroll >= maxScroll * 0.9 && !_isLoading) {
      final nextPage = _loadedPages.length + 1;
      final loadedTotal = _loadedPages.length * _limit;
      if (loadedTotal < _totalCount) {
        _loadPage(nextPage);
      }
    }
  }

  @override
  Widget build(BuildContext context) {
    if (_totalCount == 0 && !_isLoading) {
      return const Center(child: Text('暂无数据'));
    }

    final itemCount = _totalCount + (_isLoading || (_loadedPages.length * _limit < _totalCount) ? 1 : 0);

    return ListView.builder(
      controller: _scrollController,
      itemCount: itemCount,
      itemBuilder: (context, index) {
        if (index >= _totalCount) {
          // 底部加载提示
          return _isLoading
              ? const Padding(
                  padding: EdgeInsets.symmetric(vertical: 16),
                  child: Center(child: CircularProgressIndicator()),
                )
              : const Padding(
                  padding: EdgeInsets.symmetric(vertical: 16),
                  child: Center(child: Text('暂无更多数据')),
                );
        }

        // 计算当前index对应的页码和页内位置
        final page = (index ~/ _limit) + 1;
        final pageIndex = index % _limit;

        // 如果当前页未加载，触发加载（兜底逻辑）
        if (!_loadedPages.contains(page)) {
          _loadPage(page);
          return const Padding(
            padding: EdgeInsets.symmetric(vertical: 16),
            child: Center(child: CircularProgressIndicator()),
          );
        }

        final transaction = _pageCache[page]![pageIndex];
        return ListTile(
          title: Text('交易ID: ${transaction.id}'),
          subtitle: Text('金额: ${transaction.amount}'),
        );
      },
    );
  }
}

关键细节说明 #

• 实时同步总数据量：每次请求分页时都会拉取最新的total，确保itemCount始终与服务器一致，即使其他用户修改了数据，列表也会自动调整长度
• 兜底加载逻辑：如果用户快速滚动到未加载的页码，itemBuilder会触发对应页的加载，并显示加载指示器
• 避免重复请求：通过_loadedPages集合记录已加载的页码，同时在请求时加_isLoading锁，防止同一页被多次请求

内容的提问来源于stack exchange，提问作者Hans