48 lines
2.2 KiB
C#
48 lines
2.2 KiB
C#
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);
|
||
}
|
||
}
|