Flutter Stepper切换步骤时如何将焦点定位到步骤头部？

核心方案 #

通过ScrollController结合GlobalKey定位Step组件位置，配合WidgetsBinding的帧回调处理异步构建的延迟，实现切换步骤时精准滚动到Step标题位于AppBar下方的位置。

1. 初始化控制器与全局Key #

先创建用于控制外层ScrollView的控制器，以及每个Step对应的全局Key（用来获取组件位置）：

final ScrollController _scrollController = ScrollController();
// 根据你的步骤数量生成对应数量的GlobalKey
final List<GlobalKey> _stepKeys = List.generate(3, (_) => GlobalKey());
int _currentStep = 0;

2. 为Step绑定全局Key #

在构建Stepper的Step列表时，将每个Step的key属性设置为对应的GlobalKey：

Scaffold(
  appBar: AppBar(title: const Text('Stepper滚动示例')),
  body: SingleChildScrollView(
    controller: _scrollController,
    child: Stepper(
      currentStep: _currentStep,
      onStepTapped: (index) => _onStepChanged(index),
      onStepContinue: () => _onStepChanged(_currentStep + 1),
      onStepCancel: () => _onStepChanged(_currentStep - 1),
      steps: List.generate(3, (index) {
        return Step(
          key: _stepKeys[index], // 绑定全局Key
          title: Text('步骤 ${index + 1}'),
          content: Column(
            children: [
              FutureBuilder(
                future: Future.delayed(const Duration(500), () => '加载完成'),
                builder: (context, snapshot) {
                  if (snapshot.hasData) {
                    // 模拟不同高度的内容
                    return Column(
                      children: List.generate(
                        index == 1 ? 40 : 5,
                        (i) => Padding(
                          padding: const EdgeInsets.symmetric(vertical: 8),
                          child: Text('步骤${index+1}的内容行 $i'),
                        ),
                      ),
                    );
                  }
                  return const CircularProgressIndicator();
                },
              ),
            ],
          ),
        );
      }),
    ),
  ),
)

3. 实现滚动逻辑 #

在步骤切换的回调中，等待UI帧渲染完成后，计算并执行滚动操作：

void _onStepChanged(int newIndex) {
  if (newIndex < 0 || newIndex >= _stepKeys.length) return;
  
  setState(() {
    _currentStep = newIndex;
  });

  // 等待当前帧渲染完成，确保Step的位置和高度已更新
  WidgetsBinding.instance.addPostFrameCallback((_) {
    _scrollToStepHeader(newIndex);
  });
}

void _scrollToStepHeader(int stepIndex) {
  final keyContext = _stepKeys[stepIndex].currentContext;
  if (keyContext == null) return;

  final renderBox = keyContext.findRenderObject() as RenderBox;
  // 获取Step组件在屏幕中的绝对位置
  final globalPosition = renderBox.localToGlobal(Offset.zero);
  // 计算需要滚动的偏移量：当前滚动偏移 + Step顶部到屏幕顶部的距离 - AppBar高度
  final appBarHeight = AppBar().preferredSize.height;
  final targetOffset = _scrollController.offset + globalPosition.dy - appBarHeight;

  _scrollController.animateTo(
    targetOffset,
    duration: const Duration(milliseconds: 300),
    curve: Curves.easeInOut,
  );
}

4. 处理动态内容加载后的偏移（可选） #

如果FutureBuilder加载完成后内容高度变化导致Step位置偏移，可以在数据加载完成后再次触发滚动：

// 在FutureBuilder的builder中添加
if (snapshot.hasData) {
  WidgetsBinding.instance.addPostFrameCallback((_) {
    if (_currentStep == index) {
      _scrollToStepHeader(index);
    }
  });
  // ... 返回内容组件
}

内容的提问来源于stack exchange，提问作者sosnus