自定义ScrollPhysics实现粘性过滚动：问题排查与优化

需求说明 #

• 允许过滚动（Overscroll），滚动到上下边界时屏幕需保留一个列表项
• 列表不回弹且滚动平滑
• 顶部过滚动时首项停留在视口底部，底部过滚动时末项停留在视口顶部

当前问题 #

已实现StickyOverscrollPhysics类，达成了平滑过滚动且不回弹的效果，但偶发以下Flutter错误：

FlutterError (StickyOverscrollPhysics.applyBoundaryConditions returned invalid overscroll value.
The method was called to consider a change from 139.94798592776687 to 175.10397097851407, which is a delta of 35.2 units. However, it returned an overscroll of 45.8 units, which has a greater magnitude than the delta. The applyBoundaryConditions method is only supposed to reduce the possible range of movement, not increase it.
The scroll extents are 0.0 .. 349.25714285714287, and the viewport dimension is 674.7428571428571.)

问题根源指向applyBoundaryConditions方法的实现不符合Flutter滚动物理规则。

原实现代码 #

class StickyOverscrollPhysics extends ScrollPhysics {
  final double itemHeight;
  final int itemLength;
  final double maxOverscrollExtent = 70.0; // Allow overscroll but limit it.

  const StickyOverscrollPhysics({
    required this.itemHeight,
    required this.itemLength,
    ScrollPhysics? parent,
  }) : super(parent: parent);

  @override
  StickyOverscrollPhysics applyTo(ScrollPhysics? ancestor) {
    return StickyOverscrollPhysics(
      itemHeight: itemHeight,
      itemLength: itemLength,
      parent: buildParent(ancestor),
    );
  }

  // Ensure one item remains visible at min/max boundaries.
  double _visibleBoundary(ScrollMetrics position) {
    return itemHeight;
  }

  @override
  double applyBoundaryConditions(ScrollMetrics position, double value) {
    print("<value $value>  <pixels ${position.pixels}>  <ExtentInside ${position.extentInside}>");
    // If scrolling past the upper limit.
    if ( position.extentInside < _visibleBoundary(position)+70) {//minScrollExtent=0.0  maxScrollExtent=157.257..
      return -1;
    }
    // If scrolling past the lower limit.
    if ( position.extentInside > _visibleBoundary(position)-70) {
      return 0;
    }
    return 0.0; // No boundary condition violation.
  }


  @override
  double applyPhysicsToUserOffset(ScrollMetrics position, double offset) {
    // Apply friction only beyond the scroll extents to make overscroll smooth.
    if (position.pixels < position.minScrollExtent ||
        position.pixels > position.maxScrollExtent) {
      final overscrollFraction = (offset.abs() / maxOverscrollExtent).clamp(0.0, 1.0);
      return offset * (1 - _overscrollFriction(overscrollFraction));
    }
    return offset; // Normal scrolling without friction.
  }

  double _overscrollFriction(double overscrollFraction) {
    return 0.05 + (0.85 * math.pow(overscrollFraction, 1.5));
  }

  @override
  Simulation? createBallisticSimulation(ScrollMetrics position, double velocity) {
    if (position.pixels < position.minScrollExtent ||
        position.pixels > position.maxScrollExtent) {
      return ClampingScrollSimulation(
        position: position.pixels,
        velocity: velocity,
        tolerance: Tolerance(
          velocity: 1.0 / (0.05 * WidgetsBinding.instance.window.devicePixelRatio),
        ),
      );
    }
    return super.createBallisticSimulation(position, velocity);
  }

  @override
  bool shouldAcceptUserOffset(ScrollMetrics position) => true;
}

修复方案 #

核心问题分析 #

applyBoundaryConditions方法的返回值违反Flutter规则：该方法只能返回缩小滚动范围的修正值，返回值的绝对值不能大于value - position.pixels的绝对值（即不能放大滚动偏移量）。原代码直接返回固定值-1或0，未基于滚动状态计算合理的边界修正值，同时边界判断逻辑错误，导致异常。

修正后的代码 #

import 'dart:math' as math;
import 'package:flutter/widgets.dart';

class StickyOverscrollPhysics extends ScrollPhysics {
  final double itemHeight;
  final int itemLength;
  final double maxOverscrollExtent = 70.0; // 限制最大过滚动距离

  const StickyOverscrollPhysics({
    required this.itemHeight,
    required this.itemLength,
    ScrollPhysics? parent,
  }) : super(parent: parent);

  @override
  StickyOverscrollPhysics applyTo(ScrollPhysics? ancestor) {
    return StickyOverscrollPhysics(
      itemHeight: itemHeight,
      itemLength: itemLength,
      parent: buildParent(ancestor),
    );
  }

  // 顶部过滚动时的最大允许位置：首项停留在视口底部
  double _getTopStickyPosition(ScrollMetrics position) {
    return - (position.viewportDimension - itemHeight);
  }

  // 底部过滚动时的最小允许位置：末项停留在视口顶部
  double _getBottomStickyPosition(ScrollMetrics position) {
    return position.maxScrollExtent + (position.viewportDimension - itemHeight);
  }

  @override
  double applyBoundaryConditions(ScrollMetrics position, double value) {
    // 限制顶部过滚动不超过粘性位置
    if (value < _getTopStickyPosition(position)) {
      return value - _getTopStickyPosition(position);
    }
    // 限制底部过滚动不超过粘性位置
    if (value > _getBottomStickyPosition(position)) {
      return value - _getBottomStickyPosition(position);
    }
    // 正常滚动范围，无边界限制
    return 0.0;
  }

  @override
  double applyPhysicsToUserOffset(ScrollMetrics position, double offset) {
    bool isOverscroll = position.pixels < position.minScrollExtent || position.pixels > position.maxScrollExtent;
    if (isOverscroll) {
      // 基于实际过滚动距离计算摩擦比例
      double overscrollAmount = position.pixels < position.minScrollExtent
          ? (position.minScrollExtent - position.pixels).abs()
          : (position.pixels - position.maxScrollExtent).abs();
      final overscrollFraction = (overscrollAmount / maxOverscrollExtent).clamp(0.0, 1.0);
      return offset * (1 - _overscrollFriction(overscrollFraction));
    }
    return offset; // 正常滚动无摩擦
  }

  double _overscrollFriction(double overscrollFraction) {
    return 0.05 + (0.85 * math.pow(overscrollFraction, 1.5));
  }

  @override
  Simulation? createBallisticSimulation(ScrollMetrics position, double velocity) {
    // 过滚动状态下保持不回弹
    if (position.pixels < position.minScrollExtent || position.pixels > position.maxScrollExtent) {
      return ClampingScrollSimulation(
        position: position.pixels,
        velocity: velocity,
        tolerance: Tolerance(
          velocity: 1.0 / (0.05 * WidgetsBinding.instance.window.devicePixelRatio),
        ),
      );
    }
    return super.createBallisticSimulation(position, velocity);
  }

  @override
  bool shouldAcceptUserOffset(ScrollMetrics position) => true;
}

关键修正点 #

1. 修复applyBoundaryConditions逻辑：

   • 计算准确的顶部/底部粘性位置，确保边界过滚动时列表项停留在指定位置
   • 返回的修正值为value - 边界位置，保证返回值绝对值不超过滚动偏移量的绝对值，符合Flutter规则

2. 优化过滚动摩擦计算：

   • 基于实际过滚动距离计算摩擦比例，而非偏移量，逻辑更合理

3. 移除无效判断：

   • 删除原代码中错误的extentInside判断，改用视口和滚动范围的准确计算

使用示例 #

在列表组件中应用该物理效果：

ListView.builder(
  physics: StickyOverscrollPhysics(
    itemHeight: 60.0, // 列表项高度
    itemLength: 20, // 列表项总数
  ),
  itemCount: 20,
  itemBuilder: (context, index) {
    return Container(
      height: 60.0,
      alignment: Alignment.center,
      child: Text('Item $index'),
    );
  },
)

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