文档开发者中心
我的

Flutter 鸿蒙 ScrollController 滚动控制:监听与编程控制

浏览6.3W+发布于2026-06-30 15:39河南
本文章最后由 在人间耕耘 于 2026-07-05 01:51 编辑

滚动控制的需求

页面滚动时,经常需要做这些事:监听滚动位置显示回到顶部按钮、检测是否滚动到底部触发加载更多、点击某个按钮平滑滚动到指定位置。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
收藏
0
回复
0
分享
全部评论
暂无评论
暂无评论
写评论
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。
发表
我要写文章
目录 收起
滚动控制的需求
基本结构
核心属性和方法
常用属性
常用方法
实际应用场景
回到顶部按钮
底部加载更多
滚动进度条
ScrollPosition 对象
动画参数
双方向滚动
踩坑记录
ScrollController 必须 dispose
ScrollController 只能绑定一个滚动组件
animateTo 必须在 hasClients 之后调用
maxScrollExtent 在列表动态变化时更新
列表未初始化时的判断
在 Tab 切换时需要重置控制器
验证环境
了解社区公约,与您携手共创和谐专业的开发者社区。