Flutter GoRouter 路由导航详解

一、GoRouter 概述

GoRouter 是 Flutter 官方推荐的路由管理库，提供声明式路由配置和类型安全的导航。

1.1 安装依赖

dependencies: go_router: ^12.0.0

二、基本配置

2.1 创建路由配置

import 'package:go_router/go_router.dart'; final GoRouter router = GoRouter( routes: <RouteBase>[ GoRoute( path: '/', builder: (BuildContext context, GoRouterState state) { return const HomePage(); }, ), GoRoute( path: '/details/:id', builder: (BuildContext context, GoRouterState state) { return DetailPage(id: state.pathParameters['id']!); }, ), ], );

2.2 配置 MaterialApp

class MyApp extends StatelessWidget { const MyApp({super.key}); @override Widget build(BuildContext context) { return MaterialApp.router( routerConfig: router, title: 'GoRouter Demo', ); } }

三、路由导航

3.1 基本导航

// 导航到指定路径 context.push('/details/123'); // 导航并替换当前页面 context.pushReplacement('/details/123'); // 返回上一页 context.pop(); // 返回到根页面 context.popUntil((route) => route.isFirst);

3.2 带参数导航

// 路径参数 context.push('/user/${user.id}'); // 查询参数 context.push('/search?q=flutter'); // 额外参数 context.push('/details', extra: {'data': myData});

四、路由守卫

4.1 全局守卫

final GoRouter router = GoRouter( routes: [...], redirect: (BuildContext context, GoRouterState state) { final bool isLoggedIn = // 检查登录状态 if (!isLoggedIn && state.location != '/login') { return '/login'; } return null; }, );

4.2 路由级别守卫

GoRoute( path: '/profile', builder: (context, state) => const ProfilePage(), redirect: (context, state) { final bool isLoggedIn = // 检查登录状态 return isLoggedIn ? null : '/login'; }, );

五、嵌套路由

5.1 配置嵌套路由

GoRoute( path: '/dashboard', builder: (context, state) => const DashboardPage(), routes: [ GoRoute( path: 'settings', builder: (context, state) => const SettingsPage(), ), GoRoute( path: 'profile', builder: (context, state) => const ProfilePage(), ), ], );

5.2 使用 ShellRoute

final GoRouter router = GoRouter( routes: [ ShellRoute( builder: (context, state, child) { return Scaffold( body: child, bottomNavigationBar: BottomNavigationBar( items: const [ BottomNavigationBarItem(icon: Icon(Icons.home), label: 'Home'), BottomNavigationBarItem(icon: Icon(Icons.settings), label: 'Settings'), ], ), ); }, routes: [ GoRoute( path: '/', builder: (context, state) => const HomePage(), ), GoRoute( path: '/settings', builder: (context, state) => const SettingsPage(), ), ], ), ], );

六、类型安全路由

6.1 使用 TypedGoRoute

@TypedGoRoute<HomeRoute>(path: '/') class HomeRoute extends GoRouteData { const HomeRoute(); @override Widget build(BuildContext context, GoRouterState state) { return const HomePage(); } } @TypedGoRoute<DetailRoute>(path: '/details/:id') class DetailRoute extends GoRouteData { const DetailRoute({required this.id}); final String id; @override Widget build(BuildContext context, GoRouterState state) { return DetailPage(id: id); } }

6.2 类型安全导航

// 使用类型安全导航 HomeRoute().go(context); DetailRoute(id: '123').push(context);

七、实战案例

7.1 完整路由配置

final GoRouter router = GoRouter( initialLocation: '/', routes: [ GoRoute( path: '/', name: 'home', builder: (context, state) => const HomePage(), ), GoRoute( path: '/login', name: 'login', builder: (context, state) => const LoginPage(), ), GoRoute( path: '/dashboard', name: 'dashboard', builder: (context, state) => const DashboardPage(), redirect: (context, state) { final authState = Provider.of<AuthState>(context, listen: false); return authState.isLoggedIn ? null : '/login'; }, routes: [ GoRoute( path: 'profile', name: 'profile', builder: (context, state) => const ProfilePage(), ), GoRoute( path: 'settings', name: 'settings', builder: (context, state) => const SettingsPage(), ), ], ), ], errorBuilder: (context, state) => const ErrorPage(), );

7.2 使用路由信息

class DetailPage extends StatelessWidget { const DetailPage({super.key}); @override Widget build(BuildContext context) { final GoRouterState state = GoRouterState.of(context); final String id = state.pathParameters['id']!; final String? query = state.uri.queryParameters['q']; return Scaffold( appBar: AppBar(title: const Text('详情')), body: Center( child: Column( children: [ Text('ID: $id'), if (query != null) Text('查询: $query'), ], ), ), ); } }

八、总结

GoRouter 提供了强大的路由管理功能：

1. 声明式配置- 集中配置所有路由
2. 类型安全- TypedGoRoute 确保类型安全
3. 路由守卫- 全局和路由级别守卫
4. 嵌套路由- 支持复杂的页面结构
5. ShellRoute- 共享布局的路由

合理使用可以构建清晰的导航结构。