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端专属注意事项
常见模式与反模式