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 前面,只会推迟布局变化,无法让已经开始的自动滚动根据展开后的布局重新计算目标。
如何调整定位时机?
- 为每个步骤的标题保存一个稳定的
GlobalKey。 - 点击后立即更新
currentStep。 - 更新后的首帧结束后,等待展开和收起动画经过,再等一帧完成布局。
- 使用选中标题的
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 环境中实测,应检查向前切换、向后切换和连续点击时的表现。
如果步骤中还有异步加载的图片、校验提示等会继续改变高度的内容,需要在这些变化完成后再次定位。若必须精确同步动画与滚动,可以自定义步骤组件,在自己控制的动画结束回调中执行定位。
如果单个步骤的展开内容本身高于视口,滚动定位只能保证目标位置可见,无法让整段内容同时完整显示。
备注:内容仅供参考。
