feat(ui): 更新UI系统接口和实现

- 在IUiPageBehavior接口中添加Layer和IsReentrant属性
- 将IUiRouter的Show方法返回类型从void改为UiHandle
- 修改Hide、Resume、GetFromLayer等方法参数从uiKey改为UiHandle
- 新增UiHandle结构体用于唯一标识和管理UI实例
- 在CanvasItemUiPageBehavior中实现Layer和IsReentrant属性

GFramework.Game.Abstractions/ui/IUiPageBehavior.cs

@@ -1,4 +1,6 @@
-namespace GFramework.Game.Abstractions.ui;
+using GFramework.Game.Abstractions.enums;
+
+namespace GFramework.Game.Abstractions.ui;
 
 /// <summary>
 ///     UI页面行为接口，定义了UI页面的生命周期方法和状态管理
@@ -6,11 +8,30 @@
 public interface IUiPageBehavior
 {
     /// <summary>
-    ///     获取页面视图对象
+    ///     获取当前UI层的实例。
     /// </summary>
-    /// <returns>页面视图实例</returns>
+    /// <remarks>
+    ///     此属性用于访问与当前上下文关联的UI层对象。
+    /// </remarks>
+    UiLayer Layer { get; }
+
+    /// <summary>
+    ///     获取一个布尔值，指示当前操作是否为重入操作。
+    /// </summary>
+    /// <remarks>
+    ///     重入操作通常指在同一个执行上下文中多次调用相同的方法或逻辑。
+    ///     此属性可用于检测并避免重复执行可能导致异常或不一致状态的操作。
+    /// </remarks>
+    bool IsReentrant { get; }
+
+
+    /// <summary>
+    ///     获取页面视图对象。
+    /// </summary>
+    /// <returns>页面视图实例。</returns>
     object View { get; }
 
+
     /// <summary>
     ///     获取键值
     /// </summary>

GFramework.Game.Abstractions/ui/IUiRouter.cs

@@ -142,7 +142,7 @@ public interface IUiRouter : ISystem
     /// <param name="uiKey">要显示的UI页面的唯一标识符</param>
     /// <param name="layer">UI显示的层级，例如 Overlay、Modal 或 Toast</param>
     /// <param name="param">可选参数，用于传递给UI页面的初始化数据</param>
-    void Show(
+    UiHandle Show(
         string uiKey,
         UiLayer layer,
         IUiPageEnterParam? param = null);
@@ -150,46 +150,53 @@ public interface IUiRouter : ISystem
     /// <summary>
     ///     在指定层级显示UI（基于已存在实例）
     /// </summary>
-    void Show(IUiPageBehavior page, UiLayer layer);
+    UiHandle Show(IUiPageBehavior page, UiLayer layer);
 
     /// <summary>
     ///     隐藏指定层级的UI。
     /// </summary>
-    /// <param name="uiKey">要隐藏的UI的唯一标识符。</param>
+    /// <param name="handle">UI句柄，用于标识具体的UI实例。</param>
     /// <param name="layer">指定UI所在的层级。</param>
     /// <param name="destroy">是否销毁UI对象，默认为false，表示仅隐藏而不销毁。</param>
-    void Hide(string uiKey, UiLayer layer, bool destroy = false);
+    void Hide(UiHandle handle, UiLayer layer, bool destroy = false);
 
     /// <summary>
     ///     恢复指定层级的UI显示。
     /// </summary>
-    /// <param name="uiKey">要恢复显示的UI的唯一标识符。</param>
+    /// <param name="handle">UI句柄，用于标识具体的UI实例。</param>
     /// <param name="layer">指定UI所在的层级。</param>
-    void Resume(string uiKey, UiLayer layer);
+    void Resume(UiHandle handle, UiLayer layer);
-
 
     /// <summary>
-    ///     清空指定层级的所有UI
+    ///     清空指定层级的所有UI。
     /// </summary>
     /// <param name="layer">要清空的UI层级。</param>
     /// <param name="destroy">是否销毁UI实例。如果为true，则会销毁UI实例；否则仅从层级中移除。</param>
     void ClearLayer(UiLayer layer, bool destroy = false);
 
     /// <summary>
-    ///     从指定层级获取UI实例
+    ///     从指定层级获取UI实例。
     /// </summary>
-    /// <param name="uiKey">UI的唯一标识符。</param>
+    /// <param name="handle">UI句柄，用于标识具体的UI实例。</param>
     /// <param name="layer">要查询的UI层级。</param>
     /// <returns>返回与指定键关联的UI行为接口实例；如果未找到则返回null。</returns>
-    IUiPageBehavior? GetFromLayer(string uiKey, UiLayer layer);
+    UiHandle? GetFromLayer(UiHandle handle, UiLayer layer);
 
     /// <summary>
-    ///     判断指定层级是否存在可见UI
+    ///     从指定层级获取所有与给定UI键关联的UI实例。
     /// </summary>
-    /// <param name="uiKey">要检查的UI的唯一标识符</param>
+    /// <param name="uiKey">用于标识UI实例的键。</param>
-    /// <param name="layer">要检查的UI层级</param>
+    /// <param name="layer">要查询的UI层级。</param>
-    /// <returns>如果在指定层级中存在可见的UI，则返回true；否则返回false</returns>
+    /// <returns>返回一个只读列表，包含所有与指定键和层级关联的UI句柄；如果未找到则返回空列表。</returns>
-    bool HasVisibleInLayer(string uiKey, UiLayer layer);
+    IReadOnlyList<UiHandle> GetAllFromLayer(string uiKey, UiLayer layer);
+
+    /// <summary>
+    ///     判断指定层级是否存在可见UI。
+    /// </summary>
+    /// <param name="handle">UI句柄，用于标识具体的UI实例。</param>
+    /// <param name="layer">要检查的UI层级。</param>
+    /// <returns>如果在指定层级中存在可见的UI，则返回true；否则返回false。</returns>
+    bool HasVisibleInLayer(UiHandle handle, UiLayer layer);
 
     #endregion
 }

GFramework.Game.Abstractions/ui/UiHandle.cs

@@ -0,0 +1,50 @@
+// Copyright (c) 2026 GeWuYou
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using GFramework.Game.Abstractions.enums;
+
+namespace GFramework.Game.Abstractions.ui;
+
+/// <summary>
+/// 表示一个UI句柄，用于唯一标识和管理UI实例。
+/// </summary>
+public readonly struct UiHandle
+{
+    /// <summary>
+    /// 获取UI实例的唯一标识符。
+    /// </summary>
+    public string InstanceId { get; }
+
+    /// <summary>
+    /// 获取UI的键值，通常用于标识UI的类型或名称。
+    /// </summary>
+    public string Key { get; }
+
+    /// <summary>
+    /// 获取UI所在的层级，用于控制UI的显示顺序。
+    /// </summary>
+    public UiLayer Layer { get; }
+
+    /// <summary>
+    /// 初始化一个新的UiHandle实例。
+    /// </summary>
+    /// <param name="key">UI的键值，用于标识UI的类型或名称。</param>
+    /// <param name="instanceId">UI实例的唯一标识符。</param>
+    /// <param name="layer">UI所在的层级，用于控制UI的显示顺序。</param>
+    internal UiHandle(string key, string instanceId, UiLayer layer)
+    {
+        Key = key;
+        InstanceId = instanceId;
+        Layer = layer;
+    }
+}

GFramework.Godot/ui/CanvasItemUiPageBehavior.cs

@@ -1,3 +1,4 @@
+using GFramework.Game.Abstractions.enums;
 using GFramework.Game.Abstractions.ui;
 using GFramework.Godot.extensions;
 using Godot;
@@ -14,6 +15,19 @@ public class CanvasItemUiPageBehavior<T>(T owner, string key) : IUiPageBehavior
 {
     private readonly IUiPage? _page = owner as IUiPage;
 
+    /// <summary>
+    ///     获取当前UI层的类型。
+    ///     返回值表示当前页面所属的UI层级，此处固定返回UiLayer.Page。
+    /// </summary>
+    public UiLayer Layer => UiLayer.Page;
+
+    /// <summary>
+    ///     判断当前Page是否允许重入。
+    ///     返回值为false，表示该Page不支持重入操作。
+    /// </summary>
+    public bool IsReentrant => false;
+
+
     /// <summary>
     ///     获取页面视图对象
     /// </summary>