refactor(ui): 重构UI层级管理系统

- 移除 System.Collections.Generic 和 System 的 using 语句
- 添加 GFramework.Game.Abstractions.enums 的 using 语句
- 添加静态只读字典 LayerZOrderMap 来管理 UI 层级 Z 轴顺序
- 修改 AddUiPage 方法参数，使用 UiLayer 枚举替代 zOrder 参数
- 使用 TryAdd 方法替换 ContainsKey 判断逻辑
- 使用 Remove 方法的重载版本来简化页面移除逻辑
- 删除 RefreshLayerOrder 方法
- 添加 GetBaseZOrder 辅助方法来获取基础 Z 轴顺序
- 更新 UiLayer 枚举定义，移除显式的数值赋值
- 更新 IUiRoot 接口中的 AddUiPage 方法签名
- 删除 IUiRoot 接口中 RefreshLayerOrder 方法
- 更新 UiRouterBase 中调用 AddUiPage 方法的方式，传递 UiLayer 参数

GFramework.Game.Abstractions/enums/UiLayer.cs

@@ -9,25 +9,25 @@ public enum UiLayer
     /// <summary>
     /// 页面层，使用栈管理UI的切换
     /// </summary>
-    Page = 0,
+    Page,
 
     /// <summary>
     /// 浮层，用于覆盖层、对话框等
     /// </summary>
-    Overlay = 10,
+    Overlay,
 
     /// <summary>
     /// 模态层，会阻挡下层交互，带有遮罩效果
     /// </summary>
-    Modal = 20,
+    Modal,
 
     /// <summary>
     /// 提示层，用于轻量提示如toast消息、loading指示器等
     /// </summary>
-    Toast = 30,
+    Toast,
 
     /// <summary>
     /// 顶层，用于系统级弹窗、全屏加载等
     /// </summary>
-    Topmost = 40
+    Topmost
 }

GFramework.Game.Abstractions/ui/IUiRoot.cs

@@ -1,4 +1,5 @@
 using System.Collections.Generic;
+using GFramework.Game.Abstractions.enums;
 
 namespace GFramework.Game.Abstractions.ui;
 
@@ -17,8 +18,9 @@ public interface IUiRoot
     /// 向UI根节点添加子页面到指定层级
     /// </summary>
     /// <param name="child">要添加的UI页面子节点</param>
-    /// <param name="zOrder">Z-order值，用于控制UI显示层级</param>
-    void AddUiPage(IUiPageBehavior child, int zOrder = 0);
+    /// <param name="layer">层级</param>
+    /// <param name="orderInLayer">层级内排序</param>
+    void AddUiPage(IUiPageBehavior child, UiLayer layer, int orderInLayer = 0);
 
     /// <summary>
     /// 从UI根节点移除子页面
@@ -38,9 +40,4 @@ public interface IUiRoot
     /// </summary>
     /// <returns>所有显示的页面列表</returns>
     IReadOnlyList<IUiPageBehavior> GetVisiblePages();
-
-    /// <summary>
-    /// 强制刷新UI层级排序
-    /// </summary>
-    void RefreshLayerOrder();
 }

GFramework.Game/ui/UiRouterBase.cs

@@ -504,7 +504,7 @@ public abstract class UiRouterBase : AbstractSystem, IUiRouter
         layerDict[uiKey] = page;
 
         // 添加到UiRoot，传入层级Z-order
-        _uiRoot.AddUiPage(page, (int)layer);
+        _uiRoot.AddUiPage(page, layer);
 
         page.OnEnter(param);
         page.OnShow();
@@ -526,7 +526,7 @@ public abstract class UiRouterBase : AbstractSystem, IUiRouter
             _layers[layer] = new Dictionary<string, IUiPageBehavior>();
 
         _layers[layer][uiKey] = page;
-        _uiRoot.AddUiPage(page, (int)layer);
+        _uiRoot.AddUiPage(page, layer);
         page.OnShow();
 
         Log.Debug("Show existing UI instance in layer: {0}, layer={1}", uiKey, layer);

GFramework.Godot/ui/GodotUiRoot.cs

@@ -1,5 +1,4 @@
-using System.Collections.Generic;
-using System;
+using GFramework.Game.Abstractions.enums;
 using GFramework.Game.Abstractions.ui;
 using Godot;
 
@@ -20,6 +19,15 @@ public partial class GodotUiRoot : Node, IUiRoot
     /// UI页面的追踪字典，记录每个页面的节点
     /// </summary>
     private readonly Dictionary<IUiPageBehavior, Node> _pageNodes = new();
+    private static readonly IReadOnlyDictionary<UiLayer, int> LayerZOrderMap =
+        new Dictionary<UiLayer, int>
+        {
+            { UiLayer.Page,     0 },
+            { UiLayer.Overlay,  100 },
+            { UiLayer.Modal,    200 },
+            { UiLayer.Toast,    300 },
+            { UiLayer.Topmost,  400 },
+        };
 
     public override void _Ready()
     {
@@ -44,11 +52,9 @@ public partial class GodotUiRoot : Node, IUiRoot
         if (node == null)
             throw new InvalidOperationException($"Page node is null: {child.Key}");
 
-        if (_pageNodes.ContainsKey(child))
+        if (!_pageNodes.TryAdd(child, node))
             return;
 
-        _pageNodes[child] = node;
-
         if (node.GetParent() != _uiContainer)
         {
             _uiContainer.AddChild(node);
@@ -58,22 +64,26 @@ public partial class GodotUiRoot : Node, IUiRoot
     /// <summary>
     /// 向UI根节点添加子页面到指定层级
     /// </summary>
-    public void AddUiPage(IUiPageBehavior child, int zOrder = 0)
+    public void AddUiPage(
+        IUiPageBehavior child,
+        UiLayer layer,
+        int orderInLayer = 0)
     {
         AddUiPage(child);
-        SetZOrder(child, zOrder);
+
+        var z = GetBaseZOrder(layer) + orderInLayer;
+        SetZOrder(child, z);
     }
 
+
     /// <summary>
     /// 从UI根节点移除子页面
     /// </summary>
     public void RemoveUiPage(IUiPageBehavior child)
     {
-        if (!_pageNodes.TryGetValue(child, out var node))
+        if (!_pageNodes.Remove(child, out var node))
             return;
 
-        _pageNodes.Remove(child);
-
         if (_uiContainer != null && node.GetParent() == _uiContainer)
         {
             _uiContainer.RemoveChild(node);
@@ -101,17 +111,8 @@ public partial class GodotUiRoot : Node, IUiRoot
     {
         return _pageNodes.Keys.ToList().AsReadOnly();
     }
+    
 
-    /// <summary>
-    /// 强制刷新UI层级排序
-    /// </summary>
-    public void RefreshLayerOrder()
-    {
-        if (_uiContainer == null)
-            return;
-
-        _uiContainer.MoveChild(_uiContainer.GetChild(0), 0);
-    }
 
     /// <summary>
     /// 从页面行为获取对应的节点
@@ -120,4 +121,8 @@ public partial class GodotUiRoot : Node, IUiRoot
     {
         return page.View as Node;
     }
+    private static int GetBaseZOrder(UiLayer layer)
+    {
+        return !LayerZOrderMap.TryGetValue(layer, out var z) ? throw new ArgumentOutOfRangeException(nameof(layer), layer, null) : z;
+    }
 }