feat(ui): 添加UI路由基类和相关接口定义

GFramework.Game.Abstractions/UI/IUiActionHandler.cs

@@ -0,0 +1,17 @@
+namespace GFramework.Game.Abstractions.UI;
+
+/// <summary>
+///     由页面视图实现，用于接收路由仲裁后的 UI 语义动作。
+/// </summary>
+public interface IUiActionHandler
+{
+    /// <summary>
+    ///     处理一个 UI 语义动作。
+    /// </summary>
+    /// <param name="action">当前要处理的动作。</param>
+    /// <returns>
+    ///     如果页面已经完成处理则返回 <see langword="true" />；
+    ///     返回 <see langword="false" /> 时，路由器仍会把声明捕获该动作视为已消费。
+    /// </returns>
+    bool TryHandleUiAction(UiInputAction action);
+}

GFramework.Game.Abstractions/UI/IUiInteractionProfileProvider.cs

@@ -0,0 +1,16 @@
+using GFramework.Game.Abstractions.Enums;
+
+namespace GFramework.Game.Abstractions.UI;
+
+/// <summary>
+///     由页面视图实现，用于按运行时状态动态提供交互语义配置。
+/// </summary>
+public interface IUiInteractionProfileProvider
+{
+    /// <summary>
+    ///     获取页面当前应使用的交互配置。
+    /// </summary>
+    /// <param name="layer">页面绑定的默认 UI 层级。</param>
+    /// <returns>当前页面的交互配置。</returns>
+    UiInteractionProfile GetUiInteractionProfile(UiLayer layer);
+}

GFramework.Game.Abstractions/UI/IUiPageBehavior.cs

@@ -66,6 +66,11 @@ public interface IUiPageBehavior : IRoute
     /// </summary>
     bool BlocksInput { get; }
 
+    /// <summary>
+    ///     获取页面当前的输入、阻断与暂停交互配置。
+    /// </summary>
+    UiInteractionProfile InteractionProfile { get; }
+
     /// <summary>
     ///     页面进入时调用的方法
     /// </summary>
@@ -96,4 +101,11 @@ public interface IUiPageBehavior : IRoute
     ///     页面重新显示时调用的方法
     /// </summary>
     void OnShow();
-}
+
+    /// <summary>
+    ///     尝试处理一个经过路由器仲裁后的 UI 语义动作。
+    /// </summary>
+    /// <param name="action">当前动作。</param>
+    /// <returns>如果页面已经显式处理该动作则返回 <see langword="true" />。</returns>
+    bool TryHandleUiAction(UiInputAction action);
+}

GFramework.Game.Abstractions/UI/IUiRouter.cs

@@ -186,5 +186,40 @@ UiHandle Show(
     /// <param name="hideAll">是否隐藏所有匹配的UI实例，默认为false。</param>
     void HideByKey(string uiKey, UiLayer layer, bool destroy = false, bool hideAll = false);
 
+    /// <summary>
+    ///     查询当前对指定 UI 语义动作拥有最高优先级捕获权的页面。
+    /// </summary>
+    /// <param name="action">要查询的动作。</param>
+    /// <returns>动作所有者；如果当前没有页面声明捕获该动作则返回 <see langword="null" />。</returns>
+    IUiPageBehavior? GetUiActionOwner(UiInputAction action);
+
+    /// <summary>
+    ///     尝试把语义动作分发给当前拥有该动作捕获权的页面。
+    /// </summary>
+    /// <param name="action">当前动作。</param>
+    /// <returns>如果该动作已被某个页面捕获并完成分发，则返回 <see langword="true" />。</returns>
+    bool TryDispatchUiAction(UiInputAction action);
+
+    /// <summary>
+    ///     尝试把语义动作分发给当前拥有该动作捕获权的页面。
+    /// </summary>
+    /// <param name="action">当前动作。</param>
+    /// <returns>如果该动作已被某个页面捕获并完成分发，则返回 <see langword="true" />。</returns>
+    [Obsolete(
+        "Use TryDispatchUiAction(UiInputAction action) to emphasize dispatch semantics instead of handler success.")]
+    bool TryHandleUiAction(UiInputAction action);
+
+    /// <summary>
+    ///     判断当前可见 UI 是否阻断 World 指针输入。
+    /// </summary>
+    /// <returns>如果 World 指针输入应被阻断则返回 <see langword="true" />。</returns>
+    bool BlocksWorldPointerInput();
+
+    /// <summary>
+    ///     判断当前可见 UI 是否阻断 World 语义动作输入。
+    /// </summary>
+    /// <returns>如果 World 动作输入应被阻断则返回 <see langword="true" />。</returns>
+    bool BlocksWorldActionInput();
+
     #endregion
-}
+}

GFramework.Game.Abstractions/UI/UiInputAction.cs

@@ -0,0 +1,23 @@
+namespace GFramework.Game.Abstractions.UI;
+
+/// <summary>
+///     定义框架级 UI 语义动作。
+///     这些动作由输入层映射后交给 UI 路由统一仲裁，避免页面直接依赖具体按键或设备事件。
+/// </summary>
+public enum UiInputAction
+{
+    /// <summary>
+    ///     未指定动作。
+    /// </summary>
+    None = 0,
+
+    /// <summary>
+    ///     取消、返回或关闭当前 UI。
+    /// </summary>
+    Cancel = 1,
+
+    /// <summary>
+    ///     确认当前 UI 操作。
+    /// </summary>
+    Confirm = 2
+}

GFramework.Game.Abstractions/UI/UiInputActionMask.cs

@@ -0,0 +1,23 @@
+namespace GFramework.Game.Abstractions.UI;
+
+/// <summary>
+///     以位标记形式声明 UI 页面要捕获的语义动作集合。
+/// </summary>
+[Flags]
+public enum UiInputActionMask
+{
+    /// <summary>
+    ///     不捕获任何动作。
+    /// </summary>
+    None = 0,
+
+    /// <summary>
+    ///     捕获取消动作。
+    /// </summary>
+    Cancel = 1 << 0,
+
+    /// <summary>
+    ///     捕获确认动作。
+    /// </summary>
+    Confirm = 1 << 1
+}

GFramework.Game.Abstractions/UI/UiInteractionProfile.cs

@@ -0,0 +1,48 @@
+using GFramework.Core.Abstractions.Pause;
+
+namespace GFramework.Game.Abstractions.UI;
+
+/// <summary>
+///     描述一个 UI 页面在输入、World 阻断与暂停上的交互契约数据。
+/// </summary>
+/// <remarks>
+///     该类型仅承载抽象层需要共享的页面交互配置，不包含默认值工厂或动作判定等运行时策略。
+///     运行时层可在不反向依赖 Abstractions 的前提下，通过专门的 helper 为该 DTO 提供默认值和语义判定。
+/// </remarks>
+public sealed class UiInteractionProfile
+{
+    /// <summary>
+    ///     声明当前页面要捕获的语义动作集合。
+    /// </summary>
+    public UiInputActionMask CapturedActions { get; init; } = UiInputActionMask.None;
+
+    /// <summary>
+    ///     指示当前页面是否阻断 World 指针输入，例如地图点击或相机拖拽。
+    /// </summary>
+    public bool BlocksWorldPointerInput { get; init; }
+
+    /// <summary>
+    ///     指示当前页面是否阻断 World 语义动作输入，例如 gameplay 快捷键。
+    /// </summary>
+    public bool BlocksWorldActionInput { get; init; }
+
+    /// <summary>
+    ///     指示当前页面的可见性是否应驱动暂停栈。
+    /// </summary>
+    public UiPauseMode PauseMode { get; init; } = UiPauseMode.None;
+
+    /// <summary>
+    ///     当 <see cref="PauseMode" /> 生效时使用的暂停组。
+    /// </summary>
+    public PauseGroup PauseGroup { get; init; } = PauseGroup.Global;
+
+    /// <summary>
+    ///     当场景树暂停时，该页面是否仍需继续处理输入与动画。
+    /// </summary>
+    public bool ContinueProcessingWhenPaused { get; init; }
+
+    /// <summary>
+    ///     页面向暂停栈登记时使用的原因文本。
+    /// </summary>
+    public string PauseReason { get; init; } = string.Empty;
+}

GFramework.Game.Abstractions/UI/UiPauseMode.cs

@@ -0,0 +1,17 @@
+namespace GFramework.Game.Abstractions.UI;
+
+/// <summary>
+///     定义页面显示时与暂停系统的协作模式。
+/// </summary>
+public enum UiPauseMode
+{
+    /// <summary>
+    ///     页面显示不会触发暂停请求。
+    /// </summary>
+    None = 0,
+
+    /// <summary>
+    ///     页面在可见期间持有一个暂停请求，隐藏或销毁时释放。
+    /// </summary>
+    WhileVisible = 1
+}

GFramework.Game.Tests/GlobalUsings.cs

@@ -16,4 +16,8 @@
 global using System;
 global using System.Collections.Generic;
 global using System.Linq;
-global using System.Threading.Tasks;
+global using System.Threading.Tasks;
+global using System.Reflection;
+global using GFramework.Game.Abstractions.Enums;
+global using GFramework.Game.Abstractions.UI;
+global using GFramework.Game.UI;