From dadda8803f1c45ca2443f4f59cb7b683fdeb2582 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Mon, 2 Feb 2026 22:19:31 +0800
Subject: [PATCH] =?UTF-8?q?feat(ui):=20=E6=B7=BB=E5=8A=A0UI=E5=B1=82?=
 =?UTF-8?q?=E7=BA=A7=E7=AE=A1=E7=90=86=E5=92=8C=E4=BC=98=E5=8C=96Peek?=
 =?UTF-8?q?=E6=96=B9=E6=B3=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 修改Peek方法返回类型为可空IUiPageBehavior?以避免空栈异常
- 在IUiRouter接口中添加完整的UI层级管理功能
- 新增Show方法支持在指定层级显示UI（Overlay/Modal/Toast等）
- 新增Hide方法支持隐藏指定层级的UI
- 新增ClearLayer方法支持清空指定层级的所有UI
- 新增GetFromLayer方法支持从指定层级获取UI实例
- 新增HasVisibleInLayer方法支持判断指定层级是否存在可见UI
- 完善UI路由系统的层级控制能力
- [release ci]
---
 GFramework.Game.Abstractions/ui/IUiRouter.cs | 40 +++++++++++++++++++-
 GFramework.Game/ui/UiRouterBase.cs           |  4 +-
 2 files changed, 41 insertions(+), 3 deletions(-)

diff --git a/GFramework.Game.Abstractions/ui/IUiRouter.cs b/GFramework.Game.Abstractions/ui/IUiRouter.cs
index d257ff2..cc6c2e9 100644
--- a/GFramework.Game.Abstractions/ui/IUiRouter.cs
+++ b/GFramework.Game.Abstractions/ui/IUiRouter.cs
@@ -103,7 +103,7 @@ public interface IUiRouter : ISystem
     ///     获取当前栈顶的UI页面行为对象
     /// </summary>
     /// <returns>栈顶的IUiPageBehavior对象，如果栈为空则返回null</returns>
-    IUiPageBehavior Peek();
+    IUiPageBehavior? Peek();
 
 
     /// <summary>
@@ -137,4 +137,42 @@ public interface IUiRouter : ISystem
     void RemoveGuard(IUiRouteGuard guard);
 
     #endregion
+
+    #region Layer UI
+
+    /// <summary>
+    ///     在指定层级显示UI（Overlay / Modal / Toast等）
+    /// </summary>
+    void Show(
+        string uiKey,
+        UiLayer layer,
+        IUiPageEnterParam? param = null,
+        UiInstancePolicy instancePolicy = UiInstancePolicy.Reuse);
+
+    /// <summary>
+    ///     在指定层级显示UI（基于已存在实例）
+    /// </summary>
+    void Show(IUiPageBehavior page, UiLayer layer);
+
+    /// <summary>
+    ///     隐藏指定层级的UI
+    /// </summary>
+    void Hide(string uiKey, UiLayer layer, bool destroy = false);
+
+    /// <summary>
+    ///     清空指定层级的所有UI
+    /// </summary>
+    void ClearLayer(UiLayer layer, bool destroy = false);
+
+    /// <summary>
+    ///     从指定层级获取UI实例
+    /// </summary>
+    IUiPageBehavior? GetFromLayer(string uiKey, UiLayer layer);
+
+    /// <summary>
+    ///     判断指定层级是否存在可见UI
+    /// </summary>
+    bool HasVisibleInLayer(UiLayer layer);
+
+    #endregion
 }
\ No newline at end of file
diff --git a/GFramework.Game/ui/UiRouterBase.cs b/GFramework.Game/ui/UiRouterBase.cs
index 5f33f2d..f480281 100644
--- a/GFramework.Game/ui/UiRouterBase.cs
+++ b/GFramework.Game/ui/UiRouterBase.cs
@@ -267,9 +267,9 @@ public abstract class UiRouterBase : AbstractSystem, IUiRouter
     ///     获取页面栈顶元素，但不移除该元素
     /// </summary>
     /// <returns>返回栈顶的IUiPageBehavior元素</returns>
-    public IUiPageBehavior Peek()
+    public IUiPageBehavior? Peek()
     {
-        return _stack.Peek();
+        return _stack.Count == 0 ? null : _stack.Peek();
     }