路由管理组件

路由管理组件用于处理应用内的页面导航和路由控制。

提示：良好的路由管理可以提升用户体验和应用的可维护性。
路由结构图
HomePage
/
DetailsPage
/details
NotFoundPage
/*

onGenerateRoute

onGenerateRoute 用于动态生成路由。

MaterialApp(
  onGenerateRoute: (settings) {
    switch (settings.name) {
      case '/':
        return MaterialPageRoute(
          builder: (_) => HomePage(),
        );
      case '/details':
        final args = settings.arguments as Map;
        return MaterialPageRoute(
          builder: (_) => DetailsPage(args: args),
        );
      default:
        return MaterialPageRoute(
          builder: (_) => NotFoundPage(),
        );
    }
  },
)

onUnknownRoute

onUnknownRoute 处理未知的路由。

MaterialApp(
  onUnknownRoute: (settings) {
    return MaterialPageRoute(
      builder: (_) => NotFoundPage(),
    );
  },
)

initialRoute

initialRoute 指定应用的初始路由。

MaterialApp(
  initialRoute: '/login',
  routes: {
    '/login': (context) => LoginPage(),
    '/home': (context) => HomePage(),
  },
)
初始路由配置
LoginPage
→
HomePage
初始路由: /login
应用启动时直接显示登录页面

NavigatorObserver

NavigatorObserver 用于观察导航事件。

class MyNavigatorObserver extends NavigatorObserver {
  @override
  void didPush(Route route, Route? previousRoute) {
    super.didPush(route, previousRoute);
    print('推送路由: ${route.settings.name}');
  }

  @override
  void didPop(Route route, Route? previousRoute) {
    super.didPop(route, previousRoute);
    print('弹出路由: ${route.settings.name}');
  }
}

MaterialApp(
  navigatorObservers: [MyNavigatorObserver()],
  home: HomePage(),
)
导航事件日志
📱 App started
✅ didPush: /home
[route stack: /home]
✅ didPush: /details
[route stack: /home → /details]
❌ didPop: /details
[route stack: /home]

popUntil 弹出路由直到满足条件。

// 返回到首页
Navigator.popUntil(context, ModalRoute.withName('/'));

// 返回两页
Navigator.popUntil(context, (route) {
  return Navigator.of(context).canPop() && 
         Navigator.of(context).userGestureInProgress;
});

// 使用命名路由
Navigator.popUntil(context, (route) {
  return route.settings.name == '/home';
});
popUntil 路由栈变化
操作前:
/home
/details
/settings
Navigator.popUntil(context, ModalRoute.withName('/')):
/home
弹出所有页面直到首页

pushAndRemoveUntil 推送新路由并移除所有旧路由。

// 清空路由栈并推送新页面
Navigator.pushAndRemoveUntil(
  context,
  MaterialPageRoute(builder: (_) => HomePage()),
  (route) => false,
);

// 保留底部导航
Navigator.pushAndRemoveUntil(
  context,
  MaterialPageRoute(builder: (_) => LoginPage()),
  ModalRoute.withName('/'),
);
pushAndRemoveUntil 路由栈变化
操作前:
/login
/otp
/register
Navigator.pushAndRemoveUntil(..., (route) => false):
/home
清空所有旧路由，只保留新页面

pushReplacement 替换当前路由。

// 替换当前页面
Navigator.pushReplacement(
  context,
  MaterialPageRoute(builder: (_) => HomePage()),
);

// 使用命名路由
Navigator.pushReplacementNamed(
  context,
  '/home',
);
pushReplacement 路由栈变化
操作前:
/login
/home
Navigator.pushReplacement(..., /profile):
/login
/profile
替换当前页面，用户无法返回
路由管理最佳实践：
  • 使用命名路由提高代码可读性
  • 使用 onGenerateRoute 处理复杂路由
  • 使用 NavigatorObserver 监控导航
  • 合理使用 popUntil 避免用户困惑
  • 使用 Hero 动画提升用户体验
注意事项：
  • Web 平台的路由行为可能与移动平台不同
  • 深层嵌套的路由可能导致内存问题
  • 使用 pushAndRemoveUntil 时要小心
← 应用配置组件 持久化组件 →