6. Guard 与过渡动画

ISusRouteGuard —— 导航保护

public interface ISusRouteGuard
{
    bool CanEnter(SusRoute from, SusRoute to);
    bool CanLeave(SusRoute from, SusRoute to);
}

全局 guard（所有导航）

router.BeforeEach((from, to) =>
{
    if (to.Record?.Config?.Meta?.ContainsKey("requiresAuth") == true
        && to.Record.Config.Meta["requiresAuth"] is true
        && !AuthService.IsLoggedIn)
    {
        router.Push("/login");
        return false;
    }
    return true;
});

按路由的 guard

public class AdminGuard : ISusRouteGuard
{
    public bool CanEnter(SusRoute from, SusRoute to) => User.IsAdmin;
    public bool CanLeave(SusRoute from, SusRoute to) => true;
}

router.Register("/admin", typeof(AdminScreen), new SusRouteConfig
{
    Guard = new AdminGuard(),
    Meta = new() { ["requiresAuth"] = true, ["role"] = "admin" }
});

BeforeResolve —— 在创建屏幕之前

router.BeforeResolve((from, to) =>
{
    if (to.FullPath == "/battle/0") return false; // invalid id
    return true;
});

异步 guard（BeforeEachAsync / BeforeResolveAsync）

对于需要 await 的检查（服务器请求、数据加载），提供了异步 guard：

router.BeforeEachAsync(async (from, to) =>
{
    var ok = await AuthService.CheckSessionAsync();
    return ok;
});

router.BeforeResolveAsync(async (from, to) =>
{
    return await DataService.PreloadAsync(to.FullPath);
});

PushAsync / ReplaceAsync 的执行顺序：

1. BeforeEachAsync（全部，依次执行，await）
2. BeforeResolveAsync（全部，依次执行，await）
3. 同步管线（BeforeLeave → BeforeEach → CanEnter → BeforeResolve → 创建屏幕）

⚠️ 限制： 同步导航（Push / Replace / Back / Forward）不会运行异步 guard——它们无法被同步地 await。如果注册了异步 guard，但调用的是同步 Push，这些 guard 会被跳过（Editor/Development 构建会记录 [GuardAudit] 警告）。对于有异步检查的路由，请使用 PushAsync / ReplaceAsync。

SusRouteTransition —— 过渡动画

API

public class SusRouteTransition
{
    public float Duration { get; }
    public static SusRouteTransition None();
    public static SusRouteTransition Fade(float duration = 0.2f);
    public static SusRouteTransition SlideLeft(float duration = 0.3f);
    public static SusRouteTransition SlideRight(float duration = 0.3f);

    public void PlayIn(VisualElement target);
    public void PlayOut(VisualElement target);
}

实现（基于代码）

动画使用 schedule.Execute 加上对 style.opacity / style.translate 的操作：

public static SusRouteTransition Fade(float d = 0.2f) => new(
    playIn: el => { /* opacity 0 → 1 over d seconds */ },
    playOut: el => { /* opacity 1 → 0 over d seconds */ },
    duration: d
);

public static SusRouteTransition SlideLeft(float d = 0.3f) => new(
    playIn: el => { /* translate X: 100px → 0 over d seconds */ },
    playOut: el => { /* translate X: 0 → -100px over d seconds */ },
    duration: d
);

用法

new SusRouteConfig { Transition = SusRouteTransition.Fade(0.2f) }
new SusRouteConfig { Transition = SusRouteTransition.SlideLeft(0.3f) }
new SusRouteConfig { Transition = SusRouteTransition.SlideRight(0.3f) }
new SusRouteConfig { Transition = SusRouteTransition.None() }

动画在 SusRouteView.OnRouteChanged 中播放：旧屏幕上执行 PlayOut，新屏幕上执行 PlayIn。