1. 包概览

Package: com.sharq-it.sus.router · Version: 1.0.16 · Analog: Vue Router

用途

SusRouter 是 SUS 的导航层。它将路由从宿主项目中单体式的 UI 导航器里提取出来，成为一个独立的包。

范围内	范围外
Push/Replace/Back/Forward/Go	UI 组件库
Guard 管道（BeforeEach/CanEnter/CanLeave/BeforeResolve）	响应式 — sus-core
模态框 + 栈（SusModalService + SusRouterModal）	游戏逻辑 — 宿主项目
基于代码的动画（Fade/Slide）
KeepAlive LRU 缓存（off-DOM）
具名/嵌套路由，redirect/alias
Query 参数，惰性加载
SusRouteLink — 声明式导航
SusApp.UseRouter — 流式挂载

快速开始

推荐使用 SusApp + UseRouter（Runtime/SusAppRouterExtensions.cs）：

using Sharq.Core;
using Sharq.Router;

SusApp.Create(uiDocument)
    .UseTheme(SusTheme.Dark)
    .UseRouter(new SusRouter(), r =>
    {
        r.Register("/", typeof(HomeScreen));
        r.Register("/settings", typeof(SettingsScreen));
    }, initialPath: "/")
    .Run();

完整 API 见 02-router-api.md（ReplaceNamed、HasRoute、RemoveRoute、Busy、MaxHistory、异步 guard）。

生态系统

sus-core — foundation (reactivity, SusComponent, OverlayHost)
    │
sus-router (this package) — navigation
    │
UI component library (optional, separate product)
    │
host project — your application

包结构

sus-router/
├── package.json
├── docs/                    ← package docs + README
├── Runtime/
│   ├── SusRouter.cs              ← Core: Register, Push, Replace, guards
│   ├── SusRoute.cs               ← SusRouteRecord, SusRouteConfig, SusRoute, ISusRouteGuard
│   ├── SusScreen.cs              ← Base screen class
│   ├── SusRouteView.cs           ← Visual container + KeepAlive LRU (off-DOM cache)
│   ├── SusRouteLink.cs           ← Link component
│   ├── SusModal.cs               ← SusRouterModal — modal base class
│   ├── SusModalService.cs        ← Modal stack (OverlayHost)
│   ├── SusRouteTransition.cs     ← Code-based animations (SusMotion)
│   ├── SusRouteBuilder.cs        ← Declarative route tree
│   ├── SusAppRouterExtensions.cs ← SusApp.UseRouter(...)
│   ├── SusOverlayServices.cs     ← Service aggregation
│   └── Services/
│       └── SusTransitionService.cs
├── Editor/Tests/
├── Runtime/Tests/
├── Samples~/                     ← 7 samples
│   ├── BasicRouting/
│   ├── KeepAlive/
│   ├── Guards/
│   ├── Modal/
│   ├── AdvancedRouting/
│   ├── RouteLink/
│   └── FullDemo/