UI系统

Assets/_Game/Scripts/UI/Navigation/IUINavigator.cs

@@ -0,0 +1,47 @@
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace BaseGames.UI
+{
+    /// <summary>
+    /// 统一 UI 导航栈服务。所有面板（主菜单子面板 + 游戏内面板）经此压栈/出栈，
+    /// 由它统一保证：只有栈顶可交互、下层被屏蔽出导航图、ESC 逐层回退、出栈恢复焦点。
+    ///
+    /// <para>设计要点：</para>
+    /// <list type="bullet">
+    /// <item>单一取消入口：导航器是 EVT_UICancelPressed 的唯一消费者，ESC 只关栈顶一层。</item>
+    /// <item>场景作用域：面板可能位于会被卸载的关卡 / 主菜单场景，导航器订阅 sceneUnloaded
+    ///       清理随场景销毁的栈层，每次操作对已销毁面板兜底。</item>
+    /// <item>非面板的"底层上下文"（如主菜单按钮组、游戏内 HUD）不入栈，由各自上下文
+    ///       订阅 <see cref="StackChanged"/> / 读 <see cref="Depth"/> 自行屏蔽。</item>
+    /// </list>
+    /// </summary>
+    public interface IUINavigator
+    {
+        /// <summary>当前栈顶面板；空栈为 null。</summary>
+        UIPanelBase Top { get; }
+
+        /// <summary>栈深度（已打开的面板层数）。</summary>
+        int Depth { get; }
+
+        /// <summary>栈结构变化（任何 Push / Pop / 场景清理）后触发，供底层上下文屏蔽自身。</summary>
+        event Action StackChanged;
+
+        /// <summary>压栈打开面板。<paramref name="mode"/> 为空时用面板自身 <see cref="UIPanelBase.DefaultMode"/>。</summary>
+        void Push(UIPanelBase panel, PushMode? mode = null);
+
+        /// <summary>关闭栈顶并恢复下层（若有）。空栈无操作。</summary>
+        void Pop();
+
+        /// <summary>清空整个栈（逐层关闭）。</summary>
+        void PopToRoot();
+
+        /// <summary>
+        /// 压栈打开结果面板并等待玩家给出结果（确认 / 选择）。
+        /// 面板被出栈（含 ESC 取消）、被销毁或 <paramref name="ct"/> 取消时，
+        /// 以面板的取消默认值兜底完成，绝不悬挂 await。
+        /// </summary>
+        Task<T> PushForResultAsync<T>(UIResultPanel<T> panel, CancellationToken ct = default);
+    }
+}