feat(ui): 添加通过UI键隐藏指定层级UI的功能

- 在UiRouterBase中新增HideByKey方法，支持根据UI键隐藏指定层级中的UI
- 为IUiPageBehavior接口添加Handle属性，用于获取或设置当前UI句柄
- 在IUiRouter接口中定义HideByKey方法契约
- 为CanvasItemUiPageBehaviorBase实现Handle属性
- 修复UI页面行为基类中的注释描述
- 在路由初始化过程中设置页面句柄以确保正确的UI管理
- [release ci]

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; }
 

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
 }

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];
 
         // 检查重入性

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; }