如何在go_router的StatefulShellRoute.indexedStack跨StatefulShellBranch使用Hero

核心问题根源 #

StatefulShellRoute.indexedStack的每个StatefulShellBranch都持有独立的Navigator实例，而Hero组件的转场依赖同一Navigator上下文来匹配共享的Hero标签。默认跨分支页面分属不同Navigator，Hero无法自动识别匹配，因此需要手动处理导航上下文的传递逻辑。

实现步骤 #

1. 配置全局唯一的Hero标签 #

在需要转场的两个页面中，为Hero组件设置完全一致的唯一标签：

// 分支A的页面组件
Hero(
  tag: 'product_image_123',
  child: ClipRRect(
    borderRadius: BorderRadius.circular(8),
    child: Image.network('https://example.com/product.jpg'),
  ),
)

// 分支B的页面组件
Hero(
  tag: 'product_image_123',
  child: Image.network('https://example.com/product.jpg'),
)

2. 跳转时指定使用根Navigator #

触发跳转时，通过rootNavigator: true强制使用根Navigator，让两个页面处于同一导航上下文环境，确保Hero能正常匹配：

// 从分支A页面跳转至分支B页面
context.pushNamed(
  'product_detail_page',
  rootNavigator: true,
);

3. 同步底部导航栏分支状态 #

由于使用根Navigator跳转不会自动切换底部导航栏的选中分支，需要手动更新Shell的分支索引：

// 跳转后切换到目标分支
final shellState = GoRouterState.of(context).shellState;
if (shellState != null) {
  shellState.goBranch(1); // 切换到索引为1的分支（索引从0开始计数）
}

4. 优化转场视觉体验（可选） #

若希望底部导航栏在转场过程中保持显示且过渡自然，可以在目标页面的Scaffold中设置布局参数：

// 分支B的页面Scaffold
Scaffold(
  extendBodyBehindAppBar: true,
  bottomNavigationBar: YourCustomBottomNavBar(),
  body: Hero(/* ... */),
)

注意事项 #

• 所有涉及Hero转场的跳转必须指定rootNavigator: true，否则跨分支Hero无法生效。
• Hero标签必须全局唯一，避免与其他Hero组件冲突导致转场异常。
• 若分支内存在嵌套导航，需确保跳转路径正确，且根Navigator能准确定位到目标页面。

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