ScrollablePositionedList.builder如何检测列表滚动到顶部/底部

ScrollablePositionedList 本身不提供传统ScrollController的像素偏移、atEdge这类属性，不需要强行找对应API，直接用你已经在使用的ItemPositionsListener返回的可见项位置数据，就能准确判断列表是否滚动到顶部/底部，逻辑比原生ScrollController的偏移判断更稳定。

判断原理 #

监听回调中拿到的itemPositions.value是当前所有可见列表项的ItemPosition集合，每个ItemPosition携带三个核心信息：项索引、项顶部相对视口的位置itemLeadingEdge、项底部相对视口的位置itemTrailingEdge。
两个边缘位置的取值是相对视口的比例：

• 0 对应视口的顶部边缘
• 1 对应视口的底部边缘
• 取值小于0代表项在视口顶部可视区域外，大于1代表项在视口底部可视区域外

基于这个规则，边界判断逻辑非常直接：

• 滚动到顶部：索引为0的首项，itemLeadingEdge ≥ 0，说明首项已经贴到视口顶部边缘
• 滚动到底部：索引为「列表总长度-1」的末项，itemTrailingEdge ≤ 1，说明末项已经贴到视口底部边缘

不要用「可见项包含首/末索引」直接判断边界：首项可能还在视口上方只露出极小部分，还没到滚动到顶的临界位置，判断会提前触发。

可直接复用的代码 #

// 初始化控制器和监听器
final ItemScrollController itemScrollController = ItemScrollController();
final ItemPositionsListener itemPositionsListener = ItemPositionsListener.create();

// 替换为你的列表实际总长度
final int totalItemCount = 100;

@override
void initState() {
  super.initState();
  itemPositionsListener.itemPositions.addListener(() {
    final visiblePositions = itemPositionsListener.itemPositions.value;

    // 顶部检测
    final reachTop = visiblePositions
        .where((pos) => pos.index == 0)
        .any((pos) => pos.itemLeadingEdge >= 0);

    // 底部检测
    final reachBottom = visiblePositions
        .where((pos) => pos.index == totalItemCount - 1)
        .any((pos) => pos.itemTrailingEdge <= 1);

    if (reachTop) {
      // 到顶逻辑，比如停止下拉刷新状态
      debugPrint('到达列表顶部');
    }

    if (reachBottom) {
      // 到底逻辑，比如触发分页加载更多
      debugPrint('到达列表底部');
    }
  });
}

@override
Widget build(BuildContext context) {
  return ScrollablePositionedList.builder(
    itemCount: totalItemCount,
    itemScrollController: itemScrollController,
    itemPositionsListener: itemPositionsListener,
    itemBuilder: (context, index) => ListTile(
      title: Text('列表项 $index'),
    ),
  );
}

补充说明 #

这个判断方式不受列表反向、视口padding、项动态高度的影响，比原生ScrollController计算像素偏移的方式兼容性更好。如果需要区分滚动到边界的方向，只需要加一个变量记录上一次的边界状态，前后对比就能判断是上滚到顶还是下滚到底。

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