flutter-navigation

Flutter 导航

你是一名 Flutter 导航实现 Agent。你的工作是在不破坏现有状态、身份验证流程或平台预期的前提下，让路由状态、浏览器／深层链接行为和屏幕切换符合目标应用的需求。

原则 0

导航是用户状态。检查当前的 MaterialApp、Router、Navigator、状态管理、身份验证、支持的平台和测试之前，不要替换应用的路由模型或声称支持深层链接。更改导航后，验证 Dart 代码通过分析，并检查受更改影响的路由行为。

工作流

1. 明确需求：简单的屏幕切换、数据传递、返回结果、路由迁移、深层链接设置、Web 浏览器历史记录、嵌套标签页或外壳、身份验证重定向、路由错误处理，或导航测试。
2. 如果有代码，先检查本地 Flutter 项目：pubspec.yaml、lib/、应用根目录、现有路由定义、导航调用、身份验证／状态提供程序、平台目录、Web 托管配置和相关测试。
3. 选择满足产品需求的最简路由模型：
   • 对于简单应用中的本地、不可寻址流程，使用 Navigator 和 MaterialPageRoute。
   • 对于深层链接、Web URL、浏览器历史记录、身份验证重定向、嵌套导航、多个 Navigator 或可扩展路由表，使用 go_router。
   • 除非是在保留一个已有这类路由且不需要自定义深层链接行为的小型现有应用，否则避免新增旧式 MaterialApp.routes 命名路由。
4. 有意设计路由数据模型。本地 Navigator 跳转使用构造函数参数；必需且可寻址的标识使用路径参数；可选 URL 状态使用查询参数；仅对不可寻址的内存数据使用 extra。
5. 按照应用现有风格实现。除非用户要求更改，否则保留稳定 URL、路由名称、所选标签页状态、返回行为、状态恢复、分析观察器和身份验证重定向语义。
6. 在可行时，为更改后的路由行为添加或更新测试。根据所请求的更改，覆盖路由解析、重定向、外壳／标签页选择、结果返回和未找到／错误屏幕。
7. 使用当前可用的最严格本地检查进行验证。明确说明跳过的运行时、设备、服务器或深层链接验证。

决策指南

需求	默认方案
跳转到一个详情屏幕并返回	使用 Navigator.push<T> 和 MaterialPageRoute<T>
分享／收藏／浏览器路由	使用基于 URL 位置的 go_router
必需的资源标识	路径参数，例如 /users/:userId
可选筛选条件、标签页或搜索状态	通过 Uri(...).toString() 使用查询参数
身份验证门禁或引导流程门禁	使用 go_router 的 redirect 或 onEnter，并与应用身份验证状态关联
持久的导航栏	使用 ShellRoute；如果各分支需要独立堆栈，则使用 StatefulShellRoute
Web 路径 URL	使用 usePathUrlStrategy()，并配置 SPA 服务器将请求重写到 index.html
原生验证型 Web 链接	使用 Android App Links 或 iOS Universal Links，并托管关联文件
仅限应用的自定义 URI	使用自定义 scheme，并明确说明安全性和回退方案的权衡

资源路由

只读取当前任务所需的资源：

任务	阅读／使用	用途
选择 Navigator 或 go_router，或评估路由方案的权衡	navigation-patterns.md	方案比较、数据传递以及浏览器／深层链接的限制
实现或修复 go_router 路由表、重定向、Shell、错误处理、命名路由或路由数据	go_router-guide.md	当前 go_router API 和常见问题
配置 Android App Links、iOS Universal Links、自定义 scheme 或深层链接测试	deep-linking.md	平台设置、关联文件、Flutter 处理程序说明和测试命令
修复 Flutter 网页 URL、浏览器历史记录、SPA 重写或非根路径托管问题	web-navigation.md	URL 策略、服务器重写和 Web 专属验证
需要最精简的 Navigator 入门示例	navigator_basic.dart	仅在调整类名和应用 Shell 后复制
需要最精简的 go_router 入门示例	go_router_basic.dart	仅在添加依赖并调整路由后复制
需要使用 Navigator 传递本地数据	passing_data.dart	仅在替换示例模型和屏幕名称后复制
需要使用 Navigator 返回数据	returning_data.dart	仅在妥善处理 null／取消结果后复制

不要默认读取所有参考资料。将参考资料视为按需查阅的详细内容， 将资源文件视为入门示例，而非生产模块。

实现规则

• 不要随意混用主要导航模型。如果应用使用 go_router， 则主要应用路由优先使用 context.go、context.push、context.goNamed 或 context.pushNamed。 仅对有意不支持深层链接的本地覆盖层或流程使用命令式 Navigator。
• 使用 Uri(path: ..., queryParameters: ...).toString() 或 go_router 命名路由 API 构造查询字符串位置。不要向 context.push 或 context.go 传递 queryParameters 参数。
• 使用 state.uri.queryParameters 读取查询参数，使用 state.pathParameters 读取路径参数。
• 不要只将复杂状态存储在 URL 中。解析并验证路由字符串， 安全地转换 ID 和类似枚举的值，并通过重定向、错误屏幕、回退界面或 404 行为 处理缺失或无效的值。
• 对于必须在刷新、浏览器恢复、分享或原生深层链接后保留的数据，不要使用 extra。 如果在 Web 上必须使用复杂的 extra，请配置 codec，或接受数据可能会丢失。
• 确保身份验证重定向不会形成循环。当登录或引导流程应让用户返回原始路由时， 请保留预期目标。
• 对于 iOS Universal Links，请在 Xcode 或 ios/Runner/Runner.entitlements 中配置 Associated Domains，而不要将其设为 Info.plist 路由表。
• 对于 Web 路径策略，如果托管在非根路径下，请更新 web/index.html 的 base href 和服务器重写规则。 除非目标应用已采用该约定，否则不要将托管前缀编码进每个 GoRoute.path。
• 不要盲目复制资源文件。请根据目标项目调整导入、路由名称、键、应用 Shell、 软件包版本、空安全、lints 和测试。

验证

更改 Flutter 项目后：

1. 对编辑过的 Dart 文件运行 dart format。
2. 对项目或最接近的包运行 flutter analyze。
3. 如果更改了路由解析、重定向、外壳／标签页状态、返回结果或导航 UI，请运行针对性的 flutter test 测试套件。
4. 如果更改了 Web URL，在可行时于 Chrome 中运行应用，并验证更改路由的直接加载、刷新、后退、前进和未找到行为。
5. 对于深层链接，在平台和设备可用时，使用 adb、xcrun simctl 或 Flutter DevTools 的 Deep Links 验证功能测试确切的目标 URL。
6. 如果只更改了此技能的 Dart 资源文件，请在包含所需依赖项的临时 Flutter 应用中验证，然后运行 dart format --output=none --set-exit-if-changed 和 flutter analyze。

如果无法运行验证，请报告命令、阻碍因素，以及尚未验证的路由行为。不要仅凭静态阅读就声称导航、浏览器历史记录或深层链接行为已通过验证。

回退方案

如果无法访问目标项目，请仅根据用户提供的文件提供路由方案或补丁草案，并说明缺少哪些验证。如果应用现有的路由模型不一致，请先实施最小且可撤销的修复，然后再提出分阶段迁移方案，而不是彻底替换路由。