# ZenRouter技能该项目使用 [zenrouter]() — 一个 Flutter 路由器，支持 **命令式** 、 **声明式** 和 **基于协调器的** 导航。此技能涵盖 **Coordinator + RouteModule** 模式，当您需要深度链接、URL 同步、布局和模块化功能组织时，这是正确的选择。 > **深入参考** - 仅当您需要特定主题时才阅读这些内容： > > 文件|何时阅读 > ---|--- > [ADVANCED.md]() |协调器作为模块、选项卡导航、可组合重定向规则、参数路由示例 > [MIXIN.md]() | “RouteGuard”、“RouteRedirect”、“RouteDeepLink”、“RouteTransition”、“RouteQueryParameters”、“RouteRestorable”的完整参考 > [NAVIGATION.md]() |何时使用“push”、“navigate”、“replace”和其他导航方法 ** ** ## 关键类型类型 |套餐 |目的 ---|---|--- `路线目标` | `zenrouter_core` |所有路线的基类；通过“props”进行身份识别 `路线独特` | `zenrouter_core` | Mixin — 添加 URI 标识； **对于协调器路线来说是必需的** `协调员` | `zenrouter` |中央集线器：拥有“NavigationPath”，解析 URI，驱动 Flutter Router `CoordinatorModular` | `zenrouter_core` | `Coordinator` 上的 Mixin — 将路由解析拆分到 `RouteModule` 上 `RouteModule` | `zenrouter_core` |处理一项功能的 URI 模式和导航路径 `NavigationPath` | `zenrouter` |可变的路由堆栈；每个布局组一个 `IndexedStackPath` | `zenrouter` |固定的标签栏样式导航路线集 `RouteLayout` | `zenrouter` | Mixin — 包装嵌套路由的布局路由（shell、选项卡栏、抽屉等） `RouteRedirectRule` | `zenrouter_core` | Mixin — 将重定向逻辑委托给“RedirectRule”列表 `RedirectRule` | `zenrouter_core` |单个可组合防护装置；返回 `continueRedirect`、`redirectTo` 或 `stop` ** ** ## 1\.路由基础类型协调器中的所有路由都必须扩展“RouteTarget with RouteUnique”：抽象类 AppRoute 使用 RouteUnique 扩展 RouteTarget { @覆盖 Widget build(covariant Coordinator 协调器, BuildContext 上下文); } ** ** ## 2\.协调员 ### 简单（无模块）类 AppCoordinator 扩展 Coordinator { 后期最终 homeStack = NavigationPath.createWith( 标签：'家'，协调员：这个， )..bindLayout(HomeLayout.new); @覆盖 List 获取路径 => [...super.paths, homeStack]; @覆盖 AppRoute parseRouteFromUri(Uri uri) => switch (uri.pathSegments) { []|| ['home'] => HomeRoute(), ['产品'，最终 id] => ProductRoute(id: id), _ => NotFoundRoute(uri: uri), }; } // 接线： MaterialApp.router(routerConfig: AppCoordinator()) ### 模块化（带有功能模块）添加 CoordinatorModular 来跨功能模块委托 URI 解析：类 AppCoordinator 扩展 Coordinator 与 CoordinatorModular { @覆盖设置 > DefineModules() => { AuthModule（这个），商店模块（这个），配置文件模块（这个）， }; @覆盖 AppRoute notFoundRoute(Uri uri) => NotFoundRoute(uri: uri); } **规则：** * `defineModules()` 中的模块顺序决定解析优先级 — 第一个非空结果获胜。 * `CoordinatorModular` 自动覆盖 `parseRouteFromUri`； **不要**覆盖它。 * 当所有模块返回“null”时，调用“notFoundRoute”。 > 对于带有子模块的嵌套功能组，请参阅 ADVANCED.md 中的 [Coordinator as Module]()。 ** ** ## 3\.路线模块类 ShopModule 扩展 RouteModule { ShopModule(super.coordinator); 后期最终 shopStack = NavigationPath.createWith( coordinator: coordinator, // ← 总是继承的 `coordinator` 字段 (= root) 标签：“商店”， )..bindLayout(ShopLayout.new); @覆盖 List 获取路径 => [shopStack]; @覆盖 FutureOr parseRouteFromUri(Uri uri) => switch (uri.pathSegments) { ['shop'] => ShopHomeRoute(), ['商店', '产品', 最终 id] => ProductDetailRoute(id: id), _ => null, // ← 对于无法识别的 URI 必须返回 null }; } **规则：** * 对于无法识别的 URI 始终返回“null”，以便其他模块可以声明它们。 * 将“coordinator”（继承字段）用于“NavigationPath.createWith”——它始终引用拥有导航状态的根协调器。 * `bindLayout(LayoutClass.new)` 采用构造函数，而不是实例。 ** ** ## 4\.路线定义 // 标准路线类 ShopHomeRoute 扩展 AppRoute { @覆盖对象？获取parentLayoutKey => ShopLayout； // 匹配 RouteLayout.layoutKey （默认：runtimeType） @覆盖 Uri toUri() => Uri.parse('/shop'); @覆盖 Widget build（协变 AppCoordinator 协调器，BuildContext 上下文）{ 返回商城首页( onProductTap: (id) => coordinator.push(ProductDetailRoute(id: id)), ）； } } // 带参数的路由——必须覆盖 props 类 ProductDetailRoute 扩展 AppRoute { ProductDetailRoute({必填 this.id}); 最终字符串ID； @覆盖 List 获取 props => [id]; @覆盖对象？获取parentLayoutKey => ShopLayout； @覆盖 Uri toUri() => Uri.parse('/shop/products/$id'); @覆盖 Widget build（协变 AppCoordinator 协调器，BuildContext 上下文）=> 产品详细信息页面（id：id）； } **规则：** * `parentLayoutKey` 必须与目标 `RouteLayout` 的 `layoutKey` 完全匹配。默认的`layoutKey`是`runtimeType`，所以使用布局类`Type`是最简单的。 * 覆盖带有参数的路由的`props`。 * `toUri()` 用于深层链接和 URL 同步。 > 对于仅重定向路由，请参阅 ADVANCED.md 中的 [RedirectRule]()。 ** ** ## 5\.布局 class ShopLayout 使用 RouteLayout 扩展 AppRoute { @覆盖 StackPathresolvePath(协变AppCoordinator协调器) => coordinator.getModule().shopStack; //layoutKey默认为runtimeType——仅当您需要自定义值时才覆盖 // @override 对象获取layoutKey => 'ShopLayout'; @覆盖 Widget build（协变 AppCoordinator 协调器，BuildContext 上下文）{ 返回脚手架（ appBar: AppBar(标题: const Text('商店')), body: buildPath(coordinator), // 渲染活动子路由）； } } **规则：** * 使用`buildPath(coordinator)`来渲染子路由——不要**调用`super.build()`。 * `resolvePath` 必须返回模块中 `bindLayout` 的确切 `NavigationPath`。 * 对于选项卡导航，请参阅 ADVANCED.md 中的 [IndexedStackPath]()。 ** ** ## 6\.导航 coordinator.push(ProductDetailRoute(id: '42')); // 添加到堆栈 coordinator.navigate(ShopHomeRoute()); // 弹出现有的或推送新的协调器.replace(SettingsRoute()); // 全状态重置协调员.pop(); // 弹出顶部路由 // 从 URI 字符串导航（例如深层链接）：最终路线=等待coordinator.parseRouteFromUri(Uri.parse('/shop/products/42')); 协调员.push(路线!); 重定向规则会在每次导航调用时自动运行。 > 有关 `pushReplacement`、`pushOrMoveToTop`、`tryPop`、`recover` 和决策流程图的完整详细信息，请参阅 [NAVIGATION.md]()。 ** ** ## 7\.文件结构约定 lib/src/路由器/ ├── coordinator.dart ← 根协调器或协调器作为模块 ├──route.dart ← 基本路由类型（例如AppRoute） ├── _public.dart ← Barrel：导出模块+公共路由+公共规则 ├──规则/ │ ├── auth_required.dart │ └──force_redirect.dart └── 航线/ ├── (auth)/ ← 路由组（共享布局） │ ├── _layout.dart ← 该组的布局 │ ├── sign_in.dart ← /sign-in │ └──忘记密码.dart ├──（仪表板）/ │ ├── _layout.dart │ ├── _index.dart ← 索引/仅重定向路由 │ └── transactions/ ← URI 段目录 │ ├── _index.dart ← /交易 │ └── [id].dart ← /transactions/:id (命名参数路由) │ └── 博客/ │ ├── _layout.dart ← 博客布局 │ └── [...slug].dart ← /blog/* (catch-all 参数路由) └── not_found.dart **惯例：** * `(group)/` — 带括号的目录是**布局组**（仅限组织）。它们**不会**出现在 URI 中。内部的路线共享一个布局。 * `group/` — 裸目录（无括号）**确实**出现在 URI 中。 `transactions/` → URI 包括 `/transactions/...`。 * `_layout.dart` — 其组的 `RouteLayout`；以“_”为前缀，因为它是结构性的，而不是面向用户的路线。 * `_index.dart` — 目录的索引路由（通常是仅重定向路由）。 * `[param].dart` — **命名参数路由**文件。括号反映了动态 URI 段（例如 `[id].dart` → `/transactions/:id`）。 * `[...param].dart` — **包罗万象的参数路由**文件。将所有剩余的 URI 段捕获为单个列表（例如“[...slug].dart”→“/blog/*”）。 * `_public.dart` — 仅导出公共符号的桶文件。 * `rules/` — 可重用的 `RedirectRule` 实现。 > 参数路由类的详细示例请参见[命名参数路由]()和[Catch-All Parameter ADVANCED.md 中的路由]()。 ** ** ## 8\.命名约定 ### 路线类别图案|示例|当 ---|---|--- `<功能>路线` | `SignInRoute`、`TransactionRoute` |标准页面路由 `<功能>详细路线` | `交易详细路由` |带有“[id]”的详细信息页面 `<功能>索引路由` | `DashboardIndexRoute` |索引/仅重定向路由 `<功能>选项卡` | `HomeTab`、`ShopTab` | “IndexedStackPath”中的选项卡 `未找到路线` | `未找到路线` |第404章包罗万象 ### 布局、模块和规则类图案|示例|当 ---|---|--- `<功能>布局` | `AuthLayout`、`DashboardLayout` |布局外壳 `<功能>模块` | `AuthModule`、`ShopModule` |简单的`RouteModule` `<功能>协调器` | `商店协调员` |协调器作为模块（具有子模块） `<条件>规则` | `AuthRequiredRule`、`AlreadyAuthRule` |重定向规则 ### URI 模式图案|示例|路线 ---|---|--- `/功能` | `/登录` | `登录路线` `/feature/:id` | `/交易/abc123` | `TransactionDetailRoute(id:'abc123')` `/组/功能` | `/商店/产品` | `产品列表路由` `/group/feature/:id` | `/商店/产品/42` | `产品详细路由（id：'42'）` 对 URI 段使用短横线大小写。对资源详细路径使用单数名词（`/transaction/:id` 而不是 `/transactions/:id`）。 NavigationPath 标签使用短横线大小写：“auth”、“dashboard”、“shop-products”。 ** ** ## 9\.添加新功能：清单 1. **创建路由**——扩展基础路由类型；设置`parentLayoutKey`，`toUri()`，`build()`，`props`。 2. **在所属模块的`parseRouteFromUri`中注册**。 3. 如果从外部导航到，则从“_public.dart”桶**导出**。 4. **新布局组？** — 使用 `RouteLayout` 创建 `(group)/_layout.dart`，使用 `bindLayout` 创建 `NavigationPath`，添加到 `paths`。 5. **新模块？** — 创建扩展 `RouteModule` 的 `module.dart`，在父级的 `defineModules()` 中注册。 6. **带有子模块的新功能组？** — 使用 [Coordinator-as-Module]() 模式。 ** ** ## 常见错误错误|修复 ---|--- 模块中的“parseRouteFromUri”不为非拥有的 URI 返回“null” |必须返回“null”，以便其他模块可以声明该 URI `parentLayoutKey` 与 `layoutKey` 不匹配 |默认 `layoutKey` 通常是 `runtimeType` — 使用布局类 `Type` 作为 `parentLayoutKey` 覆盖 `paths` 时忘记 `...super.paths` |始终传播“super.paths”以包含根和继承的模块路径在“CoordinatorModular”协调器上覆盖“parseRouteFromUri” |不要——`CoordinatorModular` 处理它；改为覆盖 `notFoundRoute` 独立的“Coordinator”从“parseRouteFromUri”返回“null” |独立协调器绝不能返回“null”；添加一个包罗万象的案例

禅路由器

包含技能