在Flutter中，ScrollController可以精确地控制和管理滚动行为。通过ScrollController，可以监听滚动的位置、速度，甚至可以在用户滚动时触发自定义的动作。此外，ScrollController还提供了对滚动位置的直接控制，可以编程地滚动到特定位置。
ScrollController构造函数
ScrollController({double initialScrollOffset = 0.0,this.keepScrollOffset = true,this.debugLabel,this.onAttach,this.onDetach,}) : _initialScrollOffset = initialScrollOffset {if (kFlutterMemoryAllocationsEnabled) {ChangeNotifier.maybeDispatchObjectCreation(this);}} ScrollController常用的属性和方法
- offset：可滚动组件当前的滚动位置。
- jumpTo(double offset)、animateTo(double offset, {required Duration duration, required Curve curve,})：这两个方法用于跳转到指定的位置，它们不同之处在于，后者在跳转时会执行一个动画，而前者不会。
滚动监听
ScrollController间接继承自Listenable，可以根据ScrollController来监听滚动事件
final ScrollController _scrollController = ScrollController();@overridevoid initState() {super.initState();_scrollController.addListener(() {});}实例
创建一个ListView，当滚动位置发生变化时，记录滑动位置：
final ScrollController _scrollController = ScrollController();@overridevoid initState() {super.initState();_scrollController.addListener(() {print("location:${_scrollController.offset}");setState(() {offset = _scrollController.offset;});});}body: ListView(scrollDirection: scrollDirection,controller: _scrollController,children: randomList.map<Widget>((data) {return Padding(padding: const EdgeInsets.all(8),child: _getRow(data[0], math.max(data[1].toDouble(), 50.0)),);}).toList(),)TextButton(onPressed: () {},child: Text("position: ${offset.floor()}"),) 
通过animateTo方法回到顶部。
TextButton(onPressed: () {_scrollController.animateTo(0,duration: const Duration(seconds: 1),//动画时间是1秒，curve: Curves.bounceInOut);//动画曲线},child: Text("回到顶部"),
)滚动位置恢复 (copy 6.4 滚动监听及控制 | 《Flutter实战·第二版》 (flutterchina.club))
PageStorage是一个用于保存页面(路由)相关数据的组件，它并不会影响子树的UI外观，其实，PageStorage是一个功能型组件，它拥有一个存储桶（bucket），子树中的Widget可以通过指定不同的PageStorageKey来存储各自的数据或状态。
每次滚动结束，可滚动组件都会将滚动位置offset存储到PageStorage中，当可滚动组件重新创建时再恢复。如果ScrollController.keepScrollOffset为false，则滚动位置将不会被存储，可滚动组件重新创建时会使用ScrollController.initialScrollOffset；ScrollController.keepScrollOffset为true时，可滚动组件在第一次创建时，会滚动到initialScrollOffset处，因为这时还没有存储过滚动位置。在接下来的滚动中就会存储、恢复滚动位置，而initialScrollOffset会被忽略。
当一个路由中包含多个可滚动组件时，如果你发现在进行一些跳转或切换操作后，滚动位置不能正确恢复，这时你可以通过显式指定PageStorageKey来分别跟踪不同的可滚动组件的位置，如：
ListView(key: PageStorageKey(1), ... );
...
ListView(key: PageStorageKey(2), ... );不同的PageStorageKey，需要不同的值，这样才可以为不同可滚动组件保存其滚动位置。
注意：一个路由中包含多个可滚动组件时，如果要分别跟踪它们的滚动位置，并非一定就得给他们分别提供PageStorageKey。这是因为Scrollable本身是一个StatefulWidget，它的状态中也会保存当前滚动位置，所以，只要可滚动组件本身没有被从树上移除（detach），那么其State就不会销毁(dispose)，滚动位置就不会丢失。只有当Widget发生结构变化，导致可滚动组件的State销毁或重新构建时才会丢失状态，这种情况就需要显式指定PageStorageKey，通过PageStorage来存储滚动位置，一个典型的场景是在使用TabBarView时，在Tab发生切换时，Tab页中的可滚动组件的State就会销毁，这时如果想恢复滚动位置就需要指定PageStorageKey。
ScrollPosition (copy 6.4 滚动监听及控制 | 《Flutter实战·第二版》 (flutterchina.club))
ScrollPosition是用来保存可滚动组件的滚动位置的。一个ScrollController对象可以同时被多个可滚动组件使用，ScrollController会为每一个可滚动组件创建一个ScrollPosition对象，这些ScrollPosition保存在ScrollController的positions属性中（List<ScrollPosition>）。
final List<ScrollPosition> _positions = <ScrollPosition>[];ScrollPosition是真正保存滑动位置信息的对象，offset只是一个便捷属性：
double get offset => position.pixels;一个ScrollController虽然可以对应多个可滚动组件，但是有一些操作，如读取滚动位置offset，则需要一对一！但是我们仍然可以在一对多的情况下，通过其他方法读取滚动位置，举个例子，假设一个ScrollController同时被两个可滚动组件使用，那么我们可以通过如下方式分别读取他们的滚动位置：
...
controller.positions.elementAt(0).pixels
controller.positions.elementAt(1).pixels
... 我们可以通过controller.positions.length来确定controller被几个可滚动组件使用。
ScrollPosition有两个常用方法：animateTo() 和 jumpTo()，它们是真正来控制跳转滚动位置的方法，ScrollController的这两个同名方法，内部最终都会调用ScrollPosition的。
#ScrollPosition
@overrideFuture<void> animateTo(double to, {required Duration duration,required Curve curve,});#ScrollPosition @overridevoid jumpTo(double value);#ScrollController
Future<void> animateTo(double offset, {required Duration duration,required Curve curve,}) async {assert(_positions.isNotEmpty, 'ScrollController not attached to any scroll views.');await Future.wait<void>(<Future<void>>[for (int i = 0; i < _positions.length; i += 1) _positions[i].animateTo(offset, duration: duration, curve: curve),]);}#ScrollController void jumpTo(double value) {assert(_positions.isNotEmpty, 'ScrollController not attached to any scroll views.');for (final ScrollPosition position in List<ScrollPosition>.of(_positions)) {position.jumpTo(value);}}ScrollController控制原理 (copy 6.4 滚动监听及控制 | 《Flutter实战·第二版》 (flutterchina.club))
ScrollController的三个重要方法：
ScrollPosition createScrollPosition(ScrollPhysics physics,ScrollContext context,ScrollPosition oldPosition);
void attach(ScrollPosition position) ;
void detach(ScrollPosition position) ;当ScrollController和可滚动组件关联时，可滚动组件首先会调用ScrollController的createScrollPosition()方法来创建一个ScrollPosition来存储滚动位置信息，接着，可滚动组件会调用attach()方法，将创建的ScrollPosition添加到ScrollController的positions属性中，这一步称为“注册位置”，只有注册后animateTo() 和 jumpTo()才可以被调用。
当可滚动组件销毁时，会调用ScrollController的detach()方法，将其ScrollPosition对象从ScrollController的positions属性中移除，这一步称为“注销位置”，注销后animateTo() 和 jumpTo() 将不能再被调用。
需要注意的是，ScrollController的animateTo() 和 jumpTo()内部会调用所有ScrollPosition的animateTo() 和 jumpTo()，以实现所有和该ScrollController关联的可滚动组件都滚动到指定的位置。
滚动监听
String notify = "";@overrideWidget build(BuildContext context) {return Scaffold(appBar: AppBar(title: const Text("ScrollToIndexDemoPage"),),body: NotificationListener(onNotification: (dynamic notification) {String notify = "";if (notification is ScrollEndNotification) {notify = "ScrollEnd";} else if (notification is ScrollStartNotification) {notify = "ScrollStart";} else if (notification is UserScrollNotification) {notify = " UserScroll";} else if (notification is ScrollUpdateNotification) {notify = "ScrollUpdate";}setState(() {this.notify = notify;});return false;},child: ListView(scrollDirection: scrollDirection,controller: _scrollController,children: randomList.map<Widget>((data) {return Padding(padding: const EdgeInsets.all(8),child: _getRow(data[0], math.max(data[1].toDouble(), 50.0)),);}).toList(),)),persistentFooterButtons: <Widget>[const SizedBox(width: 0.3, height: 30.0),TextButton(onPressed: () {},child: Text(notify),)],);}ScrollNotification是滚动事件通知，ScrollEndNotification、ScrollStartNotification、UserScrollNotification、ScrollUpdateNotification都是它的子类。
abstract class ScrollNotification extends LayoutChangedNotification with ViewportNotificationMixin {/// Initializes fields for subclasses.ScrollNotification({required this.metrics,required this.context,});/// A description of a [Scrollable]'s contents, useful for modeling the state/// of its viewport.final ScrollMetrics metrics;/// The build context of the widget that fired this notification.////// This can be used to find the scrollable's render objects to determine the/// size of the viewport, for instance.final BuildContext? context;@overridevoid debugFillDescription(List<String> description) {super.debugFillDescription(description);description.add('$metrics');}
}
mixin ScrollMetrics {/// Creates a [ScrollMetrics] that has the same properties as this object.////// This is useful if this object is mutable, but you want to get a snapshot/// of the current state.////// The named arguments allow the values to be adjusted in the process. This/// is useful to examine hypothetical situations, for example "would applying/// this delta unmodified take the position [outOfRange]?".ScrollMetrics copyWith({double? minScrollExtent,double? maxScrollExtent,double? pixels,double? viewportDimension,AxisDirection? axisDirection,double? devicePixelRatio,}) {return FixedScrollMetrics(minScrollExtent: minScrollExtent ?? (hasContentDimensions ? this.minScrollExtent : null),maxScrollExtent: maxScrollExtent ?? (hasContentDimensions ? this.maxScrollExtent : null),pixels: pixels ?? (hasPixels ? this.pixels : null),viewportDimension: viewportDimension ?? (hasViewportDimension ? this.viewportDimension : null),axisDirection: axisDirection ?? this.axisDirection,devicePixelRatio: devicePixelRatio ?? this.devicePixelRatio,);} pixels：当前滚动位置。
maxScrollExtent：最大可滚动长度。
extentBefore：滑出ViewPort顶部的长度；此示例中相当于顶部滑出屏幕上方的列表长度。
extentInside：ViewPort内部长度；此示例中屏幕显示的列表部分的长度。
extentAfter：列表中未滑入ViewPort部分的长度；此示例中列表底部未显示到屏幕范围部分的长度。
atEdge：是否滑到了可滚动组件的边界（此示例中相当于列表顶或底部）。
虽然 Flutter 官方提供了 ScrollController，调用相关方法可以滚动到指定偏移处，但是官方没有提供滚动到指定下标位置的功能。
scroll_to_index
我们可以使用三方库实现动到指定下标位置的功能。
import 'dart:math' as math;import 'package:flutter/material.dart';
import 'package:scroll_to_index/scroll_to_index.dart';class ScrollToIndexDemoPage extends StatefulWidget {const ScrollToIndexDemoPage({super.key});@override_ScrollToIndexDemoPageState createState() => _ScrollToIndexDemoPageState();
}class _ScrollToIndexDemoPageState extends State<ScrollToIndexDemoPage> {static const maxCount = 100;/// pub scroll_to_index 项目的 controllerAutoScrollController? controller;final ScrollController _scrollController = ScrollController();final random = math.Random();final scrollDirection = Axis.vertical;late List<List<int>> randomList;//双获取偏移=>位置.像素；double offset = 0;String notify = "";@overridevoid initState() {super.initState();controller = AutoScrollController(viewportBoundaryGetter: () =>Rect.fromLTRB(0, 0, 0, MediaQuery.paddingOf(context).bottom),axis: scrollDirection);///一个 index 和 item 高度的数组randomList = List.generate(maxCount,(index) => <int>[index, (1000 * random.nextDouble()).toInt()]);_scrollController.addListener(() {print("location:${_scrollController.offset}");setState(() {offset = _scrollController.offset;});});}Widget _getRow(int index, double height) {return _wrapScrollTag(index: index,child: Container(padding: const EdgeInsets.all(8),alignment: Alignment.topCenter,height: height,decoration: BoxDecoration(border: Border.all(color: Colors.lightBlue, width: 4),borderRadius: BorderRadius.circular(12)),child: Text('index: $index, height: $height'),));}Widget _wrapScrollTag({required int index, required Widget child}) =>AutoScrollTag(key: ValueKey(index),controller: controller!,index: index,highlightColor: Colors.black.withOpacity(0.1),child: child,);@overrideWidget build(BuildContext context) {return Scaffold(appBar: AppBar(title: const Text("ScrollToIndexDemoPage"),),body: NotificationListener(onNotification: (dynamic notification) {String notify = "";if (notification is ScrollEndNotification) {notify = "ScrollEnd";} else if (notification is ScrollStartNotification) {notify = "ScrollStart";} else if (notification is UserScrollNotification) {notify = " UserScroll";} else if (notification is ScrollUpdateNotification) {notify = "ScrollUpdate";}setState(() {this.notify = notify;});return false;},child: ListView(scrollDirection: scrollDirection,controller: controller,children: randomList.map<Widget>((data) {return Padding(padding: const EdgeInsets.all(8),child: _getRow(data[0], math.max(data[1].toDouble(), 50.0)),);}).toList(),)),persistentFooterButtons: <Widget>[TextButton(onPressed: () async {///滑动到第13个的位置await controller!.scrollToIndex(13, preferPosition: AutoScrollPosition.begin);controller!.highlight(13);},child: const Text("Scroll to 13"),),// const SizedBox(width: 0.3, height: 30.0),// TextButton(// onPressed: () {// // _scrollController.animateTo(0,// // duration: const Duration(seconds: 1),// // curve: Curves.bounceInOut);// // // setState(() {// // // entries = entries;// // // });// },// child: Text("position: ${offset.floor()}"),// ),// const SizedBox(width: 0.3, height: 30.0),// TextButton(// onPressed: () {// _scrollController.animateTo(0,// duration: const Duration(seconds: 1),// curve: Curves.bounceInOut);// },// child: Text("回到顶部"),// ),// const SizedBox(width: 0.3, height: 30.0),// TextButton(// onPressed: () {},// child: Text(notify),// )],);}
}
AutoScrollTag 是一个可以包裹在任意行级 widget 中的组件，它会接收控制器和索引值，并在需要时高亮显示。
AutoScrollController 则负责整个滚动操作，包括监听和触发滚动到指定索引的命令。
对于有固定行高的情况，可以设置 suggestedRowHeight 参数以提高滚动效率。
通过 viewportBoundaryGetter 自定义视口边界，以及选择垂直或水平滚动方向。
