From 0771a7ad8575244d520093951574df7947abe0ba Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Sat, 7 Feb 2026 19:49:13 +0800
Subject: [PATCH] =?UTF-8?q?refactor(ui):=20=E6=9B=B4=E6=96=B0UI=E8=B7=AF?=
 =?UTF-8?q?=E7=94=B1=E5=92=8C=E9=A1=B5=E9=9D=A2=E8=A1=8C=E4=B8=BA=E6=8E=A5?=
 =?UTF-8?q?=E5=8F=A3=E5=AE=9A=E4=B9=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 修改HasVisibleInLayer方法签名，添加uiKey参数以精确检查特定UI可见性
- 在IUiPageBehavior接口中添加IsVisible属性用于获取页面可见状态
- 从IUiPageBehavior接口中移除RequiresMask属性
- 为ClearLayer和GetFromLayer方法添加完整的XML文档注释
- 更新CanvasItemUiPageBehavior实现以支持新的IsVisible属性
- 优化UI层级检查逻辑，提高可见性判断准确性
---
 GFramework.Game.Abstractions/ui/IUiPageBehavior.cs | 10 +++++-----
 GFramework.Game.Abstractions/ui/IUiRouter.cs       | 10 +++++++++-
 GFramework.Game/ui/UiRouterBase.cs                 |  8 ++++++--
 GFramework.Godot/ui/CanvasItemUiPageBehavior.cs    | 14 ++++++++------
 4 files changed, 28 insertions(+), 14 deletions(-)

diff --git a/GFramework.Game.Abstractions/ui/IUiPageBehavior.cs b/GFramework.Game.Abstractions/ui/IUiPageBehavior.cs
index c5ab865..a91e9df 100644
--- a/GFramework.Game.Abstractions/ui/IUiPageBehavior.cs
+++ b/GFramework.Game.Abstractions/ui/IUiPageBehavior.cs
@@ -23,6 +23,11 @@ public interface IUiPageBehavior
     /// </summary>
     bool IsAlive { get; }
 
+    /// <summary>
+    ///     获取页面是否可见
+    /// </summary>
+    bool IsVisible { get; }
+
     /// <summary>
     ///     获取页面是否为模态页面
     /// </summary>
@@ -33,11 +38,6 @@ public interface IUiPageBehavior
     /// </summary>
     bool BlocksInput { get; }
 
-    /// <summary>
-    ///     获取页面是否需要蒙版
-    /// </summary>
-    bool RequiresMask { get; }
-
     /// <summary>
     ///     页面进入时调用的方法
     /// </summary>
diff --git a/GFramework.Game.Abstractions/ui/IUiRouter.cs b/GFramework.Game.Abstractions/ui/IUiRouter.cs
index db92195..1ca311c 100644
--- a/GFramework.Game.Abstractions/ui/IUiRouter.cs
+++ b/GFramework.Game.Abstractions/ui/IUiRouter.cs
@@ -171,17 +171,25 @@ public interface IUiRouter : ISystem
     /// <summary>
     ///     清空指定层级的所有UI
     /// </summary>
+    /// <param name="layer">要清空的UI层级。</param>
+    /// <param name="destroy">是否销毁UI实例。如果为true，则会销毁UI实例；否则仅从层级中移除。</param>
     void ClearLayer(UiLayer layer, bool destroy = false);
 
     /// <summary>
     ///     从指定层级获取UI实例
     /// </summary>
+    /// <param name="uiKey">UI的唯一标识符。</param>
+    /// <param name="layer">要查询的UI层级。</param>
+    /// <returns>返回与指定键关联的UI行为接口实例；如果未找到则返回null。</returns>
     IUiPageBehavior? GetFromLayer(string uiKey, UiLayer layer);
 
     /// <summary>
     ///     判断指定层级是否存在可见UI
     /// </summary>
-    bool HasVisibleInLayer(UiLayer layer);
+    /// <param name="uiKey">要检查的UI的唯一标识符</param>
+    /// <param name="layer">要检查的UI层级</param>
+    /// <returns>如果在指定层级中存在可见的UI，则返回true；否则返回false</returns>
+    bool HasVisibleInLayer(string uiKey, UiLayer layer);
 
     #endregion
 }
\ No newline at end of file
diff --git a/GFramework.Game/ui/UiRouterBase.cs b/GFramework.Game/ui/UiRouterBase.cs
index d5fddb8..0449368 100644
--- a/GFramework.Game/ui/UiRouterBase.cs
+++ b/GFramework.Game/ui/UiRouterBase.cs
@@ -607,9 +607,13 @@ public abstract class UiRouterBase : AbstractSystem, IUiRouter
     /// <summary>
     ///     判断指定层级是否有UI显示
     /// </summary>
-    public bool HasVisibleInLayer(UiLayer layer)
+    public bool HasVisibleInLayer(string uiKey, UiLayer layer)
     {
-        return _layers.TryGetValue(layer, out var layerDict) && layerDict.Count > 0;
+        if (!_layers.TryGetValue(layer, out var layerDict) ||
+            !layerDict.TryGetValue(uiKey, out var page))
+            return false;
+
+        return page.IsVisible;
     }
 
     #endregion
diff --git a/GFramework.Godot/ui/CanvasItemUiPageBehavior.cs b/GFramework.Godot/ui/CanvasItemUiPageBehavior.cs
index 1b9a1ea..ff0f6ab 100644
--- a/GFramework.Godot/ui/CanvasItemUiPageBehavior.cs
+++ b/GFramework.Godot/ui/CanvasItemUiPageBehavior.cs
@@ -1,4 +1,4 @@
-using GFramework.Game.Abstractions.ui;
+using GFramework.Game.Abstractions.ui;
 using GFramework.Godot.extensions;
 using Godot;
 
@@ -30,8 +30,15 @@ public class CanvasItemUiPageBehavior<T>(T owner, string key) : IUiPageBehavior
     /// <summary>
     ///     获取页面是否存活状态
     /// </summary>
+    /// <returns>如果页面节点有效则返回true，否则返回false</returns>
     public bool IsAlive => owner.IsValidNode();
 
+    /// <summary>
+    ///     获取页面是否可见状态
+    /// </summary>
+    /// <returns>如果页面可见则返回true，否则返回false</returns>
+    public bool IsVisible => owner.Visible;
+
     /// <summary>
     ///     页面进入时调用
     /// </summary>
@@ -110,9 +117,4 @@ public class CanvasItemUiPageBehavior<T>(T owner, string key) : IUiPageBehavior
     ///     获取或设置页面是否阻止输入
     /// </summary>
     public bool BlocksInput { get; set; } = true;
-
-    /// <summary>
-    ///     获取或设置页面是否需要遮罩层
-    /// </summary>
-    public bool RequiresMask { get; set; }
 }
\ No newline at end of file