滚动控制的需求
页面滚动时,经常需要做这些事:监听滚动位置显示回到顶部按钮、检测是否滚动到底部触发加载更多、点击某个按钮平滑滚动到指定位置。ScrollController 就是做这些的。
基本结构
final _controller = ScrollController();
@override
void initState() {
super.initState();
_controller.addListener(() {
// 监听滚动位置
final current = _controller.position.pixels;
final max = _controller.position.maxScrollExtent;
});
}
@override
void dispose() {
_controller.dispose(); // 必须释放
super.dispose();
}
核心属性和方法
常用属性
| 属性 | 类型 | 说明 |
|---|---|---|
offset / pixels |
double | 当前滚动位置 |
position |
ScrollPosition | 滚动位置对象 |
positions |
Iterable | 所有滚动位置 |
hasClients |
bool | 是否已绑定滚动组件 |
常用方法
| 方法 | 说明 |
|---|---|
addListener(callback) |
监听滚动事件 |
removeListener(callback) |
移除监听 |
animateTo(offset, duration, curve) |
平滑滚动到指定位置 |
jumpTo(offset) |
直接跳转到指定位置 |
dispose() |
释放资源 |
实际应用场景
回到顶部按钮
class ScrollToTopPage extends StatefulWidget {
@override
State<ScrollToTopPage> createState() => _ScrollToTopPageState();
}
class _ScrollToTopPageState extends State<ScrollToTopPage> {
final _controller = ScrollController();
bool _showButton = false;
@override
void initState() {
super.initState();
_controller.addListener(() {
// 滚动超过 200px 显示按钮
setState(() {
_showButton = _controller.position.pixels > 200;
});
});
}
@override
void dispose() {
_controller.dispose();
super.dispose();
}
void _scrollToTop() {
_controller.animateTo(
0,
duration: const Duration(milliseconds: 500),
curve: Curves.easeInOut,
);
}
@override
Widget build(BuildContext context) {
return Stack(
children: [
ListView.builder(
controller: _controller,
itemCount: 100,
itemBuilder: (_, i) => ListTile(title: Text('第 $i 项')),
),
if (_showButton)
Positioned(
right: 16,
bottom: 16,
child: FloatingActionButton.small(
onPressed: _scrollToTop,
child: const Icon(Icons.arrow_upward),
),
),
],
);
}
}
底部加载更多
_controller.addListener(() {
if (_controller.position.pixels >=
_controller.position.maxScrollExtent - 100) {
// 距离底部不足 100px 时加载更多
_loadMore();
}
});
滚动进度条
_controller.addListener(() {
final max = _controller.position.maxScrollExtent;
final current = _controller.position.pixels;
final percent = max > 0 ? (current / max * 100).round() : 0;
setState(() => _scrollPercent = percent);
});

ScrollPosition 对象
_controller.position 返回 ScrollPosition,它提供了更多信息:
final pos = _controller.position;
pos.pixels; // 当前滚动位置
pos.maxScrollExtent; // 最大滚动值
pos.minScrollExtent; // 最小滚动值
pos.viewportDimension; // 视口尺寸
pos.extentBefore; // 已滚过距离
pos.extentAfter; // 剩余可滚距离
pos.atEdge; // 是否在边界
pos.axisDirection; // 滚动方向
动画参数
animateTo 的 curve 控制滚动动画曲线:
// 匀速
_controller.animateTo(500, duration: Duration(seconds: 1), curve: Curves.linear);
// 缓入缓出
_controller.animateTo(500, duration: Duration(seconds: 1), curve: Curves.easeInOut);
// 弹性效果
_controller.animateTo(500, duration: Duration(seconds: 1), curve: Curves.elasticOut);
// 弹跳效果
_controller.animateTo(500, duration: Duration(seconds: 1), curve: Curves.bounceOut);

双方向滚动
水平滚动 + 垂直滚动可以分别控制:
final _horizontalController = ScrollController();
final _verticalController = ScrollController();
Column(
children: [
SizedBox(
height: 200,
child: ListView(
controller: _horizontalController,
scrollDirection: Axis.horizontal,
children: horizontalItems,
),
),
Expanded(
child: ListView(
controller: _verticalController,
children: verticalItems,
),
),
],
)
踩坑记录

ScrollController 必须 dispose
ScrollController 需要在 dispose() 里释放,否则会内存泄漏。Flutter 会在控制台打印警告:
ScrollController not disposed. A ScrollController was used after being disposed.
ScrollController 只能绑定一个滚动组件
默认情况下,一个 ScrollController 只能被一个 ScrollView 使用。如果多个列表需要同步滚动,用 ScrollController 配合 ScrollPosition 监听实现。
animateTo 必须在 hasClients 之后调用
如果 ScrollController 还没绑定到 ScrollView(比如在 initState 里立刻调用 controller.animateTo),会报错:
ScrollController not attached to any scroll views.
确保在第一次 build 之后调用,比如用 WidgetsBinding.instance.addPostFrameCallback:
@override
void initState() {
super.initState();
WidgetsBinding.instance.addPostFrameCallback((_) {
_controller.animateTo(100, duration: Duration.zero, curve: Curves.linear);
});
}
maxScrollExtent 在列表动态变化时更新
如果列表项数量变化导致最大滚动值变了,maxScrollExtent 会自动更新。监听器里不用特别处理,读取到的值是实时的。
列表未初始化时的判断
用 _controller.hasClients 判断控制器是否已绑定到列表:
if (_controller.hasClients) {
final max = _controller.position.maxScrollExtent;
// ...
}
在 Tab 切换时需要重置控制器
如果页面在 Tab 切换时重建,注意 ScrollController 也要重新创建。用 AutomaticKeepAliveClientMixin 保持状态的页面,控制器不会重建,需要手动管理。
验证环境
Flutter 3.27.4
Dart 3.6.2
DevEco Studio 6.1.0.830
HarmonyOS NEXT 6.1








































苏公安网备 32011402010933号