Go Router

GoRouter 是一个用于 Flutter 的声明式路由包，它利用 Router API 提供便捷的基于 URL 的导航。

核心概念

1. 路由配置

将路由定义为 GoRoute 对象的列表：

dart
final GoRouter _router = GoRouter(
initialLocation: /,
routes: [
GoRoute(
path: /,
builder: (context, state) => const HomeScreen(),
),
GoRoute(
path: /user/:id,
builder: (context, state) {
final userId = state.pathParameters[id]!;
return UserScreen(id: userId);
},
),
],
);

2. 导航

dart
// 简单导航
context.go(/details);

// 带参数
context.go(/user/123);

// 命名导航（需要 name 参数）
context.goNamed(user, pathParameters: {id: 123});

// 推入（添加到栈顶）
context.push(/modal);

// 替换当前路由
context.replace(/new);

// 返回
context.pop();

// 带查询参数
context.go(/search?q=flutter);

3. 路由参数

路径参数使用 : 前缀：

dart
GoRoute(
path: /user/:id/posts/:postId,
builder: (context, state) {
final userId = state.pathParameters[id]!;
final postId = state.pathParameters[postId]!;
return PostScreen(userId: userId, postId: postId);
},
)

查询参数通过 state.uri.queryParameters 访问：

dart
GoRoute(
path: /search,
builder: (context, state) {
final query = state.uri.queryParameters[q] ?? ;
return SearchScreen(query: query);
},
)

常见模式

模式 1：带重定向的认证守卫

dart
final routerProvider = Provider((ref) {
final auth = ref.watch(authProvider);

return GoRouter(
initialLocation: /,
redirect: (context, state) {
final isLoggedIn = auth.isLoggedIn;
final isAuthRoute = state.matchedLocation == /login;

if (!isLoggedIn && !isAuthRoute) {
return /login;
}
if (isLoggedIn && isAuthRoute) {
return /;
}
return null;
},
routes: [
GoRoute(path: /login, builder: (, _) => const LoginScreen()),
GoRoute(path: /, builder: (, _) => const HomeScreen()),
],
);
});

模式 2：底部导航的 ShellRoute

dart
GoRouter(
routes: [
ShellRoute(
builder: (context, state, child) {
return ScaffoldWithNavBar(child: child);
},
routes: [
GoRoute(
path: /,
builder: (, _) => const HomeScreen(),
),
GoRoute(
path: /settings,
builder: (, _) => const SettingsScreen(),
),
],
),
],
)

模式 3：嵌套导航的 StatefulShellRoute

dart
StatefulShellRoute(
branches: [
StatefulShellBranch(
routes: [GoRoute(path: /feed, builder: (, _) => FeedScreen())],
),
StatefulShellBranch(
routes: [GoRoute(path: /profile, builder: (, _) => ProfileScreen())],
),
],
)

模式 4：自定义页面过渡动画

dart
GoRoute(
path: /details,
pageBuilder: (context, state) => const MaterialPage(
child: DetailsScreen(),
),
// 或者自定义过渡动画
pageBuilder: (context, state) => CustomTransitionPage(
child: const DetailsScreen(),
transitionsBuilder: (context, animation, secondaryAnimation, child) {
return FadeTransition(
opacity: CurveTween(curve: Curves.easeInOut).animate(animation),
child: child,
);
},
),
)

模式 5：错误处理

dart
GoRouter(
errorBuilder: (context, state) {
return ErrorScreen(error: state.error);
},
// 或者处理 404
errorPageBuilder: (context, state) => MaterialPage(
child: NotFoundScreen(path: state.uri.path),
),
)

模式 6：类型安全路由（Go Router 14+）

定义类型化路由：

dart
part app_routes.g.dart;

@TypedGoRoute(path: /)
class HomeRoute extends GoRouteData {
@override
Widget build(BuildContext context, GoRouterState state) {
return const HomeScreen();
}
}

@TypedGoRoute(path: /user/:id)
class UserRoute extends GoRouteData {
final String id;
const UserRoute({required this.id});

@override
Widget build(BuildContext context, GoRouterState state) {
return UserScreen(id: id);
}
}

路由状态

在构建器中访问路由信息：

dart
GoRoute(
path: /details,
builder: (context, state) {
// 路径：state.uri.path
// 查询参数：state.uri.queryParameters
// 额外数据：state.extra（通过 context.go(/details, extra: data) 传递）
return DetailsScreen(
path: state.uri.path,
data: state.extra as MyData?,
);
},
)

导航辅助方法

dart
// 用于更简洁导航的扩展
extension NavigationHelpers on BuildContext {
void goHome() => go(/);
void goUser(String id) => go(/user/$id);
void pushModal(Widget screen) => push(/modal, extra: screen);
}

// 使用
context.goHome();
context.goUser(123);

Web 支持

启用 Web URL 处理：

dart
GoRouter(
// 处理浏览器前进/后退
// URL 自动更新
initialLocation: /,
// Web 的基础 href
routerNeglect: true, // 禁用浏览器历史记录
)

// 访问当前路由
final currentRoute = GoRouter.of(context).routeInformationProvider.value.uri.path;

路由观察者

dart
GoRouter(
observers: [RouteObserver()],
navigatorBuilder: (context, state, child) {
// 包裹所有路由
return SomeWrapper(child: child);
},
)

测试

dart
testWidgets(正确导航, (tester) async {
await tester.pumpWidget(
MaterialApp.router(
routerConfig: _router,
),
);

// 查找并点击按钮
await tester.tap(find.text(前往详情));
await tester.pumpAndSettle();

// 验证导航
expect(find.text(详情), findsOneWidget);
});

代码生成

用于类型安全路由的代码生成：

bash
dart run build_runner build

生成：

• - 路由位置的 $route 常量
• 类型化路由的参数类

深度链接

配置 Android 和 iOS 的深度链接，然后在 GoRouter 中处理：

dart
GoRouter(
routes: [
GoRoute(
path: /product/:id,
builder: (context, state) {
// 处理 myapp.com/product/123
// 和 app://product/123
return ProductScreen(id: state.pathParameters[id]!);
},
),
],
)

无上下文导航

dart
// 存储路由引用
final GoRouter router = GoRouter(...);

// 无上下文导航
router.go(/home);
router.push(/modal);
router.pop();

架构模式请参阅 BEST_PRACTICES.md。