Back to Details

flutter-navigation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Flutter Navigation

Flutter 导航与路由

Overview

概述

Implement navigation and routing in Flutter applications across mobile and web platforms. Choose the right navigation approach, configure deep linking, manage data flow between screens, and handle browser history integration.
在移动端和Web端的Flutter应用中实现导航与路由功能。选择合适的导航方案，配置深度链接，管理页面间的数据流，并处理浏览器历史记录集成。

Choosing an Approach

选择合适的方案

Use Navigator API (Imperative) When:

以下场景使用Navigator API（命令式）：

  • Simple apps without deep linking requirements
  • Single-screen to multi-screen transitions
  • Basic navigation stacks
  • Quick prototyping
Example: 
assets/navigator_basic.dart
  • 无深度链接需求的简单应用
  • 单页面到多页面的切换
  • 基础导航栈
  • 快速原型开发
示例: 
assets/navigator_basic.dart

Use go_router (Declarative) When:

以下场景使用go_router（声明式）：

  • Apps requiring deep linking (iOS, Android, Web)
  • Web applications with browser history support
  • Complex navigation patterns with multiple Navigator widgets
  • URL-based navigation needed
  • Production applications with scalable architecture
Example: 
assets/go_router_basic.dart
  • 需要深度链接的应用（iOS、Android、Web）
  • 支持浏览器历史记录的Web应用
  • 包含多个Navigator组件的复杂导航模式
  • 需要基于URL的导航
  • 具备可扩展架构的生产级应用
示例: 
assets/go_router_basic.dart

Avoid Named Routes

避免使用命名路由

Flutter team does NOT recommend named routes. They have limitations:
  • Cannot customize deep link behavior
  • No browser forward button support
  • Always pushes new routes regardless of current state
Flutter官方团队不推荐使用命名路由。它们存在以下局限性：
  • 无法自定义深度链接行为
  • 不支持浏览器前进按钮
  • 无论当前状态如何，始终推送新路由

Common Tasks

常见任务

Pass Data Between Screens

页面间传递数据

With Navigator:
dart
Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => DetailScreen(item: myItem)),
);
With go_router:
dart
context.push('/details?id=123');
// Extract: final id = state.uri.queryParameters['id'];
Example: 
assets/passing_data.dart
使用Navigator实现：
dart
Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => DetailScreen(item: myItem)),
);
使用go_router实现：
dart
context.push('/details?id=123');
// Extract: final id = state.uri.queryParameters['id'];
示例: 
assets/passing_data.dart

Return Data From Screens

从页面返回数据

dart
final result = await Navigator.push(
  context,
  MaterialPageRoute<String>(builder: (context) => SelectionScreen()),
);
if (!context.mounted) return;
Example: 
assets/returning_data.dart
dart
final result = await Navigator.push(
  context,
  MaterialPageRoute<String>(builder: (context) => SelectionScreen()),
);
if (!context.mounted) return;
示例: 
assets/returning_data.dart

Configure Deep Linking

配置深度链接

Android: Configure 
AndroidManifest.xml
intent filters iOS: Configure 
Info.plist
for Universal Links Web: Automatic with go_router, choose URL strategy
For detailed setup: 
references/deep-linking.md
Android端： 配置
AndroidManifest.xml
中的意图过滤器 iOS端： 为通用链接配置
Info.plist
Web端： 使用go_router可自动支持，选择URL策略
详细设置参考: 
references/deep-linking.md

Web URL Strategy

Web端URL策略

Hash (default): 
example.com/#/path
- no server config needed Path: 
example.com/path
- cleaner URLs, requires server config
For server setup: 
references/web-navigation.md
哈希模式（默认）： 
example.com/#/path
- 无需服务器配置 路径模式： 
example.com/path
- URL更简洁，需要服务器配置
服务器设置参考: 
references/web-navigation.md

Navigation Methods

导航方法

go_router Navigation

go_router 导航方法

  • context.go('/path')
    - replace current route
  • context.push('/path')
    - add to stack
  • context.pop()
    - go back
  • context.go('/path')
    - 替换当前路由
  • context.push('/path')
    - 添加到导航栈
  • context.pop()
    - 返回上一页

Navigator Navigation

Navigator 导航方法

  • Navigator.push()
    - add route to stack
  • Navigator.pop()
    - remove route from stack
  • Navigator.push()
    - 将路由添加到导航栈
  • Navigator.pop()
    - 从导航栈移除当前路由

Advanced Topics

进阶主题

Route Guards: Implement authentication redirects Nested Routes: Create shell routes with shared UI Error Handling: Handle 404 and navigation errors Multiple Navigators: Manage independent navigation stacks
For advanced patterns: 
references/go_router-guide.md
路由守卫： 实现认证重定向 嵌套路由： 创建带共享UI的外壳路由 错误处理： 处理404和导航错误 多Navigator实例： 管理独立的导航栈
进阶模式参考: 
references/go_router-guide.md

Decision Guide

决策指南

Use navigation-patterns.md for:
  • Complete comparison of navigation approaches
  • Deep linking behavior by platform
  • Web-specific considerations
  • Common patterns and anti-patterns
参考navigation-patterns.md获取：
  • 导航方案的完整对比
  • 各平台的深度链接行为
  • Web端专属注意事项
  • 常见模式与反模式