跟🤡杰哥一起学Flutter (三十五、玩转Flutter滑动机制📱)

1. 引言

上节《三十四、玩转Flutter手势机制✋》扒完 Flutter 的 "手势机制 "，有点意犹未尽，那就趁热打铁，本节来把 "滑动机制" 也冲了 🔥

✨"滑动机制 " 的出现是为了解决 "有限区域 " 显示 "超量/无限内容" 的问题。

🤔 打个比方：

想象下你面前有一幅延绵百米的巨型壁画，你的眼睛一次只能看到笔画的一部分 (如正前方2米宽的区域)，这个"眼睛能看到的区域 " 可以称作你的 "视野窗口 (Viewport)"，当你左右移动身体，"视口" 也会随之移动，让你看到壁画的其它部分。

😶 贴近现实，现代数字内容的丰富性 (如长文本、图片列表、网页、数据表格等) 远超 屏幕的物理显示范围 ，此时，用户也需要一种 "移动视口 " 的方式，以访问被屏幕边缘遮挡的内容。💁‍♂️ "滑动机制 " 应运而生，其本质是通过 用户交互 (如手指拖动、鼠标滚轮、触控板手势) 改变内容在屏幕上的显示位置 (视口偏移 )，从而让用户逐步 "扫过" 超量内容。技术实现通常分为这三个部分：

• 内容容器与视口分离 ：将内容渲染在一个更大的 "虚拟画布" 中，屏幕仅显示其中一部分。
• 输入事件驱动偏移 ：用户通过 滑动手势 触发系统计算位移量，调整内容容器的位置 (如向上偏移100像素)，使得原本被遮挡的内容进入视口。
• 边界反馈：当内容已完全显示 (到达顶部/底部) 时，通过阻力反馈或动画提示用户"无更多内容"。

😄 而在 Flutter 中，视口 (Viewport) 的概念不在局限于屏幕级别的显示区域，而是扩展到任意一个 "构建其可视范围内子项的可滚动区域 "。为此，Flutter 设计了一套 "滑动处理机制"，其中的重要参与者：

Scrollable -专注交互，监听手势并驱动滚动、Viewport -管理并提供可见视口，Slivers-提供内容，在Viewport按需渲染自己的一部分。

这种清晰的职责划分 (分层设计) 使得 Flutter 在实现无限列表、复杂联动特效时，仍能够保持出色的性能与强大的灵活性。

😏 本节就来系统学习下 Flutter 的这套 "滑动机制 "，依旧是 "概念名词+API详解+源码剖析" 的叙述套路~

2. 三大核心构件

💡 这部分涉及到比较多的 API，可以选择性阅读 (跳着看)，大概知道是都是干嘛的，用到再查也可以。🤔对 "Sliver协议的工作流程" 建立一个基础认知，在后面分析各种具体滚动视图时会更加得心应手。

2.1. Scrollable - 滑动控制器

所有 可滚动组件 的 "基石 "，作用是将 "用户的输入 (手势) 转化为滚动的视觉变化"，具体功能：

• 手势识别 ：通过内置的 RawGestureDetector，识别垂直或水平方向的拖拽手势。
• 滚动物理模拟 ：通过 ScrollPhysics ，定义了滚动的 "感觉"，比如：滚动到边缘时的效果 (Android-蓝色辉光-ClampingScrollPhysics、iOS-回弹-BouncingScrollPhysics)、滑动停止时的惯性动画 (Fling)。
• 状态管理 ：管理滚动的核心状态，如：当前滚动位置 (pixel)、滚动范围 (min/max scroll extent)。这个状态由一个叫做 ScrollPosition 的对象维护。
• 外部控制接口 ：通过 ScrollController，允许开发者从外部读取滚动位置、监听滚动事件或命令式地控制滚动 (如跳转到指定位置、执行动画)。
• 构建视口 ：Scrollable 本身不渲染任何可滚动的内容。它通过一个名为 viewportBuilder 的回调函数，将滚动的能力 (ViewportOffset) "嫁接" 给一个负责渲染部分内容的 Viewport 组件。

2.1.1. 属性/方法

构造方法：

class Scrollable extends StatefulWidget {
  const Scrollable({
    super.key,
    this.axisDirection = AxisDirection.down,        // 滚动方向
    this.controller,                                // 滚动控制器
    this.physics,                                   // 滚动物理效果
    required this.viewportBuilder,                  // 视口构建器（必需）
    this.incrementCalculator,                       // 增量计算器，
    this.excludeFromSemantics = false,             // 是否在语义树 (用于辅助功能，如屏幕阅读器) 中可见。
    this.semanticChildCount,                        // 向辅助功能提供一个提示，告知总共有多少个子项。
    this.dragStartBehavior = DragStartBehavior.start, // 拖拽开始行为
    this.restorationId,                            // 恢复ID
    this.scrollBehavior,                           // 滚动行为
    this.clipBehavior = Clip.hardEdge,             // 裁剪行为
  })
}

参数详解：

① axisDirection ：AxisDirection

定义了【滚动轴的方向】& ScrollPosition 的 pixel 为 0 时，内容所处的位置，可选值：

• down：垂直方向，内容从上到下排列 (0.0在顶部)
• up：垂直方向，内容从下到上排列 (0.0在底部)
• right:：水平方向，内容从左到右排列 (0.0在左侧)
• left：水平方向，内容从右到左排列 (0.0在右侧)

---

② physics ：ScrollPhysics?

定义了【组件滚动时的物理特性 】，决定了滚动时的"手感"，如果为null，Scrollable 会通过 ScrollConfiguration.of(context) 获取一个平台默认的 ScrollPhysics 。Android 上是ClampingScrollPhysics (边界钳制，有辉光)，在 iOS 上是 BouncingScrollPhysics (边界回弹)。常见的还有：NeverScrollableScrollPhysics (禁止滚动)、AlwaysScrollableScrollPhysics (内容不足一屏也可滚动)。

③ incrementCalculator ：ScrollIncrementCalculator?

用于计算非指针（如键盘箭头、鼠标滚轮）滚动事件的滚动增量。通常无需关注此参数，框架有默认实现，在需要自定义键盘/滚轮滚动行为时才使用。

④ dragStartBehavior ：DragStartBehavior

定义了【拖拽开始行为】决定滚动操作何时开始被识别。

• start：默认值，用户的手指按下并移动了一段微小的距离后才会被识别为滚动开始。
• down：用户手指按下并开始移动的瞬间就被立即识别为滚动，除非有极致及时反馈的交互时才设置，否则建议还是保持默认，以保证最佳和最符合预期的用户体验。

⑤ clipBehavior ：Clip

定义了【如何对超出边界的内容进行裁剪】，可选值：

• hardEdge：默认，以最快的方式裁剪掉超出边界的内容。裁剪的边缘是硬的，可能会有锯齿，但GPU负载最低，性能最好，特别适合滚动视图是矩形且没特殊视觉效果的场景。
• antiAlias：裁剪内容，并对裁剪的边缘进行抗锯齿处理，使其看起来更平滑。视觉效果更好，特别是当滚动视图有圆角时，可以避免边缘的锯齿感。性能开销比 hardEdge 稍高。
• antiAliasWithSaveLayer：使用最高质量的抗锯齿裁剪，但也是性能开销最大的。它会创建一个临时的离屏缓冲区 (save layer) 来执行裁剪操作。能处理复杂的裁剪场景，提供最平滑、最准确的视觉效果。但严重影响性能。只有当Clip.antiAlias 仍然出现视觉问题 (如复杂的透明度和变换组合下) 时，才作为最后的手段使用。
• none: 完全不裁剪，内容可以绘制到滚动视图的边界之外。 性能最差，因为它可能需要绘制更多内容，而且，溢出的内容可以会覆盖页面上其它UI元素，导致混乱的视觉布局。

⑥ restorationId ：String?

用于【为滚动视图提供一个唯一的ID 】以便在应用被系统杀死并恢复后，能够自动恢复其滚动位置。属于 Flutter 状态恢复 (State Restoration) 框架的一部分。应用场景：包含长内容页面 (如文章)，当应用被挂起时 RestorationManager 会找到所有带 restorationId 的 Widget，并向它们请求需要保存的数据，(对于滚动视图，就是当前的 scrollOffset )。这些数据被保存到系统中，当应用恢复时，RestorationManager 会找到具体相同 restorationId 的Widget，并将保存的数据交还给它，使其能够恢复到之前的状态 (即滚动到之前的位置)。

⑦ viewportBuilder ：ViewportBuilder

这是 ViewportBuilder 的定义代码：

typedef ViewportBuilder = Widget Function(BuildContext context, ViewportOffset position);

这个参数是【构建Viewport的回调 】，Scrollable.build() 时会创建一个 ViewportOffset 对象 (实际上是 ScrollPosition 的实例)，并将其作为 参数 传递到这个回调中，回调执行后返回 Viewport 或其它自定义组件，需要通过这个 position 参数来决定其它子组件 (通常是 Sliver) 的布局偏移。

⑧ controller ：ScrollController?

可选的【外部滚动控制器 】继承 ChangeNotifier ，可以通过它来监听滚动位置、驱动滚动。多个 Scrollable 还可以共享 同一个 controller 来实现同步滚动效果。不传这个参数 (null )，Scrollable 会在内部自动创建一个 ScrollController ，如果自己创建了 ScrollController ，记得在 State 的 dispose() 中销毁它。它的构造函数：

class ScrollController extends ChangeNotifier {
    ScrollController({
      double initialScrollOffset = 0.0,	// 初始滚动偏移量，默认为 0.0
      this.keepScrollOffset = true,
      this.debugLabel,
      this.onAttach,
      this.onDetach,
  })
}

typedef ScrollControllerCallback = void Function(ScrollPosition position);

参数详解：

• keepScrollOffset ：是否使用 PageStorage 保存滚动位置，默认true, 当 ScrollController 被附加到多个滚动视图时非常有用，它决定了控制器是否应该在切换附加对象时，尝试保持当前的 scrollOffset。
• onAttach ：ScrollControllerCallback? ，当一个 ScrollPosition 被附加到 ScrollController 时会触发这个回调，可在回调中可以获得刚附加的 ScrollPosition对象，进行一些初始化操作或记录。
• onDetach：ScrollControllerCallback? ，当一个 ScrollPosition 从 ScrollController 中分离时会触发这个回调。可在回调中可以获得即将被分离的 ScrollPosition对象，进行一些清理或记录。

属性/方法：

// 当前附加的所有 ScrollPosition 对象
Iterable<ScrollPosition> get positions => _positions;

// 是否有附加的滚动视图
bool get hasClients => _positions.isNotEmpty;

// 获取唯一的 ScrollPosition（仅在单个视图时使用）
ScrollPosition get position {return _positions.single}

// 当前滚动偏移量 (滚了多少像素)
double get offset => position.pixels;

// ✨ 滚动控制方法
// 动画滚动到指定位置，参数：偏移量、动画时长和曲线
// 顶部 (position为0)，底部 (最大滚动距离-_scrollController.position.maxScrollExtent)
Future<void> animateTo(double offset, {
  required Duration duration,
  required Curve curve,
});

// 立即跳转到指定位置 (没有动画效果)
void jumpTo(double value);

// ✨ 添加滚动监听
_scrollController.addListener(() {
  print('offset: ${_scrollController.position.pixels}');
});

💡 注：要精确地判断滑动状态，推荐使用 NotificationListener ，它比 ScrollController 的 addListener 提供了更丰富、更具体的事件信息，如滚动停止。另外，上拉加载更多 (滑动到底部，用户还往上拉)，常见的错误做法：在 addListener 里判断 position.pixels == position.maxScrollExtent ，这只在到达底部时触发一次，而不是在到达底部后继续拉动时触发。正确的做法是：监听 OverscrollNotification ，当用户试图滚动超过 maxScrollExtent 时，就会触发这个通知。

ScrollController 内部维护了一个 ScrollPosition 列表 _positions ，ScrollPosition 存储了 "单个滚动视图 " 的 "状态信息 & 控制逻辑"。

abstract class ScrollPosition extends ViewportOffset with ScrollMetrics {
  required this.physics,         // 滚动的物理模拟效果
  required this.context,         // 滚动上下文
  this.keepScrollOffset = true,  // 是否通过 PageStorage 保存和恢复滚动位置
  ScrollPosition? oldPosition,   // 用于在 Widget 重建时迁移状态
  String? debugLabel,            // 调试标签
}

参数详解：

• context ：ScrollContext ，充当 Scrollable 和 ScrollPosition 间的桥梁，为滚动操作提供必要的 上下文信息 。包括：分发ScrollNotification -notificationContext、搜索PageStorage -storageContext、动画支持 -vsync、滚动方向 -axisDirection、设备像素比 -devicePixelRatio。除此之外，还提供了交互控制相关的方法：是否忽略指针事件 -setIgnorePointer()、是否可以拖拽 -setCanDrag()、setPixels (double offset)-当 ScrollPosition 内部的 pixels 值改变时，用它来通知 Viewport 更新其偏移量，从而真正移动视图。
• oldPosition ：ScrollPosition? ，当 Scrollable 的配置发生变化 (如ScrollController 或 ScrollPhysics 被替换) 时，ScrollableState 会创建一个新的 ScrollPosition，oldPosition 参数允许新 Position 从 旧 Position "吸收(absorb) " 状态，如当前的 pixels值，从而实现平滑过渡。

属性/方法：

// ================ 🔔 存储滚动核心数据 ================ 
double pixels: 最核心的属性。表示当前滚动位置距离滚动起点的偏移量（逻辑像素）。
double minScrollExtent: 最小滚动范围。通常是 0.0。
double maxScrollExtent: 最大滚动范围。它由 (内容总高度 - 视口高度) 计算得出。
double viewportDimension: 视口（可见区域）在滚动轴上的尺寸。例如，对于一个垂直滚动的 ListView，这就是它的高度。
double extentBefore: 在视口之前（上方或左方）的不可见区域的长度。等于 pixels - minScrollExtent。
double extentInside: 在视口内部的区域长度，就是 viewportDimension。
double extentAfter: 在视口之后（下方或右方）的不可见区域的长度。
bool outOfRange: 当前 pixels 是否超出了 minScrollExtent 和 maxScrollExtent 的范围。
bool atEdge: 当前 pixels 是否正好等于 minScrollExtent 或 maxScrollExtent。
  
Axis axis: 滚动的轴（Axis.vertical 或 Axis.horizontal）。
- ScrollDirection userScrollDirection: 用户最近一次的滚动方向。有四个值：
- ScrollDirection.idle: 静止。
- ScrollDirection.forward: 向前滚动（例如，在垂直列表中向上滚动，内容向下移动）。
- ScrollDirection.reverse: 向后滚动（例如，在垂直列表中向下滚动，内容向上移动）。
- 这个属性对于实现"滚动时隐藏/显示AppBar或FAB"等效果至关重要。

ScrollActivity activity: 内部状态机。表示当前滚动正在进行的"活动"。它是一个抽象类，常见的实现有：
- IdleScrollActivity: 静止状态。
- DragScrollActivity: 用户手指按住并拖动时的活动。
- BallisticScrollActivity: 用户手指抬起后，列表根据速度进行惯性滚动的活动。

// ================ 🎪 核心滚动操作 ================ 
jumpTo(double value): 瞬间将滚动位置改变到指定值，不带动画。
animateTo(double to, ...): 以动画方式将滚动位置平滑移动到指定值。
moveTo(double to, ...): jumpTo 和 animateTo 的内部实现，负责应用新的像素值。
correctBy(double correction): 当滚动位置不正确时（例如，子元素增删导致 maxScrollExtent 变化），用于修正 pixels。
applyNewDimensions(): 当视口或内容尺寸变化时，被调用来更新 min/maxScrollExtent 等维度信息，并可能修正 pixels。

// ================ 🎪 驱动滚动物理和动画 ================ 
它内部持有一个 ScrollPhysics 对象，用于决定滚动的物理行为（如在滚动到边缘时是阻尼效果还是回弹效果）。
它使用 Ticker 来驱动滚动动画，如用户手指离开屏幕后的惯性滚动（Fling/Ballistic）。
它定义了如 goIdle()、goBallistic(double velocity) 等方法来控制滚动的动态行为。

// ================ 🎪 通知机制 ================ 
// 它继承自 ChangeNotifier，当 pixels 发生变化时，
// 会调用 notifyListeners()。ScrollController 就是通过监听这个通知来得知滚动位置的变化。
// 它负责向上冒泡派发 ScrollNotification
// (如 ScrollStartNotification, ScrollUpdateNotification, ScrollEndNotification 等)，
// 让父组件（如 NotificationListener）可以监听到滚动事件。
  
// 💡 可以调用 controller.positions 属性来访问这个ScrollPosition列表
// 当控制器只附加到一个滚动视图上时，你可以直接调用 controller.offset 来获取ScrollPosition对象
// 实际上返回的：controller.position.pixels。

Scrollable 里还有一个 scrollBehavior 属性，也顺带提一嘴。ScrollBehavior 用于【统一整个App或子树中所有滚动组件的默认行为 】。当一个 可滚动的Widget 被创建时，它会调用 ScrollConfiguration.of() 向上查找离它最近的 ScrollConfiguration ，并返回其 behavior 对象，Scrollable 根据它来配置自己的滚动物理效果、滚动条演示、越界指示器、指针设备交互等。构造方法：

// 构造方法，没有任何参数，创建的是一个不可变(immutable)的对象。
ScrollBehavior copyWith({
  bool? scrollbars,           // 是否显示滚动条
  bool? overscroll,          // 是否显示过度滚动效果
  Set<PointerDeviceKind>? dragDevices,        // 支持拖拽的设备类型
  MultitouchDragStrategy? multitouchDragStrategy,  // 多点触控策略
  Set<LogicalKeyboardKey>? pointerAxisModifiers,   // 滚动轴修饰键
  ScrollPhysics? physics,     // 滚动物理特性
  TargetPlatform? platform,   // 目标平台
})

2.1.2. ScrollableState

Scrollable 的核心逻辑都在 ScrollableState 中，内部维护一个 ScrollPosition 类型的 _position 属性，所有对滚动的操作，最终都作用于这个属性。ScrollPosition 是抽象类，在 ScrollableState 里的具体实现是 ScrollPositionWithSingleContext，核心实现：

• 与 Scrollable 建立连接 ："Single Context " 指的是它持有一个 "ScrollableState" 引用，通过它可以获取到：ScrollPhysics、BuildContext、TickerProvider 及 axisDirection。
• 与 Viewport 通信：applyNewDimensions() 的具体实现就是通过 ScrollableState 找到对应的 Viewport，并从 Viewport 获取 minScrollExtent/maxScrollExtent，这是 ScrollPosition 获得滚动范围信息的关键。
• 处理用户输入 ：实现了 beginActivity() 和 applyUserOffset() 等方法，当用户在 Scrollable 上拖动时，Scrollable 会将 拖动偏移量(delta) 传递给 applyUserOffset ，然后 ScrollPositionWithSingleContext 会根据 ScrollPhysics 的规则更新 pixels 。并且在用户开始拖动时会创建一个 DragScrollActivity 来响应用手操作。当用户松开手指时，调用 goBallistic() 来启动一个 BallisticScrollActivity，实现惯性滚动。
• 管理生命周期 ：当一个 ScrollController 被附加到 Scrollable 上时，ScrollableState 会调用 attach() ，将自己作为参数传递给 ScrollPosition，从而完成绑定，解绑时则调用 death()。

ScrollPositionWithSingleContext 是实际工作的 滚动引擎 ，连接 ScrollController的意图 和 Scrollable视图表现 的桥梁与执行者。ScrollableState 的核心方法如下：

class ScrollableState extends State<Scrollable> with , RestorationMixin
    implements ScrollContext {
  
      // 类似于 Theme.of(context)。它允许子组件沿着组件树向上查找到最近的 ScrollableState 实例
      static ScrollableState? of(BuildContext context):

      // 手势识别器 (DragGestureRecognizer) 的回调，当手势发生时，这些方法被调用，然后它们会调用
      // position.drag() 和 position.dragEnd()，将手势的细节传递给 ScrollPosition。
      _handleDragStart, _handleDragUpdate, _handleDragEnd

      // 用户如果没提供controller，创建一个备用的ScrollController实例
      initState()

      // 调 _updatePosition() → controller.createScrollPosition() 创建
      // ScrollPositionWithSingleContext 实例。controller.attach(position)。
      didChangeDependencies()

      // 构建Viewport
      Widget build(BuildContext context){
        // 套_ScrollableScope (继承InheritedWidget，便于实现 Scrollable.of() 查找 ScrollableState)
        Widget result = _ScrollableScope(          
          scrollable: this,
          position: position,
          // 套Listener-监听指针信号、套 RawGestureDetector-手势识别
          child: Listener(                         
            onPointerSignal: _receivedPointerSignal,
            child: RawGestureDetector(             
              gestures: _gestureRecognizers,
              child: Semantics(
                // 套IgnorePointer-忽略指针事件让其直接穿透到下层
                child: IgnorePointer(              
                  ignoring: _shouldIgnorePointer,
                  child: widget.viewportBuilder(context, position), // ✨ 实际内容视口
                ),
              ),
            ),
          ),
        );
        result = _buildChrome(context, result);  // 添加滚动条、过度滚动指示器等
        ...
      }
}

😄 在 ScrollableState.build() 中调用了 Scrollable 构造方法中传入的 viewportBuilder 回调，在创建 Viewport Widget 的同时传入了 position ，使得 Viewport 可以根据 position.pixels 来计算子元素的偏移量，从而实现滚动效果。梳理下方法调用的流程，先是 初始化 (选择 ScrollController → 配置 Physics → 处理 ScrollPostion)：

Widget 创建
    ↓
ScrollableState.initState()
    ↓
检查 widget.controller
    ├─ 如果为 null → 创建 _fallbackScrollController = ScrollController()  // 第629行
    └─ 如果不为 null → 使用提供的 controller
    ↓
super.initState()
    ↓
didChangeDependencies()
    ↓
获取 MediaQuery 设置和设备像素比
    ↓
_updatePosition()
    ↓
获取 ScrollConfiguration 和基础 ScrollPhysics
    ↓
检查自定义 physics
    ├─ 有 widget.physics → _physics = widget.physics!.applyTo(_physics)
    ├─ 有 widget.scrollBehavior → 应用 scrollBehavior 的 physics
    └─ 都没有 → 使用默认 physics
    ↓
检查旧的 _position
    ├─ 存在旧 position → detach 旧 position → scheduleMicrotask 销毁
    └─ 不存在 → 直接进入下一步
    ↓
_effectiveScrollController.createScrollPosition(_physics!, this, oldPosition)
    ↓
_effectiveScrollController.attach(position)
    ↓
初始化完成 ✅

用户手指拖动事件 (状态转换：空闲→Hold→Drag→结束，正常结束-可能惯性滚动、取消操作-立即停止)

用户手指按下屏幕
    ↓
GestureDetector 识别触摸事件
    ↓
_handleDragDown()
    ↓
状态检查 assert(_drag == null && _hold == null)
    ↓
_hold = position.hold(_disposeHold)  // 创建保持控制器
    ↓
停止当前滚动动画
    ↓
用户开始移动手指
    ↓
_handleDragStart()
    ↓
状态检查
    ├─ _hold 可能为 null（用户代码触发了其他活动）→ 直接返回
    └─ _hold 存在 → 继续处理
    ↓
_drag = position.drag(details, _disposeDrag)
    ↓
_hold 自动变为 null（转换为拖拽状态）
    ↓
用户继续拖拽移动
    ↓
_handleDragUpdate() (持续调用)
    ↓
状态检查
    ├─ _drag 为 null（拖拽已结束）→ 不处理
    └─ _drag 存在 → _drag.update(details)
    ↓
ScrollPosition.setPixels()
    ↓
应用 ScrollPhysics 约束
    ↓
更新滚动位置 + 发送 ScrollNotification
    ↓
触发 UI 重建
    ↓
检查用户操作
    ├─ 继续拖拽 → 回到 _handleDragUpdate()
    ├─ 松开手指 → _handleDragEnd()
    └─ 取消操作 → _handleDragCancel()

松开手指分支：
_handleDragEnd()
    ↓
状态检查
    ├─ _drag 为 null → 不处理
    └─ _drag 存在 → _drag.end(details)
    ↓
根据结束速度判断
    ├─ 速度足够大 → 开始惯性滚动 (BallisticScrollActivity)
    └─ 速度不够 → 停止滚动 (IdleScrollActivity)
    ↓
_drag 变为 null
    ↓
拖拽流程完成 ✅

取消操作分支：
_handleDragCancel()
    ↓
检查 _gestureDetectorKey.currentContext
    ├─ 为 null（组件被销毁）→ 直接返回
    └─ 存在 → 继续处理
    ↓
清理状态
    ├─ _hold?.cancel() → _hold = null
    └─ _drag?.cancel() → _drag = null
    ↓
取消流程完成 ✅

数据流向：

用户手指拖动
    ↓
DragUpdateDetails.delta (比如: Offset(0, -10))
    ↓
ScrollDragController.update()
    ↓
ScrollPosition.setPixels(oldPixels + delta)
    ↓
position.pixels 变化 (100.0 → 90.0)
    ↓
didUpdateScrollPositionBy(-10.0)
    ↓
dispatchScrollStartedNotification 发送通知
    ↓
notifyListeners 通知监听器，ViewportOffset 继承自 ChangeNotifier
    ↓
┌─────────────────────┬─────────────────────┬─────────────────────┐
│   Viewport重新布局  	│   Scrollbar更新位置 	│   子组件可见性变化   │
└─────────────────────┴─────────────────────┴─────────────────────┘
    ↓                     ↓                     ↓
RenderSliver计算可见范围   滚动条thumb位置更新     Widget build/dispose
    ↓                     ↓                     ↓
子组件的renderObject更新   滚动条重绘             新的UI呈现给用户

2.2. Sliver - 滑动片段

"Sliver" 不是具体的类，而是一个协议/概念，它是 RenderSliver 和它的容器 (通常是 RenderViewport ) 间沟通的方式。这个协议主要由 两个核心数据结构 + performLayout() 构成。

2.2.1. 输入-SliverConstraints

RenderViewport (滚动视口) 传递给 RenderSliver 的 "布局约束信息 "。它告诉 Sliver："这是你当前所处的环境，请根据这些信息结算你的布局"。SliverConstraints 的关键属性：

// ================ 🔄 滚动相关 ================

// 当前滚动偏移量，Sliver 根据它来判断自己哪一部分是可见的。
final double scrollOffset;

// 前面所有 Sliver 消耗的滚动距离总和。用于计算当前 Sliver 在整个可滚动区域中的起始位置。
final double precedingScrollExtent;  

// 剩余可绘制的像素数量。Sliver 应该根据这个值来决定绘制多少内容，不应该超过这个限制
final double remainingPaintExtent; 

// 前一个 Sliver 重叠的像素数量，当前一个 Sliver 的 paintExtent > layoutExtent 时
// 会产生重叠，通常用于固定头部等效果。如：SliverAppBar 收起时会与列表重叠
final double overlap;

// ================ 🎯 视口和缓存相关 ================

// 视口在主轴方向上的像素数量，对垂直列表来说，就是视口的高度。
final double viewportMainAxisExtent;

// 缓存区域的起始位置，相对于 scrollOffset。总是负数或零，
// 表示需要在当前可见区域之前预渲染多少内容。
final double cacheOrigin;

// 剩余缓存区域的大小。Sliver 应该从 cacheOrigin 开始，
// 尽可能提供 remainingCacheExtent 范围内的内容以优化滚动性能。
final double remainingCacheExtent;

// ================ 🧭 坐标系统信息 ================

// 滚动方向，决定了 scrollOffset 和 remainingPaintExtent 的增长方向
final AxisDirection axisDirection;  

// Sliver 内容的排列方向，相对于 axisDirection 而言，forward-相同，reverse反向
final GrowthDirection growthDirection;  

// 用户滚动的方向，用于判断用户是在向前滚动还是向后滚动，某些Sliver(如浮动头部)会根据此信息调整行为
final ScrollDirection userScrollDirection; 

// 交叉轴的可用空间。对于垂直列表来说就是宽度，对于水平列表来说就是高度。
final double crossAxisExtent;

// 交叉轴的方向。通常用于垂直列表中描述文字方向是从左到右还是从右到左。
final AxisDirection crossAxisDirection; 

2.2.2. 输出-SliverGeometry

当 RenderSliver 的 performLayout() 被调用后，它必须计算并设置自己的 geometry 属性，这是它返回给 RenderViewport 的 "布局结果 "。SliverGeometry 的关键属性：

class SliverGeometry {
  // ================ 🎨 核心尺寸信息 ================

  // Sliver 总的可滚动范围，表示用户需要滚动多少距离才能从这个 Sliver 的开始滚动到结束。
  final double scrollExtent;

  // 当前实际绘制的像素范围，表示这个 Sliver 在当前滚动位置下实际占用的可见区域大小。
  final double paintExtent;

  // 布局占用的空间大小，决定下一个 Sliver 的布局位置，默认等于 paintExtent。
  // 当需要 "挤压"后续 Sliver 时会小于 paintExtent。
  final double layoutExtent;

  // 该 Sliver 能够绘制的最大范围。用于支持收缩包装的视口，
  表示如果有无限空间时这个 Sliver 最多能绘制多大。
  final double maxPaintExtent;

  // 当 Sliver 被固定在边缘时，能够阻挡内容滚动的最大范围，应用栏就是最典型的例子。
  final double maxScrollObstructionExtent;
  
  // ================ 📦 位置和交互信息 ================

  // 交叉轴占用的空间大小，如果为null，则使用约束中的 crossAxisExtent。
  // 用于某些需要自定义交叉轴大小的 Sliver。
  final double crossAxisExtent;
  
  // 绘制起始位置的偏移量，如果 Sliver 想要在其布局位置之前开始绘制 
  // (如阴影效果)，这个值就是负数
  final double paintOrigin;

  // 可以响应点击事件的范围，默认等于 paintExtent，但某些情况下
  // 可能需要扩大或缩小点击区域。
  final double hitTestExtent;

  // 缓存区域消耗的大小。表示这个 Sliver 从剩余缓存区域中消耗了多少空间，用于优化滚动性能。
  final double cacheExtent;
  
  // ================ 🔧 状态信息 ================

  // 该 Sliver 是否应该被绘制。默认情况下，paintExtent > 0 时为 true，否则为 false。
  final bool visible;

  // 是否有视觉溢出。如果为 true，视口需要对子组件进行裁剪以避免内容溢出到视口边界之外。
  final bool hasVisualOverflow;

  // 滚动偏移修正值。如果不为 null，父组件会调整滚动位置并重新布局。
  // 用于处理滚动位置需要修正的特殊情况。
  final double? scrollOffsetCorrection;
}

2.2.3. 协议流程总结

• RenderViewport 调 子RenderSliver.layout() ，并传入 SliverConstraints (输入)。
• RenderSliver.performLayout() 被触发，RenderSliver 的具体子类 (如RenderSliverList) 会根据 SliverConstraints 计算出自己需要展示哪些子元素、它们的位置，并最终计算出一个 SliverGeometry (输出)。
• RenderSliver 将计算好的 SliverGeometry 赋值给自己的 geometry 属性。
• RenderViewport 读取 geometry，从而知道这个 Sliver 占了多少空间、下一个 Sliver 应该从哪里开始布局等信息，然后继续布局下一个 Sliver。

RenderSliver子类.performLayout() 中进行 布局计算 的示例代码：

void performLayout() {
  // 1. 接收约束
  final SliverConstraints constraints = this.constraints;
  
  // 2. 分析滚动状态
  final double scrollOffset = constraints.scrollOffset;
  final double remainingExtent = constraints.remainingPaintExtent;
  
  // 3. 计算内容布局
  // ... 具体的布局逻辑 ...
  
  // 4. 生成几何信息
  geometry = SliverGeometry(
    scrollExtent: totalContentHeight,      // 总内容高度
    paintExtent: visibleContentHeight,     // 可见内容高度
    layoutExtent: layoutContentHeight,     // 布局影响高度
    maxPaintExtent: maxContentHeight,      // 最大绘制高度
    hasVisualOverflow: hasOverflow,        // 是否溢出
  );
}

梳理下 RenderSliver 的子类们：

💡 Tips ：Sliver 组件们：ListView → SliverList 、GridView → SliverGrid 、SliverToBoxAdapter (用于将一个普通Box组件进行Sliver适配)、SliverAppBar 、SliverPersistentHeader (吸顶头部)、SliverFillRemaining (填充视口剩余空间)、SliverPadding (为Sliver添加内边距)、SliverLayoutBuilder (可以根据 Sliver 的几何信息来构建其子组件) 等。

2.3. Viewport - 视口管理器

继承 MultiChildRenderObjectWidget (多子Widget)，实现 "懒加载/按需渲染" 滚动视图的基石，主要职责：

• 管理可见区域显示 ：根据自身尺寸和给定的偏移量显示子组件的子集，只渲染在视口范围内可见的 Sliver子组件，而不是全部内容。
• 协调滚动偏移 ：接收并处理 ViewportOffset 传递的滚动偏移量信息，随着偏移量的变化，动态调整哪些子组件在视口中可见。
• 实现高效的布局算法 ：采用视口感知的布局协议，向 Sliver子组件 传递约束信息，包含可见空间剩余量等视口相关信息，使子组件能够智能地决定渲染内容。
• 支持无限滚动机制：通过按需构建机制，只创建当前可见的 Widget，在布局阶段与构建阶段交错进行，实现高性能的无限列表。
• 处理不同类型的 Sliver 组合 ：统一管理线性列表、网格、可折叠头部等不同类型的 Sliver，通过 Sliver布局协议 协调各种滚动效果，如视差滚动、折叠头部等。
• 维护渲染边界和裁剪：定义内容的可视边界，对超出视口的内容进行裁剪，管理重绘边界，优化渲染性能。

构造函数：

Viewport({
  super.key,
  this.axisDirection = AxisDirection.down,	// 主轴方向，决定了滚动的方向和布局的起点。
  this.crossAxisDirection,	// 交叉轴方向，它会影响子项在交叉轴上的布局顺序。
  this.anchor = 0.0,	// 锚点
  required this.offset,	// 滚动偏移控制器，通常由ScrollPosition实现。
  this.center,	// 中心子项的Key
  this.cacheExtent,	// 缓存区域大小
  this.cacheExtentStyle = CacheExtentStyle.pixel,	// 缓存区域计算方式
  this.clipBehavior = Clip.hardEdge,	// 超出Viewport边界内容的裁剪行为
  List<Widget> slivers = const <Widget>[],	// 子组件列表
})

属性详解：

• anchor : double，表示视口中的"零点" (scrollOffset为0.0的点) 在视口自身中的位置比例。0.0-视口的顶部(或左侧) 是滚动偏移的零点，当 scrollOffset 为 0 时，内容的开头对齐视口的开头。1.0-视口的底部 (或右侧) 是滚动偏移的零点。0.5-视口的中心是滚动偏移的零点。anchor 的改变会影响内容如何从 center key 开始向两侧填充。对于反向列表(reverse:true)，ListView会将其设置为1.0。
• center ：Key?， 中心子项的Key ，这是一个优化参数。当 Viewport 首次布局时，它会尝试找到这个 Key 对应的 Sliver，并假定它位于 scrollOffset 为 0.0 的位置。这主要有两个用途：快速定位 -在拥有大量数据时，可以快速定位到初始显示位置，而无需从头开始构建。布局稳定性-当 Viewport 的尺寸变化时 (如屏幕旋转) 通过 center key 可以保持同一个子项在视口中的相对位置，防止列表"跳动"。
• cacheExtent：doube?，指定在视口可见区域之外，上下(或左右) 应该预先构建和布局的区域大小。如：如果视口高度为 600px，cacheExtent 为 200px，那么系统会渲染从 -200px 到 800px 这个范围内的列表项。
• cacheExtentStyle ：CacheExtentStyle ，缓存单位，pixel -默认，逻辑像素，viewport-视口大小的倍数，如：cacheExtent 为 1.0 意味着在视口上方和下方各缓存一个视口高度的区域。
• slivers ：List，只能放 Sliver 类型的 Widget， 如：SliverList、SliverGrid、SliverAppBar, SliverToBoxAdapter 等。

核心方法：

// Widget 层和 RenderObject 层的连接点。Viewport Widget 
// 调用此方法来创建一个 RenderViewport 实例，并将构造函数中的所有参数传递给它。
createRenderObject(BuildContext context)

// 当 Viewport Widget 的配置发生变化时（例如 axisDirection 改变），此方法会被调用，
// 用新的配置去更新已存在的 RenderViewport 对象。
updateRenderObject(BuildContext context, RenderViewport renderObject)

// 创建 MultiChildRenderObjectElement，这是 Widget 在元素树中的表示。
createElement()

Viewport 在 渲染树 中有两个主要实现：

• RenderViewport ：标准视口 RenderObject，会扩展填充整个主轴空间。
• RenderShrinkWrappingViewport ：收缩包装视口 RenderObject，会根据其子组件在主轴上的大小来调整自身大小。

// 主轴上占据所有空间
RenderViewport extends RenderViewportBase<SliverPhysicalContainerParentData>{}

abstract class RenderViewportBase<ParentDataClass extends ContainerParentDataMixin<RenderSliver>>
    extends RenderBox with ContainerRenderObjectMixin<RenderSliver, ParentDataClass>
    implements RenderAbstractViewport { ... }

// 主轴上所有以包裹其内容 (shrinkWrap: true)
class RenderShrinkWrappingViewport extends RenderViewportBase<SliverLogicalContainerParentData> { ... }

父类 RenderViewportBase 继承了 RenderBox ，这表明 RenderViewport 自身遵循 盒子模型 (父节点会给他一个 BoxConstraints ，它必须在此约束下确定自己的size)，而管理的子节点列表则必须是 RenderSliver 类型，😄 可以把 RenderViewport 看作是 盒子协议 & Sliver协议 间的桥梁。具体的方法调用链路：

// ================ 🚀 初始化 ================

RenderViewport 构造函数
    ↓
调用父类 RenderViewportBase 构造
    ├─ 设置 axisDirection 和 crossAxisDirection // 设置主轴和交叉轴方向
    ├─ 绑定 ViewportOffset // 绑定滚动偏移控制器
    └─ 初始化 cacheExtent 和 clipBehavior // 设置缓存范围和裁剪行为
    ↓
设置 RenderViewport 特有属性
    ├─ _anchor = anchor // 设置锚点位置（0.0-1.0）
    └─ _center = center // 设置中心sliver
    ↓
addAll(children) // 批量添加子元素
    └─ adoptChild() // 为每个子元素建立父子关系
        ├─ setupParentData() // 设置 SliverPhysicalContainerParentData
        ├─ attach() // 将子元素附加到渲染管道
        └─ markNeedsLayout() // 标记需要重新布局
    ↓
设置默认center
    ├─ center == null && firstChild != null → _center = firstChild
    └─ 否则 → 保持原有center设置

attach() // 将视口附加到渲染管道
├─ super.attach(owner) // 调用父类attach方法
├─ _offset.addListener(markNeedsLayout) // 监听滚动偏移变化
└─ 递归调用子元素attach() // 确保所有子元素都正确附加

// ================ 📦 布局 ================

performLayout() // 布局入口
    ↓
应用视口尺寸到偏移控制器
    ├─ axis == Axis.vertical → offset.applyViewportDimension(size.height)
    └─ axis == Axis.horizontal → offset.applyViewportDimension(size.width)
    ↓
检查是否有子元素
    ├─ center == null → 设置滚动范围为0并返回
    │   ├─ _minScrollExtent = 0.0
    │   ├─ _maxScrollExtent = 0.0
    │   ├─ _hasVisualOverflow = false
    │   └─ offset.applyContentDimensions(0.0, 0.0)
    └─ 有子元素 → 继续布局流程
    ↓
计算布局参数
    ├─ (mainAxisExtent, crossAxisExtent) = switch (axis) // 计算主轴和交叉轴尺寸
    ├─ centerOffsetAdjustment = center!.centerOffsetAdjustment // 获取中心偏移调整
    └─ maxLayoutCycles = _maxLayoutCyclesPerChild * childCount // 设置最大布局循环次数
    ↓
执行布局循环
    ├─ _attemptLayout() // 尝试布局所有子元素
    │   ├─ 重置布局数据
    │   │   ├─ _minScrollExtent = 0.0
    │   │   ├─ _maxScrollExtent = 0.0
    │   │   └─ _hasVisualOverflow = false
    │   ├─ 计算中心偏移和绘制范围
    │   │   ├─ centerOffset = mainAxisExtent * anchor - correctedOffset
    │   │   ├─ reverseDirectionRemainingPaintExtent = clampDouble(centerOffset, 0.0, mainAxisExtent)
    │   │   └─ forwardDirectionRemainingPaintExtent = clampDouble(mainAxisExtent - centerOffset, 0.0, mainAxisExtent)
    │   ├─ 计算缓存范围
    │   │   ├─ _calculatedCacheExtent = switch (cacheExtentStyle) // 根据缓存样式计算实际缓存大小
    │   │   └─ 计算各方向的缓存范围
    │   ├─ layoutChildSequence(反向子元素) // 布局center之前的子元素
    │   │   ├─ child.layout(SliverConstraints) // 为每个子sliver执行布局
    │   │   ├─ updateChildLayoutOffset() // 更新子元素的布局偏移
    │   │   │   └─ childParentData.paintOffset = computeAbsolutePaintOffset()
    │   │   └─ updateOutOfBandData() // 更新滚动范围等额外数据
    │   │       ├─ GrowthDirection.reverse → _minScrollExtent -= scrollExtent
    │   │       └─ hasVisualOverflow → _hasVisualOverflow = true
    │   └─ layoutChildSequence (正向子元素) // 布局center及之后的子元素
    │       ├─ child.layout(SliverConstraints)	// ✨ 给每个子 Sliver下发约束，执行布局
    │       ├─ SliverGeometry childLayoutGeometry = child.geometry! // ✨ 获得Sliver 返回的几何信息
    │       ├─ updateChildLayoutOffset() // 记录每个 Sliver 的绘制位置
    │       └─ updateOutOfBandData() // 基于每个 Sliver 的反馈更新全局信息
    │           ├─ GrowthDirection.forward → _maxScrollExtent += scrollExtent	// 累计最大滚动范围
    │           └─ hasVisualOverflow → _hasVisualOverflow = true	// 判断是否有溢出
    ├─ correction != 0.0 → offset.correctBy(correction) // 修正滚动偏移量
    └─ correction == 0.0 → offset.applyContentDimensions() // 应用最终的内容尺寸范围

// ================ 🎨 绘制 ================

paint() // 绘制入口
    ↓
检查是否有子元素
    ├─ firstChild == null → 直接返回
    └─ 有子元素 → 继续绘制流程
    ↓
检查是否需要内容裁剪
    ├─ hasVisualOverflow && clipBehavior != Clip.none → 创建裁剪区域
    │   └─ _clipRectLayer.layer = context.pushClipRect() // 创建裁剪图层
    │       ├─ needsCompositing // 检查是否需要合成
    │       ├─ Offset.zero & size // 设置裁剪矩形
    │       ├─ _paintContents // 绘制内容回调
    │       └─ oldLayer: _clipRectLayer.layer // 复用旧图层
    └─ 无溢出或不裁剪 → 直接绘制内容
        ├─ _clipRectLayer.layer = null // 清理裁剪图层
        └─ _paintContents(context, offset) // 直接绘制内容
    ↓
_paintContents() // 绘制所有可见内容
    └─ 遍历 childrenInPaintOrder // 按绘制顺序处理子元素
        ├─ child.geometry!.visible → 检查子元素是否可见
        └─ context.paintChild(child, offset + paintOffsetOf(child)) // 绘制每个可见的子元素
            ├─ paintOffsetOf(child) // 获取子元素绘制偏移
            │   └─ return childParentData.paintOffset
            └─ 应用变换矩阵并绘制

😶 老规矩画个图帮助理解：

😏 原理学完，动手缝合下三个构件，实现一个 最简单 的滑动效果【--->c35/simple_scroll_demo.dart<---】：

运行效果：

😄 是的，就是这么简单，关于Flutter滑动机制 "三个核心构件" 就了解到这，接着开始学习具体的滑动组件。

3. 常用滑动组件

3.1. SingleChildScrollView

简介：

一个用于解决 "内容溢出 " 问题的简单 滚动容器Widget ，可以让 单个子Widget 在空间不足时进行滚动。

3.1.1. API 详解

继承 StatelessWidget ，大部分属性在 Scrollable 那里已经详细讲了，不再赘述，挑几个没讲到的：

• padding ：EdgeInsetsGeometry? ，在滚动区域内部添加内边距 (child外边)，边距会随着内容一起滚动。
• keyboardDismissBehavior ：ScrollViewKeyboardDismissBehavior ，用户与滚动区域交互时，如何以及何时自动收起弹出的键盘。【manual -默认】滚动视图本身不会做任何事情来收起键盘，键盘的收起完全依赖于其他方式，如：回退键、FocusScope.of(context).unfocus() 等。【onDrag 】当键盘弹出时，用户在滚动视图上开始拖动 (滚动) 的那一刻，键盘就会自动收起 ✨。
• primary ：bool? ，是否使用主滚动控制器，默认null，由系统自动根据上下文自动选择最合适的控制器。为 true 时，使用 主滚动控制器-PrimaryScrollController (不能同时设置自定义controller)，🤔 用于页面级别的滚动，需要与其它组件共享滚动状态，在移动平台上它会自动处理一些系统级的交互。如：Android 从屏幕边缘拖动可以触发返回操作，主滚动视图会优先响应滚动。在 iOS 上，点击状态栏可以快速滚动到顶部。在Scaffold中，如果body是一个可滚动组件，当键盘弹出时，会调整滚动区域以保证焦点输入框可见。为 false 时，当一个页面有多个滚动视图时，只能有一个可以是primary，其它都应该显示设置为false。一般用于独立的滚动区域：如对话框、侧边栏。

简单使用示例【--->c35/single_child_scroll_view_demo.dart<---】运行效果：

😄 非常简单，就切滚动物理效果、设置键盘随列表滚动消失、以及快速滑动到底部、中部和顶部。接着提下使用 SingleChildScrollView 的 两个注意事项：

① 与Column 配合使用的冲突

Column 试图占用尽可能多的空间，而 SingleChildScrollView 提供无限空间，这会导致冲突，需要对Column 进行高度约束。可以使用 LayoutBuilder + ConstrainedBox 设置最小高度，或者使用IntrinsicHeight 强制 Column 适应内容大小。

② 加载机制

SingleChildScrollView 会一次性将它的 child 全部渲染到内存中 ，而不管这个 child 有多大，它只是在 "视口 " 中移动显示。它更适合处理 内容相对固定且不太多 的场景，对于 大量动态内容 ，还是得选择具有 "懒加载 " 特性的滚动组件 (如 Listview )，混合布局可以考虑用 CustomScrollView。

3.1.2. 源码剖析

关于第一个注意事项 "SingleChildScrollView 提供无限空间"，在源码中的体现 (移除了滚动方向的尺寸约束)：

接着是第二个 "一次性将child全部渲染到内存中 "，跟下代码调用：SingleChildScrollView → build()

SingleChildScrollView 的 Viewport 具体实现 Widget 是 _SingleChildViewport ，对应的 RenderObject → _RenderSingleChildViewport

绘制方法：

上面通过 pushClipRect() 来显示显示区域 (视觉裁剪) 实现 "窗口效果"：

🤔 那 "滚动效果 " 呢？通过改变 paintOffset 来移动 子组件的绘制位置：

😁 视觉效果 (滑动) 与实际移动反向是 "相反" 的 ❗️ 向下滚动时，子组件是向上移动的，Y轴负值表示向上移动。

初始状态 (position = 0):
┌─────────────────┐ ← 视口顶部
│  子组件内容A     │
│  子组件内容B     │
│  子组件内容C     │
└─────────────────┘ ← 视口底部
│  子组件内容D     │ ← 不可见
│  子组件内容E     │ ← 不可见

向下滚动 (position = 100):
                   ← 子组件内容A (不可见)
┌─────────────────┐ ← 视口顶部
│  子组件内容B     │
│  子组件内容C     │
│  子组件内容D     │
└─────────────────┘ ← 视口底部
│  子组件内容E     │ ← 不可见

😊 可以将 clipBehavior 属性 Clip.none 来验证是否 child 是否真的是 全部渲染 【--->c35/single_child_scroll_none_clip_demo.dart<---】运行效果：

3.2. ScrollView

抽象类 ，Flutter中绝大部分 "可滚动视图 " 的 顶层父类 ，核心思想是 "滚动机制 & 内容布局 " 的解耦，定义了一个可滚动区域的通用配置框架，具体如何排列子元素 (列表、网格或是其它形式) 则交由其子类实现。它的使命：

将用户的 滚动意图 (由Scrollable捕获) 转化为 视口内内容的平移 (由Viewport 和 Slivers 实现)。

核心方法：

// ❗️ 子类都必须实现，用于返回 Widget列表 (必须是Sliver类型，
// 如：SliverList, SliverGrid, SliverToBoxAdapter),
// ScrollView 会把这个 Sliver 列表交给 Viewport 去渲染.
@protected
List<Widget> buildSlivers(BuildContext context);

// 构建Viewport，根据 shrinkWrap 决定使用哪种 Viewport
@protected  
Widget buildViewport(
  BuildContext context,
  ViewportOffset offset, 
  AxisDirection axisDirection,
  List<Widget> slivers,
){
  if (shrinkWrap) {
      return ShrinkWrappingViewport(...);
  }
  return Viewport();
}

// 结合 scrollDirection 和 reverse，用于获取滚动方向。
@protected
AxisDirection getDirection(BuildContext context) {
  return getAxisDirectionFromAxisReverseAndDirectionality(context, scrollDirection, reverse);
}

// 实现了 StatelessWidget.build()
@override
Widget build(BuildContext context) {
  // 第1步：构建 slivers 列表
  final List<Widget> slivers = buildSlivers(context);
  
  // 第2步：确定滚动方向
  final AxisDirection axisDirection = getDirection(context);

  // 第3步：确定有效的 primary 属性
  final bool effectivePrimary = primary
      ?? controller == null && PrimaryScrollController.shouldInherit(context, scrollDirection);

  // 第4步：获取滚动控制器
  final ScrollController? scrollController = effectivePrimary
      ? PrimaryScrollController.maybeOf(context)
      : controller;

  // 第5步：创建 Scrollable 组件
  final Scrollable scrollable = Scrollable(
    dragStartBehavior: dragStartBehavior,
    axisDirection: axisDirection,
    controller: scrollController,
    physics: physics,
    scrollBehavior: scrollBehavior,
    semanticChildCount: semanticChildCount,
    restorationId: restorationId,
    // 💡 将 Slivers 喂给 Viewport
    viewportBuilder: (BuildContext context, ViewportOffset offset) {
      return buildViewport(context, offset, axisDirection, slivers);
    },
    clipBehavior: clipBehavior,
  );

  // 第6步：处理 PrimaryScrollController 继承
  final Widget scrollableResult = effectivePrimary && scrollController != null
      ? PrimaryScrollController.none(child: scrollable)
      : scrollable;

  // 第7步：处理键盘消失行为
  if (keyboardDismissBehavior == ScrollViewKeyboardDismissBehavior.onDrag) {
    return NotificationListener<ScrollUpdateNotification>(
      child: scrollableResult,
      onNotification: (ScrollUpdateNotification notification) {
        final FocusScopeNode focusScope = FocusScope.of(context);
        if (notification.dragDetails != null && focusScope.hasFocus) {
          focusScope.unfocus();
        }
        return false;
      },
    );
  } else {
    return scrollableResult;
  }
}

😄 将通用的滚动逻辑 (视口、控制器、物理效果) 都进行了封装，子类只需实现 buildSlivers() 塞 Slivers。

3.3. ListView

简介：

用于创建 可滚动的线性列表布局 的高级滑动组件。

3.3.1. API 详解

继承 BoxScrollView，同样挑几个属性讲讲：

• shrinkWrap ：bool，默认false，尽可能占据父组件在滚动方向上提供的所有空间，如果父组件没限制 (如Column)，就会导致无限高度/宽度错误。为true时，尺寸会收缩以包裹其内容的总高度/宽度，但这样会牺牲性能，因为它需要计算所有子项的尺寸 (即便不可见) 来确定自身的总尺寸。故仅在必要时使用，如：在Column 中嵌套一个 ListView 时。
• itemExtent ：double? ，子项固定固定高度，如果所有子项都有相同的高度/宽度，设置此属性能极大地提高性能。因为 Listview不再需要动态计算每个子项的尺寸，可以直接算出滚动偏移，从而简化布局过程。
• itemExtentBuilder ：ItemExtentBuilder? ，子项高度构建器 ，其实就一方法回调，有两个参数：index -当前子项索引 和 dimensions-当前滚动视口的尺寸信息，返回值double-子项高度。适用于：当你的列表项目高度是可预知的、有规律的，但又不完全相同的场景，如：奇数index，高度50，偶数index，高度100。
• prototypeItem ：Widget? ，列表项高度/宽度基本一致但又不想写死 itemExtent，可以提供一个 原型Widget，ListView 会测量这个原型一次，然后假设所有其他项都具有相同的尺寸。
• cacheExtent ：double? ，缓存范围，Viewport 的预加载区域大小 (默认250.0) 增加此值可以减少快速滚动时的空白，但因为会提前构建更多项，所以会增加内存消耗。
• addAutomaticKeepAlives ：bool ，默认true，当列表项滚动出视口时，是否自动使用 AutomaticKeepAlive 来保存它们的状态。列表项 的 State 也需要混入 AutomaticKeepAliveClientMixin 重写 wantKeepAlive 返回 true 才会有效，对列表项包含复杂状态 (如输入框内容、动画状态) 时很有用。更复杂的和状态，应使用外部状态管理方案 (如Provider、BLoC、Riverpod等)，将状态与 UI 分离。
• addRepaintBoundaries ：bool，默认true，是否为每个列表项自动包裹一个 RepaintBoundary，用于隔离每个列表项的重绘，防止一个项的动画或变化导致整个列表重绘，从而优化性能。

提供了 四种构造方式：

// ✨ 默认构造函数，接收一个 List<Widget> 作为 children。
// 内部使用 SliverChildListDelegate，它会一次性构建所有的子 Widget，
// 所以仅适用于【少量、固定的子项】的场景
ListView(children: <Widget>[ Container(), ...])

// ✨ ListView.builder()，最常用、最高性能
// 内部使用 SliverChildBuilderDelegate，它不会立即创建所有列表项，而是通过
// itemBuilder 回调函数，在列表项即将进入视口时才进行构建。适用于【大量或无限子项】的场景
final List<String> entries = List<String>.generate(1000, (i) => 'Item $i');
ListView.builder(
  itemCount: entries.length,	// 列表项总数，如果为 null，则表示一个无限列表。
  itemBuilder: (BuildContext context, int index) {
    // 根据索引 index 返回对应的 Widget
    return ListTile(
      title: Text(entries[index]),
    );
  },
)

// ✨ ListView.separated()，builder() 变种，可以方便地在每个列表项之间插入一个分割线 Widget
ListView.separated(
  itemCount: 100,
  itemBuilder: (BuildContext context, int index) {
    return ListTile(title: Text('Item $index'));
  },
  // 根据索引 index 构建位于 item[index] 和 item[index + 1] 间的分割线。
  separatorBuilder: (BuildContext context, int index) {
    return const Divider(color: Colors.grey);
  },
)

// ✨ ListView.custom() 完全自定义，允许你提供一个自定义的 SliverChildDelegate
// 通过「childrenDelegate」参数传入，前三种构造方法其实都是这个构造方法的语法糖。
// 这种构造方式很少直接使用，适用场景：需对子项的创建、销毁、保活等行为进行更精细控制

3.3.2. 源码剖析

默认构造函数，内部使用 SliverChildListDelegate：

SliverChildListDelegate extends SliverChildDelegate { 
  SliverChildListDelegate(
    this.children, // 这里是 List<Widget>
    {
    this.addAutomaticKeepAlives = true,
    this.addRepaintBoundaries = true,
    this.addSemanticIndexes = true,
    this.semanticIndexCallback = _kDefaultSemanticIndexCallback,
    this.semanticIndexOffset = 0,
  }) : _keyToIndex = <Key?, int>{null: 0};
}

看下 build() 方法：

"盐值(Salt) " 这个概念来自密码学，指的是在 加密过程中添加的额外随机数据 。在这里是给原有Key 添加额外信息 ，如：原始Key("item_1") 包装成 _SaltedValueKey(Key('item_1'))，目的是让这个Key在delegate内部是唯一的，以避免Flutter混乱这些Key，导致状态错乱。

"KeyedSubtree " 是一个特殊的 Widget ，它的作用是：为整个子树提供一个稳定的身份标识，帮助Flutter的渲染系统正确追踪Widget，确保当Widget位置变化时，状态能正确保持。"Element复用机制 "：当Widget第一次显示时，Flutter创建对应的 Element 和 RenderObject ，当Widget重新构建时，Flutter会尝试 复用已有的Element ，复用条件是：Widget的runtimeType和key都相同。

😶 用的 children ，传入时就是已经创建的Widget，所以是一次性构建所有的子 Widget ，接着看下 builder() 构建的方式，用的 SliverChildBuilderDelegate：

class SliverChildBuilderDelegate extends SliverChildDelegate {
  const SliverChildBuilderDelegate(
    this.builder, // 这里是 NullableIndexedWidgetBuilder
    {
    this.findChildIndexCallback,
    this.childCount,
    this.addAutomaticKeepAlives = true,
    this.addRepaintBoundaries = true,
    this.addSemanticIndexes = true,
    this.semanticIndexCallback = _kDefaultSemanticIndexCallback,
    this.semanticIndexOffset = 0,
  });
}

typedef NullableIndexedWidgetBuilder = Widget? Function(BuildContext context, int index);

看下 build() 方法：

💁‍♂️ separated() 也是用的 SliverChildBuilderDelegate ，custom() 则需要通过 childrenDelegate 参数传入自定义的 SliverChildDelegate 。继承关系：ListView → BoxScrollView → ScrollView ，BoxScrollView 在 ScrollView 的基础上增加了 "自动填充padding " (避免状态栏遮挡-垂直滚动自动添加顶部填充、避免底部导航栏-自动添加底部填充、刘海屏适配-自动处理异形屏幕的安全区域)。另外，还对布局构建进行了抽象，子类只需实现 buildChildLayout(BuildContext context) 方法。构建调用链路：

ScrollView.build()
  ↓
BoxScrollView.buildSlivers()
  ↓
ListView.buildChildLayout()	// 生成 SliverMultiBoxAdaptorWidget 对象
  ↓ 
BoxScrollView.buildSlivers() // 包装ListView生成的Sliver (如SliverPadding)，返回[sliver]
  ↓
ScrollView.build() // 总装配
  ↓
@override
Widget build(BuildContext context) {
  final List<Widget> slivers = buildSlivers(context);  // ② 获取slivers
  final Scrollable scrollable = Scrollable(  // ① 创建Scrollable
    viewportBuilder: (context, offset) => buildViewport(context, offset, axisDirection, slivers),
  );
}

清楚明了，看下 ListView.buildChildLayout() ，根据不同情况，创建了四种类型的 Sliver Widget：

👀 跟下这四个 Sliver 到类的具体实现~

3.3.3. SliverList - 动态列表

每个子项都要调用 layout() 方法，需要缓存已测量子项的信息，核心源码：

class SliverList extends SliverMultiBoxAdaptorWidget {
  const SliverList({
    super.key,
    required super.delegate,
  });

  @override
  RenderSliverList createRenderObject(BuildContext context) {
    final SliverMultiBoxAdaptorElement element = context as SliverMultiBoxAdaptorElement;
    return RenderSliverList(childManager: element);
  }
}

// 底层 RenderObject 核心逻辑
class RenderSliverList extends RenderSliverMultiBoxAdaptor {
  // 🔥 关键：每个子项都需要单独进行布局计算
  @override
  void performLayout() {
    // 1. 遍历每个可见的子项
    // 2. 调用 child.layout() 计算每个子项的实际尺寸
    // 3. 累积计算总的滚动范围
    // 4. 确定每个子项的位置
    
    double scrollOffset = constraints.scrollOffset;
    double remainingExtent = constraints.remainingPaintExtent;
    
    // 💡 关键性能瓶颈：需要逐个测量每个子项的高度
    while (remainingExtent > 0) {
      RenderBox child = getChildAtIndex(index);
      child.layout(constraints.asBoxConstraints(), parentUsesSize: true);
      
      // 📏 每次都要获取子项的实际高度
      double childExtent = getMainAxisExtent(child);
      // ... 位置计算和缓存逻辑
    }
  }
}

3.3.4. SliverFixedExtentList - 固定高度高性能列表

直接通过数学计算确定位置，跳过子项的layout过程，可以精确预测滚动范围，核心源码：

class SliverFixedExtentList extends SliverMultiBoxAdaptorWidget {
  const SliverFixedExtentList({
    super.key,
    required super.delegate,
    required this.itemExtent, // 👈 关键：固定高度
  });

  final double itemExtent; // 🔥 核心：所有子项的固定高度

  @override
  RenderSliverFixedExtentList createRenderObject(BuildContext context) {
    final SliverMultiBoxAdaptorElement element = context as SliverMultiBoxAdaptorElement;
    return RenderSliverFixedExtentList(
      childManager: element,
      itemExtent: itemExtent, // 传递固定高度
    );
  }
}

// 底层 RenderObject 核心逻辑
class RenderSliverFixedExtentList extends RenderSliverMultiBoxAdaptor {
  final double itemExtent;

  @override
  void performLayout() {
    // 🚀 性能优势：可以直接计算而不需要测量
    
    // 1. 🔥 直接计算可见区域内的项目数量
    double scrollOffset = constraints.scrollOffset;
    int firstVisibleIndex = (scrollOffset / itemExtent).floor();
    int lastVisibleIndex = ((scrollOffset + constraints.viewportMainAxisExtent) / itemExtent).ceil();
    
    // 2. 🚀 直接计算每个子项的位置（无需layout测量）
    for (int index = firstVisibleIndex; index <= lastVisibleIndex; index++) {
      RenderBox child = getChildAtIndex(index);
      
      // 💎 关键优化：强制设置子项高度，跳过子项自己的layout计算
      child.layout(
        constraints.asBoxConstraints(
          minHeight: itemExtent,
          maxHeight: itemExtent, // 强制固定高度
        ),
        parentUsesSize: false, // 💡 不需要获取子项尺寸
      );
      
      // 🎯 直接计算位置：索引 * 固定高度
      double childMainAxisPosition = index * itemExtent - scrollOffset;
      // 设置子项位置...
    }
    
    // 3. 🚀 直接计算总的滚动范围
    geometry = SliverGeometry(
      scrollExtent: childCount * itemExtent, // 直接计算总高度
      paintExtent: math.min(constraints.remainingPaintExtent, maxPaintExtent),
      maxPaintExtent: childCount * itemExtent,
    );
  }
}

3.3.5. SliverPrototypeExtentList - 原型高度列表

支持复杂的Widget作为原型，只需测量原型一次，后续使用固定高度算法，核心源码：

class SliverPrototypeExtentList extends SliverMultiBoxAdaptorWidget {
  const SliverPrototypeExtentList({
    super.key,
    required super.delegate,
    required this.prototypeItem, // 👈 关键：原型Widget
  });

  final Widget prototypeItem; // 🔥 核心：用于测量的原型Widget

  @override
  RenderSliverPrototypeExtentList createRenderObject(BuildContext context) {
    final SliverMultiBoxAdaptorElement element = context as SliverMultiBoxAdaptorElement;
    return RenderSliverPrototypeExtentList(
      childManager: element,
      prototypeItem: prototypeItem,
    );
  }
}

// 底层 RenderObject 核心逻辑：
class RenderSliverPrototypeExtentList extends RenderSliverMultiBoxAdaptor {
  Widget _prototypeItem;
  double? _prototypeExtent; // 缓存原型的高度
  
  @override
  void performLayout() {
    // 🎨 首次计算：测量原型Widget的高度
    if (_prototypeExtent == null) {
      _prototypeExtent = _measurePrototype();
    }
    
    // 💎 后续逻辑与SliverFixedExtentList类似
    double itemExtent = _prototypeExtent!;
    
    // 🚀 使用固定高度的高性能算法
    int firstVisibleIndex = (constraints.scrollOffset / itemExtent).floor();
    int lastVisibleIndex = ((constraints.scrollOffset + constraints.viewportMainAxisExtent) / itemExtent).ceil();
    
    for (int index = firstVisibleIndex; index <= lastVisibleIndex; index++) {
      RenderBox child = getChildAtIndex(index);
      
      // 🔥 强制使用原型高度
      child.layout(
        constraints.asBoxConstraints(
          minHeight: itemExtent,
          maxHeight: itemExtent,
        ),
        parentUsesSize: false,
      );
    }
  }
  
  // 🎨 原型测量方法
  double _measurePrototype() {
    // 1. 创建原型Widget的RenderObject
    RenderBox prototypeRenderBox = _createPrototypeRenderBox();
    
    // 2. 对原型进行layout测量
    prototypeRenderBox.layout(constraints.asBoxConstraints(), parentUsesSize: true);
    
    // 3. 获取原型的主轴高度
    double extent = getMainAxisExtent(prototypeRenderBox);
    
    // 4. 清理原型RenderObject
    prototypeRenderBox.dispose();
    
    return extent;
  }
}

3.3.6. SliverVariedExtentList - 预定义不同高度列表

适用于高度已知，无需子项自己测量，itemExtentBuilder会被多次调用，计算过的高度会被缓存，核心源码：

class SliverVariedExtentList extends SliverMultiBoxAdaptorWidget {
  const SliverVariedExtentList({
    super.key,
    required super.delegate,
    required this.itemExtentBuilder, // 👈 关键：高度构建器
  });

  // 🔥 核心：根据索引和维度信息返回高度的回调
  final ItemExtentBuilder itemExtentBuilder;

  @override
  RenderSliverVariedExtentList createRenderObject(BuildContext context) {
    final SliverMultiBoxAdaptorElement element = context as SliverMultiBoxAdaptorElement;
    return RenderSliverVariedExtentList(
      childManager: element,
      itemExtentBuilder: itemExtentBuilder,
    );
  }
}

// 底层 RenderObject 核心逻辑：
class RenderSliverVariedExtentList extends RenderSliverMultiBoxAdaptor {
  final ItemExtentBuilder itemExtentBuilder;
  
  // 🔧 高度缓存机制
  final Map<int, double> _cachedExtents = <int, double>{};

  @override
  void performLayout() {
    double scrollOffset = constraints.scrollOffset;
    double remainingExtent = constraints.remainingPaintExtent;
    
    // 📊 混合策略：预计算 + 按需计算
    int currentIndex = 0;
    double currentOffset = 0;
    
    // 1. 🔍 找到第一个可见的子项（通过累积高度）
    while (currentOffset < scrollOffset) {
      double itemHeight = _getItemExtent(currentIndex);
      currentOffset += itemHeight;
      currentIndex++;
    }
    
    // 2. 🎯 渲染可见区域内的子项
    while (remainingExtent > 0 && currentIndex < childCount) {
      double itemHeight = _getItemExtent(currentIndex);
      
      RenderBox child = getChildAtIndex(currentIndex);
      // 💡 性能优化：使用预定义的高度约束子项
      child.layout(
        constraints.asBoxConstraints(
          minHeight: itemHeight,
          maxHeight: itemHeight,
        ),
        parentUsesSize: false,
      );
      
      remainingExtent -= itemHeight;
      currentIndex++;
    }
  }
  
  // 🔥 核心方法：获取指定索引的高度
  double _getItemExtent(int index) {
    // 缓存机制避免重复计算
    return _cachedExtents[index] ??= itemExtentBuilder(index, constraints);
  }
}

3.4. GridView

简介：

用于创建 二维可滚动网格布局容器 ，能够将一系列子Widget 排列成 多行多列的网格形式，支持横向和纵向滚动。

3.4.1. API 详解

继承 BoxScrollView ，属性和Listview差不多，核心是 "gridDelegate"，它负责定义网格的几何结构。

// 控制网格布局的代理
final SliverGridDelegate gridDelegate;

// Flutter 提供了两个实现
SliverGridDelegateWithFixedCrossAxisCount
- crossAxisCount: 固定列数。
- mainAxisSpacing: 主轴间距。
- crossAxisSpacing: 交叉轴间距。
- childAspectRatio: 子项的宽高比。默认为 1.0。非常重要，用于计算子项在主轴上的高度。

SliverGridDelegateWithMaxCrossAxisExtent
- maxCrossAxisExtent: 子项在交叉轴上的最大尺寸
- 其它参数同上

提供了 五种构造方式：

// 模拟一些数据
final List<int> data = List.generate(50, (index) => index);

// ✨ ① GridView() - 默认构造函数
// 需要手动提供 gridDelegate 和 children 列表，适合少量、固定的子项。
GridView(
  gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
    crossAxisCount: 3,	// 交叉轴子项数量
    crossAxisSpacing: 10,	// 交叉轴方向相邻子项间的间距
    mainAxisSpacing: 10,	// 主轴方向相邻子项间的间距
    childAspectRatio: 1.0, // 子项的宽高比
  ),
  children: data.map((i) => GridItem(index: i)).toList()
);


// ✨ ① GridView.count() - 最常用，用于创建固定列数的网格
GridView.count(
  // 核心参数：固定列数
  crossAxisCount: 4,
  crossAxisSpacing: 10,
  mainAxisSpacing: 10,
  children: data.map((i) => GridItem(index: i)).toList(),
);

// ✨ ③ GridView.extent() - 响应式布局，根据子项的最大宽度自动计算列数。
GridView.extent(
  // 核心参数：子项在交叉轴上的最大尺寸
  maxCrossAxisExtent: 120.0,
  crossAxisSpacing: 10,
  mainAxisSpacing: 10,
  children: data.map((i) => GridItem(index: i)).toList(),
);

// ✨ ④ GridView.builder() - 高性能懒加载，用于大量或无限数据的场景，按需构建子项。
GridView.builder(
  // 布局代理，与默认构造函数中的一样
  gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
    crossAxisCount: 3,
    crossAxisSpacing: 10,
    mainAxisSpacing: 10,
  ),
  // 核心参数：子项总数
  itemCount: data.length,
  // 核心参数：子项构建器
  itemBuilder: (context, index) {
    // 只有当 item 将要显示时，此方法才会被调用
    print('Building item for builder: $index');
    return GridItem(index: data[index]);
  },
);

// ✨ ⑤ GridView.custom() - 完全自定义，提供了最大的灵活性，可以自定义子项的构建和管理策略。
GridView.custom(
  gridDelegate: const SliverGridDelegateWithMaxCrossAxisExtent(
    maxCrossAxisExtent: 150,
    mainAxisSpacing: 10,	// 主轴间距
    crossAxisSpacing: 10,	// 交叉轴间距
  ),
  // 核心参数：子项代理
  // SliverChildBuilderDelegate 行为与 GridView.builder 相同
  childrenDelegate: SliverChildBuilderDelegate(
    (context, index) {
      return GridItem(index: data[index]);
    },
    childCount: data.length,
  ),
);

简单使用示例【--->c35/gridview_demo.dart<---】运行效果：

3.4.2. 源码剖析

有了前面 ListView 的经验，看起源码来可谓是轻车熟路了，先是 构造方法：

// 😄 前三个的 Sliver 都是【SliverChildListDelegate】，全是一次性加载所有子控件
// 区别在于【网格布局代理类】的不同：
// 
//「SliverGridDelegateWithFixedCrossAxisCount」
// 固定交叉轴上的子项数量 (列数/行数)，无论屏幕多大，始终显示固定的列数
// 子项宽度：childWidth = (totalWidth - spacing) / crossAxisCount 
//
//「SliverGridDelegateWithMaxCrossAxisExtent」
// 固定子项在交叉轴上的最大尺寸，根据屏幕大小自动计算合适的列数
// 开发者指定子项最大宽度固定，如：maxCrossAxisExtent = 150.0 
// 计算列数：crossAxisCount = ceil(totalWidth / (maxCrossAxisExtent + spacing))
// 计算子项宽度：childWidth = (totalWidth - spacing) / crossAxisCount

GridView()  → 需要自定义 SliverGridDelegateWithFixedCrossAxisCount 通过 gridDelegate 传入

GridView.count()  → 内部自动创建 SliverGridDelegateWithFixedCrossAxisCount

GridView.extend() → 内部自动创建 SliverGridDelegateWithMaxCrossAxisExtent
  
// 💡 懒加载，Sliver 是【SliverChildBuilderDelegate】，需传入自定义的 gridDelegate 参数。
GridView.builder()

// 既需要自定义 gridDelegate 参数，也需要自定义 childrenDelegate 参数。
GridView.custom()

GridView 也是继承 BoxScrollView ，直接搜 buildChildLayout() ：

3.4.3. SliverGrid - 网格布局

用于在 二维网格中放置多个 box 子组件 的 Sliver 组件，专门为滚动视图设计的 网格布局组件。

RenderSliverGrid 的核心源码：

class RenderSliverGrid extends RenderSliverMultiBoxAdaptor {
  @override
  void performLayout() {
    // 🎯【准备阶段】获取滚动约束条件
    final SliverConstraints constraints = this.constraints;
    childManager.didStartLayout();
    childManager.setDidUnderflow(false);
  
    final double scrollOffset = constraints.scrollOffset + constraints.cacheOrigin;
    final double remainingExtent = constraints.remainingCacheExtent;
    final double targetEndScrollOffset = scrollOffset + remainingExtent;

    // 🎯【计算可见范围】获取布局策略、计算第一个/最后一个可见子项索引
    final SliverGridLayout layout = _gridDelegate.getLayout(constraints);
    final int firstIndex = layout.getMinChildIndexForScrollOffset(scrollOffset);
    final int? targetLastIndex = targetEndScrollOffset.isFinite ?
    layout.getMaxChildIndexForScrollOffset(targetEndScrollOffset) : null;

    // 🎯【垃圾回收】移除不在可见范围内的子组件，释放内存
    if (firstChild != null) {
      final int leadingGarbage = calculateLeadingGarbage(firstIndex: firstIndex);
      final int trailingGarbage = targetLastIndex != null ? calculateTrailingGarbage(lastIndex: targetLastIndex) : 0;
      collectGarbage(leadingGarbage, trailingGarbage);
    } else {
      collectGarbage(0, 0);
    }

    // 🎯【布局子组件】每个子组件都通过 SliverGridGeometry 获得精确的位置和尺寸
    // 双向构建-既向前也向后添加子组件，懒加载-只构建可见区域的子组件
    
    // 处理第一个子组件
    final SliverGridGeometry firstChildGridGeometry = layout.getGeometryForChildIndex(firstIndex);
    
    // 向前添加子组件
    for (int index = indexOf(firstChild!) - 1; index >= firstIndex; --index) {
      final SliverGridGeometry gridGeometry = layout.getGeometryForChildIndex(index);
      final RenderBox child = insertAndLayoutLeadingChild(
        gridGeometry.getBoxConstraints(constraints),
      )!;
      final SliverGridParentData childParentData = child.parentData! as SliverGridParentData;
      childParentData.layoutOffset = gridGeometry.scrollOffset;
      childParentData.crossAxisOffset = gridGeometry.crossAxisOffset;
    }
    
    // 向后添加子组件
    for (int index = indexOf(trailingChildWithLayout!) + 1; targetLastIndex == null || index <= targetLastIndex; ++index) {
      // ... 类似的布局逻辑
    }

    // 🎯【计算几何信息】估算总滚动范围、计算绘制区域、计算缓存区域
    final double estimatedTotalExtent = reachedEnd
      ? trailingScrollOffset
      : childManager.estimateMaxScrollOffset(
          constraints,
          firstIndex: firstIndex,
          lastIndex: lastIndex,
          leadingScrollOffset: leadingScrollOffset,
          trailingScrollOffset: trailingScrollOffset,
        );
    final double paintExtent = calculatePaintOffset(
      constraints,
      from: math.min(constraints.scrollOffset, leadingScrollOffset),
      to: trailingScrollOffset,
    );
    geometry = SliverGeometry(
      scrollExtent: estimatedTotalExtent,
      paintExtent: paintExtent,
      maxPaintExtent: estimatedTotalExtent,
      cacheExtent: cacheExtent,
      hasVisualOverflow: estimatedTotalExtent > paintExtent || constraints.scrollOffset > 0.0 || constraints.overlap != 0.0,
    );
  }
}

代码有点多，梳理下执行链条：

RenderSliverGrid.performLayout()  // 开始网格布局
  ↓
childManager.didStartLayout()  // 初始化子组件管理器
  ↓
_gridDelegate.getLayout(constraints)  // 获取网格布局策略
  ↓
layout.getMinChildIndexForScrollOffset(scrollOffset)  // 计算第一个可见子项索引
  ↓
layout.getMaxChildIndexForScrollOffset(targetEndScrollOffset)  // 计算最后一个可见子项索引
  ↓
collectGarbage(leadingGarbage, trailingGarbage)  // 回收不可见的子组件
  ↓
layout.getGeometryForChildIndex(firstIndex)  // 获取第一个子项的几何信息
  ↓
for (index >= firstIndex; --index)  // 【循环1】向前布局缺失的子组件
  → insertAndLayoutLeadingChild()
  → 设置 layoutOffset 和 crossAxisOffset
  ↓
for (index <= targetLastIndex; ++index)  // 【循环2】向后布局新的子组件
  → insertAndLayoutChild()
  → 设置 layoutOffset 和 crossAxisOffset
  ↓
childManager.estimateMaxScrollOffset()  // 估算总滚动范围
  ↓
calculatePaintOffset() / calculateCacheOffset()  // 计算绘制和缓存区域
  ↓
geometry = SliverGeometry(...)  // 创建最终几何信息
  ↓
childManager.didFinishLayout()  // 完成布局，清理资源

😄 套下数据写个简单的例子 (垂直方向、一行4列，子元素高度为50，Viewport 为180，有24个子项)：

// ① 计算可见范围
scrollOffset = 0 (初始位置)
targetEndScrollOffset = 0 + 180 = 180
layout.getMinChildIndexForScrollOffset(0) = 0     // 第一个可见项：索引0
layout.getMaxChildIndexForScrollOffset(180) = 15  // 最后一个可见项：索引15
// 计算详解
mainAxisCount = (180 / 50).ceil() = 3.6.ceil() = 4 行
maxChildIndex = max(0, 4 * 4 - 1) = 15

// ② 分析子项分布 (24个):
行1 (y=0-50):    [0] [1] [2] [3]     
行2 (y=50-100):  [4] [5] [6] [7]     
行3 (y=100-150): [8] [9] [10][11]    
行4 (y=150-200): [12][13][14][15]    
行5 (y=200-250): [16][17][18][19]    ← 不可见
行6 (y=250-300): [20][21][22][23]    ← 不可见

实际需要布局的子项: 索引 0-15 (只有前16个)
不会创建的子项: 索引 16-23 (后8个)

// ③ 布局执行
collectGarbage(): 清理超出范围的子项

第一个循环 (向前布局):
无需执行 (从索引0开始)

第二个循环 (向后布局):
for (index = 1; index <= 15; ++index) {  // 注意：只到15，不到23
  insertAndLayoutChild() // 只创建索引1到15的子项
  设置 layoutOffset 和 crossAxisOffset
}

索引16-23的子项: 完全不会被创建！

// ④ 最终几何信息
estimatedTotalExtent = childManager.estimateMaxScrollOffset()
// 会根据已知的16个子项来估算24个子项的总高度
// 估算结果: 6行 × 50px = 300px

paintExtent = 180px (viewport高度)
scrollExtent = 300px (估算的总滚动范围)

// 渲染结果
┌─────────────────────────┐ ← viewport top (y=0)
│ [0]  [1]  [2]  [3]     │ ← 行1: 已创建，完全可见
│ [4]  [5]  [6]  [7]     │ ← 行2: 已创建，完全可见
│ [8]  [9]  [10] [11]    │ ← 行3: 已创建，完全可见
│ [12] [13] [14] [15]    │ ← 行4: 已创建，部分可见
└─────────────────────────┘ ← viewport bottom (y=180)
未显示区域:
│ [16] [17] [18] [19]    │ ← 行5: 未创建，不可见
│ [20] [21] [22] [23]    │ ← 行6: 未创建，不可见

3.5. PageView

简介

可滚动的列表，特殊之处在于它的每个子组件 (称为"页面 ") 在滚动时都会强制占据整个视口 (Viewport)。常用于引导页、轮播图。TabBarView 也是基于它实现的，用来配置TabBar展示不同标签下的内容。

3.5.1. API 详解

继承 StatefulWidget，同样挑几个属性讲讲：

• pageSnapping ：bool，是否启用页面吸附，默认true，滚动停止时会自动吸附到最近的页面边界，设置 false，则可以停在任何位置。
• padEnds ：bool ，是否在列表的两端添加填充，默认true，会在第一页和最后一页添加额外的填充空间。使得第一页和最后一页能够居中显示在视口中。这个参数只有 viewportFraction < 1.0 时才生效。
• onPageChanged ：ValueChanged? ，当一个新页面完全显示时 (pageSnapping完成后) 调用，可以获取新页面的索引。
• childrenDelegate ：PageView 内部使用它来生成子组件，不同构造方法最终会创建不同类型的 SliverChildDelegate。

提供了 三种构造方式：

// ✨ ① PageView() - 默认构造函数，适合页面数量较少且固定的情况
PageView(
  children: <Widget>[
    _buildPage(1, Colors.pink),
    _buildPage(2, Colors.cyan),
    _buildPage(3, Colors.deepPurple),
  ],
)

// ✨ ② PageView.builder() - 构造器构造函数，最常用，懒加载，适合页面数量多或不确定的情况。
// 假设有100个页面
const int pageCount = 100;
PageView.builder(
  itemCount: pageCount,
  itemBuilder: (BuildContext context, int index) {
    // itemBuilder 会在页面即将进入视口时被调用
    // 这意味着只有当用户滑动到某个页面时，它才会被构建
  }
)

// ✨ ③ PageView.custom() - 自定义构造函数，对子项的构建、布局和回收逻辑进行高度自定义时。
PageView.custom(
  // childrenDelegate 是核心，它决定了如何提供子页面
  childrenDelegate: SliverChildBuilderDelegate(
    (BuildContext context, int index) {
      // 如：奇数页和偶数页显示不同的内容
      if (index.isEven) {
        return Container(
          color: Colors.green,
          child: Center(
            child: Text(
              'Even Page ${index + 1}\n(From PageView.custom())',
              textAlign: TextAlign.center,
              style: const TextStyle(fontSize: 22, color: Colors.white),
            ),
          ),
        );
      } else {
        return Container(
          color: Colors.orange,
          child: Center(
            child: Text(
              'Odd Page ${index + 1}\n(From PageView.custom())',
              textAlign: TextAlign.center,
              style: const TextStyle(fontSize: 22, color: Colors.white),
            ),
          ),
        );
      }
    },
    // 同样可以指定子项数量，也可以为 null 表示无限列表
    childCount: 20, 
  ),
);

页面的切换控制，用到的 → PageController ，它继承自 ScrollController ，在原有像素级别的基础上，新增了 "页面" 级别的滚动控制，构造方法 & 类成员：

PageController({
  this.initialPage = 0,           // 初始页面索引
  this.keepPage = true,           // 是否保存页面状态
  this.viewportFraction = 1.0,    // 视口占比，< 1.0 每页只占部分视口，可以看到相邻页面的一部分
                                  // > 1.0: 每页超出视口，会有padding效果
  super.onAttach,                 // 附加回调
  super.onDetach,                 // 分离回调
}) : assert(viewportFraction > 0.0);

double? get page	// 当前页面的精确位置，可能包含小数部分，如 1.5 表示在第1页和第2页之间
                  // 必须在 PageView 构建完成后才能访问

// 核心方法
  
// 动画地切换到指定页面
animateToPage(int page, {required Duration duration, required Curve curve})
  
// 无动画地直接跳转到指定页面
jumpToPage(int page)

// 动画地切换到下一页
nextPage({required Duration duration, required Curve curve})

// 动画地切换到上一页
previousPage({required Duration duration, required Curve curve})

简单使用示例【--->c35/pageview_demo.dart<---】运行效果：

💡 Tips ：滑动几页后，切换Tab，再切回来，发现会从第一页开始，即重新创建。如果想 保存页面状态 ，子页面需混入 AutomaticKeepAliveClientMixin 并重写 wantKeepAlive 返回 true ❗️

3.5.2. 源码剖析

😄 没啥新意，默认构造是 SliverChildListDelegate ，builder() 则是 SliverChildBuilderDelegate ，前者一次性构建所有的子Widget，后者动态懒加载。PageView 继承 StatefulWidget ，直接看 _PageViewState.build() ：

SliverFillViewport 继承 StatelessWidget ，直接看 build() ：

• _SliverFractionalPadding：负责根据视口大小动态计算并添加内边距，让SliverFillViewport的首尾子项能够居中显示。
• _SliverFillViewportRenderObjectWidget ：Widget 和 RenderObject间的桥梁，负责创建和管理RenderSliverFillViewport 渲染对象。

RenderSliverFillViewport 的父类 RenderSliverFixedExtentBoxAdaptor 实现了 performLayout() ，关键代码：

abstract class RenderSliverFixedExtentBoxAdaptor extends RenderSliverMultiBoxAdaptor {
  @override
  void performLayout() {
    // ① 初始化阶段
    
    // 获取约束信息
    final SliverConstraints constraints = this.constraints;
    childManager.didStartLayout();
    
    // 计算关键偏移量
    final double scrollOffset = constraints.scrollOffset + constraints.cacheOrigin;
    final double targetEndScrollOffset = scrollOffset + remainingExtent;

    // ② 索引计算阶段
    
    // 获取约束信息
    final SliverConstraints constraints = this.constraints;
    childManager.didStartLayout();
    
    // 计算关键偏移量
    final double scrollOffset = constraints.scrollOffset + constraints.cacheOrigin;
    final double targetEndScrollOffset = scrollOffset + remainingExtent;

    // ③ 垃圾回收阶段
    // 计算需要布局的子组件索引范围
    final int firstIndex = getMinChildIndexForScrollOffset(scrollOffset, -1);
    final int? targetLastIndex = getMaxChildIndexForScrollOffset(targetEndScrollOffset, -1);

    // ④ 子组件布局阶段
    // 向前布局：清理不再需要的子组件
    final int leadingGarbage = calculateLeadingGarbage(firstIndex: firstIndex);
    final int trailingGarbage = calculateTrailingGarbage(lastIndex: targetLastIndex);
    collectGarbage(leadingGarbage, trailingGarbage);
    // 向后布局：从 firstChild 向前插入和布局子组件
    for (int index = indexOf(firstChild!) - 1; index >= firstIndex; --index) {
      final RenderBox? child = insertAndLayoutLeadingChild(_getChildConstraints(index));
      childParentData.layoutOffset = indexToLayoutOffset(-1, index);
    }

    // ⑤ 几何信息结算阶段：从 trailingChildWithLayout 向后插入和布局子组件
    for (int index = indexOf(trailingChildWithLayout!) + 1; index <= targetLastIndex; ++index) {
      RenderBox? child = insertAndLayoutChild(_getChildConstraints(index), after: trailingChildWithLayout);
      childParentData.layoutOffset = indexToLayoutOffset(-1, index);
    }

    // ⑥ 完成阶段
    // 计算各种范围信息
    final double paintExtent = calculatePaintOffset(constraints, from: leadingScrollOffset, to: trailingScrollOffset);
    final double cacheExtent = calculateCacheOffset(constraints, from: leadingScrollOffset, to: trailingScrollOffset);
    
    // 设置最终的几何信息
    geometry = SliverGeometry(
      scrollExtent: estimatedMaxScrollOffset,
      paintExtent: paintExtent,
      cacheExtent: cacheExtent,
      maxPaintExtent: estimatedMaxScrollOffset,
      hasVisualOverflow: ...,
    );
  }
}

4. 高级组件 & 自定义滚动

Sliver 是 Flutter 为了解决 大量内容滚动时的性能问题 而设计的 视口驱动渲染机制 ，它 只构建和渲染用户当前能看到的部分 ，相比 普通Widget 会一次性构建所有内容导致内存爆炸和性能问题要高效得多。

4.1. CustomScrollView

用于 构建自定义、复杂的滚动视图 ，它本身不直接决定其子项的布局，而是创建了一个可以容纳 Sliver 系列组件的滚动视口 (Viewport)。继承自 ScrollView ，只是重写了 buildSlivers() ，返回构造参数传入的 slivers - Sliver组件列表。

4.2. SliverPersistentHeader

Persistent -"持久化 "，该组件可以 根据滚动位置改变自身大小 ，并且可以选择性地 "钉 " 在视口(Viewport) 顶部 的 Sliver 。当它滚动到屏幕边缘时，它不会像普通列表项那样完全滚出屏幕，而是可以收缩到一个最小高度并"固定在那里"，直到被下一个 SliverPersistentHeader 或者滚动会顶部所代替。😄 其实就很常说的"吸顶"组件。

class SliverPersistentHeader extends StatelessWidget {
  const SliverPersistentHeader({
    Key? key,
    required this.delegate,	 // 头部布局的委托对象，包括：最大/最小高度和构建逻辑
    this.pinned = false,	// 是否固定在视口顶部 (滚动也不消失)
    this.floating = false,	// 是否有浮动效果 (用户反向滚动会立即重新出现)
  });
}

SliverPersistentHeaderDelegate 是一个抽象类，需继承并实现下述方法：

@override
double get minExtent => 60.0; // 最小高度

@override
double get maxExtent => 200.0; // 最大高度

// 返回头部的 UI 组件，参数：
// 「shrinkOffset」-头部从最大高度 maxExtent 收缩的距离，可能范围[0.0, maxExtent-minExtent]
// 当 shrinkOffset 为 0 时，头部处于完全展开状态，当达到最大值时，头部处于完全收缩状态
// 可以利用这个值来实现各种动画效果，如 (透明度、位移、大小锁房)
//
//「overlapsContent」该 Header 当前是否与滚动视图中的主要内容重写。
// 通常在 pinned 为 true 时，Header 下方的内容开始滚动到其后面时，此值为 true。
@override
Widget build(BuildContext context, double shrinkOffset, bool overlapsContent) {
  return Container(/* 你的头部内容 */);
}

@override
bool shouldRebuild(covariant SliverPersistentHeaderDelegate oldDelegate) {
  // 返回是否需要重建
  return true;
}

写个简单使用示例【--->c35/sliver_persistent_header_demo.dart<---】运行效果：

😶 简单传几个参数就实现了吸顶和浮动效果，跟下源码，看下是怎么做到的，build() 根据不同的值情况返回不同的 渲染对象 ，跟下对应的 performLayout() 的核心代码：

从下往上看，先是 _SliverScrollingPersistentHeader → RenderSliverScrollingPersistentHeader：

接着是 _SliverFloatingPersistentHeader → RenderSliverFloatingPersistentHeader：

再接着 _SliverPinnedPersistentHeader → RenderSliverPinnedPersistentHeader：

最后是 _SliverFloatingPinnedPersistentHeader → RenderSliverFloatingPinnedPersistentHeader ，浮动效果来自于父类 RenderSliverFloatingPersistentHeader ，吸顶效果则是重写 updateGeometry() 实现：

4.3. SliverAppBar

基于 SliverPersistentHeader 实现的具体 应用栏组件 (内置应用的常见功能，如标题、操作按钮、背景等)，开箱即用，相比起手写一坨 _SliverHeaderDelegate ，直接配置几个属性即可轻松实现相同的效果：floating 、pinned 就不用说了，还有这些：

• snap：是否启用快速收缩/展开动画。
• expandedHeight：完全展开时的高度，通常和 flexibleSpace 来显示背景内容，null 时使用默认工具栏高度。
• collapsedHeight：收缩时的最小高度，不写默认为 toolbarHeight + bottom?.preferredSize.height。
• stretch ：bool，是否启用拉伸效果，默认false， 禁用拉伸效果，应用栏保持固定大小。设为true，当用户向下过度滚动时，应用栏会被拉伸放大。开启后的视觉效果：下拉时应用栏的 flexibleSpace 区域会被拉伸，拉伸后背景内容会按比例放大。
• stretchTriggerOffset ：double，设置触发 onStretchTrigger 回调 (拉伸回弹) 需要的过度滚动距离，默认100像素，计算方式: 从应用栏的自然位置开始计算向下的拖拽距离。
• onStretchTrigger ：Future ，拉伸触发的异步回调，用户拖拽超过阈值且松手时 (拉伸距离达到stretchTriggerOffset)，注意，只在 stretch = true 时有效。

写个简单使用示例【--->c35/sliver_app_bar_demo.dart<---】运行效果：

跟下源码，内部使用 _SliverAppBarDelegate 来实现 SliverPersistentHeaderDelegate：

4.4. NestedScrollView

当你在一个可滚动组件中放入一个"同方向 "的可滚动组件，通常会遇到两大类问题："手势冲突 " & "布局约束问题 "。比如最经典的例子：两个垂直滚动的ListView嵌套，会怎么样？

先是会报错：xxx has an unbounded height，尝试添加 固定高度 约束后。只有内部的列表在滑动，当它滚动尽头时，滚动事件并不会自动传递给外部的ListView。(🐶一种不太好的解法，内部ListView设置：shrinkWrap:true + physics: NeverScrollableScrollPhysics() ，即收缩+禁止滚动，仅适用于列表项少且固定的情况)。

而 NestedScrollView 就是为了解决这两个问题而设计出来的：

• 通过 滚动协调器 ( _NestedScrollCoordinator) 统一管理和分配滚动事件，消除竞争.
• 为 body 提供了有界约束，使其内部的可滚动组件可以正常布局。

4.4.1. API 详解

构造方法：

class NestedScrollView extends StatefulWidget {
  const NestedScrollView({
    super.key, // Widget的唯一标识符，用于性能优化和状态保持
    this.controller, // 外层滚动控制器，用于程序化控制滚动位置和监听滚动事件
    this.scrollDirection = Axis.vertical, // 滚动方向，默认垂直滚动（仅影响外层滚动）
    this.reverse = false, // 是否反向滚动，true时从底部开始滚动（仅影响外层滚动）
    this.physics, // 滚动物理效果，控制弹性、边界行为等滚动特性（仅影响外层滚动）
    required this.headerSliverBuilder, // 头部构建器，返回头部Sliver组件列表（如SliverAppBar）
    required this.body, // 主体内容Widget，通常是TabBarView或其他滚动组件
    this.dragStartBehavior = DragStartBehavior.start, // 拖拽开始行为，控制手势识别的起始时机
    this.floatHeaderSlivers = false, // 是否优先浮动头部Sliver，true时向下滚动优先展开头部
    this.clipBehavior = Clip.hardEdge, // 内容裁剪行为，控制超出边界内容的显示方式
    this.restorationId, // 状态恢复ID，用于应用重启时恢复滚动位置
    this.scrollBehavior, // 滚动行为配置，定义滚动样式、物理效果等平台相关行为
  });

核心属性：

• headerSliverBuilder ：NestedScrollViewHeaderSliversBuilder → List Function(BuildContext context, bool innerBoxIsScrolled)，用于构建 头部 的 Sliver 组件列表。第二个参数的值代表"嵌套的滑动内容是否已经达到顶部，开始滑动"。
• body ：Widget ，主体部分，通常是一个包含可滚动内容的组件，最常见的是 TabBarView ，其每个子页面都是一个 ListView 或 CustomScrollView，这部分内容构成了 "内部滚动视图"。
• controller ：ScrollController ，控制外层滚动，内层滚动由 PrimaryScrollController 自动管理。
• floatHeaderSlivers：是否优先浮动头部Slivers，默认 false，设为 true，向下滚动会优先展开头部。
• 注：scrollDirection、reverse、physics 只影响外层滚动视图，内层滚动视图需要在body中单独配置。

最简单的使用代码示例 (注意headerSliverBuilder列表的元素必须为Sliver组件，如：SliverList)：

 NestedScrollView(
  // 头部
  headerSliverBuilder: (BuildContext context, bool innerBoxIsScrolled) {
    return <Widget>[
      SliverToBoxAdapter(
        child: Container(height: 200, color: Colors.orange),
      ),
    ];
  },
  // 主体
  body: Container(
    color: Colors.orange.shade50,
    child: ListView.builder(
      padding: const EdgeInsets.all(16),
      itemCount: 30,
      itemBuilder: (context, index) => Card(
        margin: const EdgeInsets.only(bottom: 8),
        child: ListTile(
          leading: CircleAvatar(
            backgroundColor: Colors.orange,
            child: Text('${index + 1}'),
          ),
          title: const Text('这是主体内容 (body)'),
          subtitle: Text('列表项 ${index + 1}'),
        ),
      ),
    ),
  ),
),

运行效果：

尝试 SliverAppBar：

 headerSliverBuilder: (BuildContext context, bool innerBoxIsScrolled) {
  return <Widget>[
    // 🎨 可折叠的 SliverAppBar
    SliverAppBar(
      title: const Text('📱 SliverAppBar 示例'),
      backgroundColor: Colors.purple,
      foregroundColor: Colors.white,
      floating: true,
      pinned: true,
      snap: true,
      expandedHeight: 200.0,
      // 🎭 弹性空间 - 展开时显示的内容
      flexibleSpace: FlexibleSpaceBar(
        title: const Text('可折叠标题'),
        background: Container(
          color: Colors.purple,
          child: Center(
            child: Icon(Icons.star, size: 80, color: Colors.white.withOpacity(0.3)),
          ),
        ),
      ),
      // 根据内容滚动状态决定是否显示阴影
      forceElevated: innerBoxIsScrolled,
    ),
  ];
},

运行效果：

在 NestedScrollView 中，使用 floating、pinned、snap 等属性的 SliverAppBar 时，会产生 "重叠" 问题：

AppBar 在展开/收起过程中可能遮挡内容、内层滚动视图的内容可能显示在 AppBar 下方、滚动对齐不正确。

为了避免 body 的初始内容被 Header 遮挡，你需要使用这两对组合：

• SliverOverlapInjector ：将它作为 headerSliverBuilder 返回的 Sliver 列表中的一个父组件，包裹住其他 Sliver。它会捕获其子 Sliver (如 SliverAppBar) 所占据的重叠量。
• SliverOverlapInjector ：在 body 内部的可滚动视图，将它作为第一个Sliver，它会将SliverOverlapAbsorber 捕获到的重叠量作为内边距，应用到其内部，从而将 body内容往下挪，避免被遮挡。

用法示例 (注：两者必须使用同一个 SliverOverlapAbsorberHandle)：

// 在 headerSliverBuilder 中，套Sliver组件
SliverOverlapAbsorber(
  handle: NestedScrollView.sliverOverlapAbsorberHandleFor(context),
  sliver: SliverAppBar(...), // 包装会产生重叠的组件
)

// 在 body 的每个滚动视图中，在 TabBarView 的每个 Tab 中都要使用 SliverOverlapInjector
SliverOverlapInjector(
  handle: NestedScrollView.sliverOverlapAbsorberHandleFor(context),
)

另外，你可能发现滑动后，且Tab到别的页面，回来后，第一页的 滑动距离没有保持 ，给 CustomScrollView 的 key 属性设置一个 PageStorageKey 的对象 (唯一标识) 即可解决。原理是 ScrollPosition 类中通过 PageStorage 组件进行滑动进度的读写。

💡 Tips: 在 body 的 TabBarView 中为每个 ListView 都提供了自己的 ScrollController，会导致NestedScrollView 的协调机制 失效！

4.4.2. 源码剖析

核心大脑 _NestedScrollCoordinator (协调器)：

class _NestedScrollCoordinator implements ScrollActivityDelegate, ScrollHoldController { ... }

它管理两个独立的 ScrollController： _outerController 和 _innerController：

协调内外滚动位置的同步、处理手势分发和滚动事件。滚动分发的核心算法 (用户开始拖拽-drag() → 拖拽更新-applyUserOffset() )：

• 向上拖拽 (delta < 0)：优先消除内层 overscroll → 然后滚动外层 → 最后滚动内层。
• 向下拖拽 (delta > 0)：根据 floatHeaderSlivers 决定是否优先滚动外层。

然后是 惯性滚动处理，当手指离开屏幕：

然后是关键的 _getMetrics() ，它创建统一的滚动指标，让内外两个独立的滚动视图在物理模拟时表现得像一个整体。最后是为了解决 SliverAppBar 重叠问题的 SliverOverlapAbsorber/Injector 机制：

在 RenderSliverOverlapInjector.performLayout() 中：

画个调用时序图帮助理解：

用户手势 → NestedScrollCoordinator → 智能分析 → 分发给合适的滚动组件

4.5. Notification通知机制

ScrollNotification 是一个抽象类，用于 在滚动相关事件发生时发出通知，它是整个滚动通知系统的核心基类。

abstract class ScrollNotification extends LayoutChangedNotification with ViewportNotificationMixin {
  ScrollNotification({
    required this.metrics,
    required this.context,
  });
  
  final ScrollMetrics metrics;  // 滚动指标信息
  final BuildContext? context;  // 触发通知的组件上下文
}

核心属性：

• metrics：ScrollMetrics，描述滚动视图内容的详细信息，包含：pixels(当前位置)、minScrollExtent(最小滚动范围)、maxScrollExtent(最大滚动范围)、viewportDimension(视口尺寸)等。
• context：触发此通知的 Widget 的构建上下文，可用于查找滚动组件的渲染对象，确定视口大小等。
• depth：继承自 ViewportNotificationMixin，表示通知冒泡经过的视口数量，通常监听器只响应 depth 为 0 的通知 (本地通知)。

它的几个字类：

// 开始滚动
class ScrollStartNotification extends ScrollNotification {
  final DragStartDetails? dragDetails; // 拖拽开始详情
}

// 滚动更新
class ScrollUpdateNotification extends ScrollNotification {
  final DragUpdateDetails? dragDetails; // 拖拽更新详情
  final double? scrollDelta; // 滚动距离增量
}

// 过渡滚动
class OverscrollNotification extends ScrollNotification {
  final double overscroll; // 过度滚动的像素数
  final double velocity;   // 滚动速度
}

// 滚动结束
class ScrollEndNotification extends ScrollNotification {
  final DragEndDetails? dragDetails; // 拖拽结束详情
}

// 用户滚动方向改变
class UserScrollNotification extends ScrollNotification {
  final ScrollDirection direction; // 滚动方向
}

// 用户停止交互
class UserScrollNotification extends ScrollNotification {
  final ScrollDirection direction;	// 处于 idle
}

使用示例：

// 使用 NotificationListener<ScrollNotification> 包裹滑动视图进行监听
NotificationListener<ScrollNotification>(
  onNotification: (ScrollNotification notification) {
    if (notification is ScrollUpdateNotification) {
      print('滚动位置: ${notification.metrics.pixels}');
    }
    return false; // 不消费通知，继续向上传播
  },
  child: ListView(...),
)

相比 ScrollController ，ScrollNotification 的优势在于 "解耦 " 和 "事件驱动"，具体表现在：

• 任何父组件都可以通过 NotificationListener 监听到其子孙树中任何滚动组件的事件，无需获取该滚动组件的 ScrollController，这使得父组件与子滚动组件间没有强依赖关系，代码更清晰、更易维护。
• NotificationListener 提供了丰富且详细的事件类型，让你能精确地知道滚动的具体阶段。而ScrollController.addListener() 只有一个通用的"滚动变动"通知，你无法直接区分是用户拖动、惯性滑动还是代码驱动的滚动。
• ScrollNotification 是一种标准的、自下而上 的"事件冒泡机制 "，而 ScrollController 则主要用于自上而下的 控制，监听只是其附加功能。

😁 ScrollNotification 的事件来源可以分为两种：

// 用户手势交互

1. 用户拖拽屏幕 -> GestureDetector 识别
2. 手势生成 DragStartDetails, DragUpdateDetails, DragEndDetails
3. 这些手势信息传递给 ScrollActivity

// ② 程序化滚动

// ScrollController 主动调用
controller.animateTo(100.0); // 程序控制滚动
controller.jumpTo(200.0);    // 立即跳转

然后 Scrollable 是所有滚动组件的基础，其内部事件生成流程：

• 手势识别 : RawGestureDetector 识别用户手势
• 活动创建 : 根据手势类型创建不同的 ScrollActivity (DragScrollActivity -用户拖拽、DrivenScrollActivity -程序滚动、BallisticScrollActivity-惯性滚动)。
• 位置更新: ScrollPosition 根据活动更新滚动位置。
• 通知分发 : ScrollPosition 创建并分发 ScrollNotification。

ScrollPosition 是事件创建的核心，关键源码：

abstract class ScrollPosition {

  /// 开始滚动时调用
  void didStartScroll() {
    // 实际上是通过 activity 来分发通知的！
    activity!.dispatchScrollStartNotification(copyWith(), context.notificationContext);
  }

  /// 滚动更新时调用
  void didUpdateScrollPositionBy(double delta) {
    // 通过 activity 分发滚动更新通知
    activity!.dispatchScrollUpdateNotification(copyWith(), context.notificationContext!, delta);
  }

  /// 滚动结束时调用
  void didEndScroll() {
    // 通过 activity 分发滚动结束通知，并保存偏移量
    activity!.dispatchScrollEndNotification(copyWith(), context.notificationContext!);
    saveOffset();
    if (keepScrollOffset) {
      saveScrollOffset();
    }
  }

  /// 过度滚动时调用
  void didOverscrollBy(double value) {
    assert(activity!.isScrolling);
    // 通过 activity 分发过度滚动通知
    activity!.dispatchOverscrollNotification(copyWith(), context.notificationContext!, value);
  }

  /// 用户滚动方向改变时调用
  void didUpdateScrollDirection(ScrollDirection direction) {
    // 直接创建 UserScrollNotification 并分发
    UserScrollNotification(
      metrics: copyWith(), 
      context: context.notificationContext!, 
      direction: direction
    ).dispatch(context.notificationContext);
  }

  /// 滚动指标更新时调用
  void didUpdateScrollMetrics() {
    assert(SchedulerBinding.instance.schedulerPhase != SchedulerPhase.persistentCallbacks);
    assert(_haveScheduledUpdateNotification);
    _haveScheduledUpdateNotification = false;
    if (context.notificationContext != null) {
      // 分发滚动指标变化通知
      ScrollMetricsNotification(
        metrics: copyWith(), 
        context: context.notificationContext!
      ).dispatch(context.notificationContext);
    }
  }
}

接着是 事件传播的链路：

ScrollPosition.didUpdateScrollPositionBy()
   ↓
ScrollPosition._dispatch(ScrollUpdateNotification(...))
   ↓
BuildContext.dispatchNotification(notification)
   ↓
Element._notificationTree.dispatch(notification)
   ↓
向上遍历 Element 树
   ↓
查找 NotificationListener<ScrollNotification>
   ↓
执行 onNotification 回调
   ↓
根据返回值决定是否继续传播