PAYATHON 2026

Flutter Stepper 切换到后续步骤时展开内容超出可视区域,如何处理?

数据小陈

更新 currentStep 后,可以等展开和收起动画结束,再调用 Scrollable.ensureVisible 重新定位选中的步骤。题中的示例可以先通过固定延迟来校正滚动位置,但这是一种规避方案,需要在实际界面中验证。

为什么自动滚动后仍会移出可视区域?

Flutter 3.41.9 的垂直 Stepper 在处理步骤点击时,会先调用 Scrollable.ensureVisible,再调用 onStepTapped。回调中的 setState 随后更新 currentStep,触发旧步骤收起、新步骤展开。源码中,这部分高度变化由 AnimatedCrossFade 实现,动画时长使用 kThemeAnimationDuration。Flutter 3.41.9 Stepper 源码

第一次滚动是按切换前的布局计算的。动画过程中,选中步骤的位置和高度还会变化,原先的滚动目标可能不再合适。

原示例把 Future.delayed 放在 setState 前面,只会推迟布局变化,无法让已经开始的自动滚动根据展开后的布局重新计算目标。

如何调整定位时机?

  1. 为每个步骤的标题保存一个稳定的 GlobalKey。
  2. 点击后立即更新 currentStep。
  3. 更新后的首帧结束后,等待展开和收起动画经过,再等一帧完成布局。
  4. 使用选中标题的 BuildContext 调用 Scrollable.ensureVisible,将标题移到视口靠上的位置,为下方内容留出空间。

Scrollable.ensureVisible 会查找目标所在的滚动容器,因此这里不必额外创建 ScrollController。Scrollable.ensureVisible 文档

代码示例

保留原示例中的 MyApp 和 HomeScreen,将 _HomeScreenState 替换为下面的实现:

class _HomeScreenState extends State<HomeScreen> {
  static const int _stepCount = 50;

  final List<GlobalKey> _titleKeys = List<GlobalKey>.generate(
    _stepCount,
    (_) => GlobalKey(),
  );

  int _selected = 0;
  int _scrollRequest = 0;

  void _selectStep(int step) {
    final int request = ++_scrollRequest;

    setState(() {
      _selected = step;
    });

    WidgetsBinding.instance.addPostFrameCallback((_) async {
      await Future<void>.delayed(
        kThemeAnimationDuration + const Duration(milliseconds: 100),
      );

      if (!mounted || request != _scrollRequest) {
        return;
      }

      await WidgetsBinding.instance.endOfFrame;

      if (!mounted || request != _scrollRequest) {
        return;
      }

      final BuildContext? targetContext =
          _titleKeys[step].currentContext;

      if (targetContext == null) {
        return;
      }

      await Scrollable.ensureVisible(
        targetContext,
        alignment: 0.1,
        duration: const Duration(milliseconds: 200),
        curve: Curves.easeInOut,
      );
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Home')),
      body: Stepper(
        currentStep: _selected,
        onStepTapped: _selectStep,
        steps: List<Step>.generate(
          _stepCount,
          (i) => Step(
            title: Text('Step $i', key: _titleKeys[i]),
            content: const Text('Hi'),
          ),
        ),
      ),
    );
  }
}

_scrollRequest 用于丢弃快速连续点击产生的旧定位请求;mounted 检查可以避免页面销毁后继续访问界面。GlobalKey 保存在 State 中,避免每次 build 时重新创建。

alignment: 0.1 将标题放在视口靠上的位置。接近列表末尾时,实际位置还会受到可滚动范围的限制。最后一次滚动的 200 毫秒只控制校正滚动的速度。

使用时要注意什么?

单独调用一次 addPostFrameCallback 通常不足以解决问题:它只等待一帧结束,此时展开和收起动画可能仍在继续。示例先等待首帧,再等待动画时长,并通过 endOfFrame 等待后续布局完成。addPostFrameCallback 文档、endOfFrame 文档

额外的 100 毫秒是示例中的缓冲时间,不是 Flutter 规定的参数,也不等同于监听动画完成。示例未在题述 DartPad 环境中实测,应检查向前切换、向后切换和连续点击时的表现。

如果步骤中还有异步加载的图片、校验提示等会继续改变高度的内容,需要在这些变化完成后再次定位。若必须精确同步动画与滚动,可以自定义步骤组件,在自己控制的动画结束回调中执行定位。

如果单个步骤的展开内容本身高于视口,滚动定位只能保证目标位置可见,无法让整段内容同时完整显示。

备注:内容仅供参考。