From d2e273901692c48c783dc127260442937d3d5ea2 Mon Sep 17 00:00:00 2001
From: GeWuYou <95328647+GeWuYou@users.noreply.github.com>
Date: Sun, 8 Feb 2026 10:09:35 +0800
Subject: [PATCH] =?UTF-8?q?feat(ui):=20=E6=B7=BB=E5=8A=A0=E9=80=9A?=
 =?UTF-8?q?=E8=BF=87UI=E9=94=AE=E9=9A=90=E8=97=8F=E6=8C=87=E5=AE=9A?=
 =?UTF-8?q?=E5=B1=82=E7=BA=A7UI=E7=9A=84=E5=8A=9F=E8=83=BD?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 在UiRouterBase中新增HideByKey方法，支持根据UI键隐藏指定层级中的UI
- 为IUiPageBehavior接口添加Handle属性，用于获取或设置当前UI句柄
- 在IUiRouter接口中定义HideByKey方法契约
- 为CanvasItemUiPageBehaviorBase实现Handle属性
- 修复UI页面行为基类中的注释描述
- 在路由初始化过程中设置页面句柄以确保正确的UI管理
- [release ci]
---
 .../ui/IUiPageBehavior.cs                     | 16 ++++++++++++-
 GFramework.Game.Abstractions/ui/IUiRouter.cs  |  9 +++++++
 GFramework.Game/ui/UiRouterBase.cs            | 24 ++++++++++++++++++-
 .../ui/CanvasItemUiPageBehaviorBase.cs        | 14 ++++++++++-
 4 files changed, 60 insertions(+), 3 deletions(-)

diff --git a/GFramework.Game.Abstractions/ui/IUiPageBehavior.cs b/GFramework.Game.Abstractions/ui/IUiPageBehavior.cs
index 8232dd0..8eae2cd 100644
--- a/GFramework.Game.Abstractions/ui/IUiPageBehavior.cs
+++ b/GFramework.Game.Abstractions/ui/IUiPageBehavior.cs
@@ -7,11 +7,25 @@ namespace GFramework.Game.Abstractions.ui;
 /// </summary>
 public interface IUiPageBehavior
 {
+    /// <summary>
+    ///     获取或设置当前UI句柄。
+    /// </summary>
+    /// <value>
+    ///     表示当前UI句柄的可空类型 <see cref="UiHandle"/>。
+    /// </value>
+    /// <remarks>
+    ///     此属性允许获取或设置与当前上下文关联的UI句柄。若未设置，则其值为 null。不可重入的ui句柄通常为null
+    /// </remarks>
+    UiHandle? Handle { get; set; }
+
     /// <summary>
     ///     获取当前UI层的实例。
     /// </summary>
+    /// <value>
+    ///     返回与当前上下文关联的 <see cref="UiLayer"/> 实例。
+    /// </value>
     /// <remarks>
-    ///     此属性用于访问与当前上下文关联的UI层对象。
+    ///     此属性用于访问与当前上下文关联的UI层对象，通常用于管理UI的层次结构和交互逻辑。
     /// </remarks>
     UiLayer Layer { get; }
 
diff --git a/GFramework.Game.Abstractions/ui/IUiRouter.cs b/GFramework.Game.Abstractions/ui/IUiRouter.cs
index 488c20a..08b68f3 100644
--- a/GFramework.Game.Abstractions/ui/IUiRouter.cs
+++ b/GFramework.Game.Abstractions/ui/IUiRouter.cs
@@ -198,5 +198,14 @@ public interface IUiRouter : ISystem
     /// <returns>如果在指定层级中存在可见的UI，则返回true；否则返回false。</returns>
     bool HasVisibleInLayer(UiHandle handle, UiLayer layer);
 
+    /// <summary>
+    ///     根据UI键隐藏指定层级中的UI。
+    /// </summary>
+    /// <param name="uiKey">UI的唯一标识键。</param>
+    /// <param name="layer">要操作的UI层级。</param>
+    /// <param name="destroy">是否销毁UI实例，默认为false。</param>
+    /// <param name="hideAll">是否隐藏所有匹配的UI实例，默认为false。</param>
+    void HideByKey(string uiKey, UiLayer layer, bool destroy = false, bool hideAll = false);
+
     #endregion
 }
\ No newline at end of file
diff --git a/GFramework.Game/ui/UiRouterBase.cs b/GFramework.Game/ui/UiRouterBase.cs
index ded1226..04fa8ff 100644
--- a/GFramework.Game/ui/UiRouterBase.cs
+++ b/GFramework.Game/ui/UiRouterBase.cs
@@ -363,6 +363,27 @@ public abstract class UiRouterBase : AbstractSystem, IUiRouter
         return page.IsVisible;
     }
 
+    /// <summary>
+    ///     根据UI键隐藏指定层级中的UI。
+    /// </summary>
+    /// <param name="uiKey">UI的唯一标识键。</param>
+    /// <param name="layer">要操作的UI层级。</param>
+    /// <param name="destroy">是否销毁UI实例，默认为false。</param>
+    /// <param name="hideAll">是否隐藏所有匹配的UI实例，默认为false。</param>
+    public void HideByKey(string uiKey, UiLayer layer, bool destroy = false, bool hideAll = false)
+    {
+        var handles = GetAllFromLayer(uiKey, layer);
+        if (handles.Count == 0) return;
+
+        if (hideAll)
+            foreach (var h in handles)
+            {
+                Hide(h, layer, destroy);
+            }
+        else
+            Hide(handles[0], layer, destroy);
+    }
+
     #endregion
 
     #region Route Guards
@@ -452,7 +473,8 @@ public abstract class UiRouterBase : AbstractSystem, IUiRouter
         // 初始化层级字典
         if (!_layers.ContainsKey(layer))
             _layers[layer] = new Dictionary<string, IUiPageBehavior>();
-
+        // 设置句柄
+        page.Handle = handle;
         var layerDict = _layers[layer];
 
         // 检查重入性
diff --git a/GFramework.Godot/ui/CanvasItemUiPageBehaviorBase.cs b/GFramework.Godot/ui/CanvasItemUiPageBehaviorBase.cs
index 0c42228..d94bd23 100644
--- a/GFramework.Godot/ui/CanvasItemUiPageBehaviorBase.cs
+++ b/GFramework.Godot/ui/CanvasItemUiPageBehaviorBase.cs
@@ -55,9 +55,21 @@ public abstract class CanvasItemUiPageBehaviorBase<T> : IUiPageBehavior
 
     #region 抽象属性 - 子类必须实现
 
+    /// <summary>
+    ///     获取或设置当前UI句柄。
+    /// </summary>
+    /// <value>
+    ///     表示当前UI句柄的可空类型 <see cref="UiHandle"/>。
+    /// </value>
+    /// <remarks>
+    ///     此属性允许获取或设置与当前上下文关联的UI句柄。若未设置，则其值为 null。不可重入的ui句柄通常为null
+    /// </remarks>
+    public UiHandle? Handle { get; set; }
+
     /// <summary>
     ///     获取 UI 所属的层级。
-    ///     由子类指定具体值。
+    ///     该属性由子类实现并指定具体的层级值。
+    ///     层级用于确定 UI 元素在界面中的显示顺序和逻辑分组。
     /// </summary>
     public abstract UiLayer Layer { get; }