diff --git a/GFramework.Game.Abstractions/UI/IUiActionHandler.cs b/GFramework.Game.Abstractions/UI/IUiActionHandler.cs new file mode 100644 index 00000000..876b293b --- /dev/null +++ b/GFramework.Game.Abstractions/UI/IUiActionHandler.cs @@ -0,0 +1,17 @@ +namespace GFramework.Game.Abstractions.UI; + +/// +/// 由页面视图实现，用于接收路由仲裁后的 UI 语义动作。 +/// +public interface IUiActionHandler +{ + /// + /// 处理一个 UI 语义动作。 + /// + /// 当前要处理的动作。 + /// + /// 如果页面已经完成处理则返回 ； + /// 返回 时，路由器仍会把声明捕获该动作视为已消费。 + /// + bool TryHandleUiAction(UiInputAction action); +} diff --git a/GFramework.Game.Abstractions/UI/IUiInteractionProfileProvider.cs b/GFramework.Game.Abstractions/UI/IUiInteractionProfileProvider.cs new file mode 100644 index 00000000..138ddc27 --- /dev/null +++ b/GFramework.Game.Abstractions/UI/IUiInteractionProfileProvider.cs @@ -0,0 +1,16 @@ +using GFramework.Game.Abstractions.Enums; + +namespace GFramework.Game.Abstractions.UI; + +/// +/// 由页面视图实现，用于按运行时状态动态提供交互语义配置。 +/// +public interface IUiInteractionProfileProvider +{ + /// + /// 获取页面当前应使用的交互配置。 + /// + /// 页面绑定的默认 UI 层级。 + /// 当前页面的交互配置。 + UiInteractionProfile GetUiInteractionProfile(UiLayer layer); +} diff --git a/GFramework.Game.Abstractions/UI/IUiPageBehavior.cs b/GFramework.Game.Abstractions/UI/IUiPageBehavior.cs index 17a3e686..450a3000 100644 --- a/GFramework.Game.Abstractions/UI/IUiPageBehavior.cs +++ b/GFramework.Game.Abstractions/UI/IUiPageBehavior.cs @@ -66,6 +66,11 @@ public interface IUiPageBehavior : IRoute /// bool BlocksInput { get; } + /// + /// 获取页面当前的输入、阻断与暂停交互配置。 + /// + UiInteractionProfile InteractionProfile { get; } + /// /// 页面进入时调用的方法 /// @@ -96,4 +101,11 @@ public interface IUiPageBehavior : IRoute /// 页面重新显示时调用的方法 /// void OnShow(); -} \ No newline at end of file + + /// + /// 尝试处理一个经过路由器仲裁后的 UI 语义动作。 + /// + /// 当前动作。 + /// 如果页面已经显式处理该动作则返回 。 + bool TryHandleUiAction(UiInputAction action); +} diff --git a/GFramework.Game.Abstractions/UI/IUiRouter.cs b/GFramework.Game.Abstractions/UI/IUiRouter.cs index b6b18873..a84aff7b 100644 --- a/GFramework.Game.Abstractions/UI/IUiRouter.cs +++ b/GFramework.Game.Abstractions/UI/IUiRouter.cs @@ -186,5 +186,40 @@ public interface IUiRouter : ISystem /// 是否隐藏所有匹配的UI实例，默认为false。 void HideByKey(string uiKey, UiLayer layer, bool destroy = false, bool hideAll = false); + /// + /// 查询当前对指定 UI 语义动作拥有最高优先级捕获权的页面。 + /// + /// 要查询的动作。 + /// 动作所有者；如果当前没有页面声明捕获该动作则返回 。 + IUiPageBehavior? GetUiActionOwner(UiInputAction action); + + /// + /// 尝试把语义动作分发给当前拥有该动作捕获权的页面。 + /// + /// 当前动作。 + /// 如果该动作已被某个页面捕获并完成分发，则返回 。 + bool TryDispatchUiAction(UiInputAction action); + + /// + /// 尝试把语义动作分发给当前拥有该动作捕获权的页面。 + /// + /// 当前动作。 + /// 如果该动作已被某个页面捕获并完成分发，则返回 。 + [Obsolete( + "Use TryDispatchUiAction(UiInputAction action) to emphasize dispatch semantics instead of handler success.")] + bool TryHandleUiAction(UiInputAction action); + + /// + /// 判断当前可见 UI 是否阻断 World 指针输入。 + /// + /// 如果 World 指针输入应被阻断则返回 。 + bool BlocksWorldPointerInput(); + + /// + /// 判断当前可见 UI 是否阻断 World 语义动作输入。 + /// + /// 如果 World 动作输入应被阻断则返回 。 + bool BlocksWorldActionInput(); + #endregion -} \ No newline at end of file +} diff --git a/GFramework.Game.Abstractions/UI/UiInputAction.cs b/GFramework.Game.Abstractions/UI/UiInputAction.cs new file mode 100644 index 00000000..c0aee070 --- /dev/null +++ b/GFramework.Game.Abstractions/UI/UiInputAction.cs @@ -0,0 +1,23 @@ +namespace GFramework.Game.Abstractions.UI; + +/// +/// 定义框架级 UI 语义动作。 +/// 这些动作由输入层映射后交给 UI 路由统一仲裁，避免页面直接依赖具体按键或设备事件。 +/// +public enum UiInputAction +{ + /// + /// 未指定动作。 + /// + None = 0, + + /// + /// 取消、返回或关闭当前 UI。 + /// + Cancel = 1, + + /// + /// 确认当前 UI 操作。 + /// + Confirm = 2 +} diff --git a/GFramework.Game.Abstractions/UI/UiInputActionMask.cs b/GFramework.Game.Abstractions/UI/UiInputActionMask.cs new file mode 100644 index 00000000..09c7b54e --- /dev/null +++ b/GFramework.Game.Abstractions/UI/UiInputActionMask.cs @@ -0,0 +1,23 @@ +namespace GFramework.Game.Abstractions.UI; + +/// +/// 以位标记形式声明 UI 页面要捕获的语义动作集合。 +/// +[Flags] +public enum UiInputActionMask +{ + /// + /// 不捕获任何动作。 + /// + None = 0, + + /// + /// 捕获取消动作。 + /// + Cancel = 1 << 0, + + /// + /// 捕获确认动作。 + /// + Confirm = 1 << 1 +} diff --git a/GFramework.Game.Abstractions/UI/UiInteractionProfile.cs b/GFramework.Game.Abstractions/UI/UiInteractionProfile.cs new file mode 100644 index 00000000..6f2cecb3 --- /dev/null +++ b/GFramework.Game.Abstractions/UI/UiInteractionProfile.cs @@ -0,0 +1,48 @@ +using GFramework.Core.Abstractions.Pause; + +namespace GFramework.Game.Abstractions.UI; + +/// +/// 描述一个 UI 页面在输入、World 阻断与暂停上的交互契约数据。 +/// +/// +/// 该类型仅承载抽象层需要共享的页面交互配置，不包含默认值工厂或动作判定等运行时策略。 +/// 运行时层可在不反向依赖 Abstractions 的前提下，通过专门的 helper 为该 DTO 提供默认值和语义判定。 +/// +public sealed class UiInteractionProfile +{ + /// + /// 声明当前页面要捕获的语义动作集合。 + /// + public UiInputActionMask CapturedActions { get; init; } = UiInputActionMask.None; + + /// + /// 指示当前页面是否阻断 World 指针输入，例如地图点击或相机拖拽。 + /// + public bool BlocksWorldPointerInput { get; init; } + + /// + /// 指示当前页面是否阻断 World 语义动作输入，例如 gameplay 快捷键。 + /// + public bool BlocksWorldActionInput { get; init; } + + /// + /// 指示当前页面的可见性是否应驱动暂停栈。 + /// + public UiPauseMode PauseMode { get; init; } = UiPauseMode.None; + + /// + /// 当 生效时使用的暂停组。 + /// + public PauseGroup PauseGroup { get; init; } = PauseGroup.Global; + + /// + /// 当场景树暂停时，该页面是否仍需继续处理输入与动画。 + /// + public bool ContinueProcessingWhenPaused { get; init; } + + /// + /// 页面向暂停栈登记时使用的原因文本。 + /// + public string PauseReason { get; init; } = string.Empty; +} diff --git a/GFramework.Game.Abstractions/UI/UiPauseMode.cs b/GFramework.Game.Abstractions/UI/UiPauseMode.cs new file mode 100644 index 00000000..5462c171 --- /dev/null +++ b/GFramework.Game.Abstractions/UI/UiPauseMode.cs @@ -0,0 +1,17 @@ +namespace GFramework.Game.Abstractions.UI; + +/// +/// 定义页面显示时与暂停系统的协作模式。 +/// +public enum UiPauseMode +{ + /// + /// 页面显示不会触发暂停请求。 + /// + None = 0, + + /// + /// 页面在可见期间持有一个暂停请求，隐藏或销毁时释放。 + /// + WhileVisible = 1 +} diff --git a/GFramework.Game.Tests/GlobalUsings.cs b/GFramework.Game.Tests/GlobalUsings.cs index 6b9d4d62..1ea2af31 100644 --- a/GFramework.Game.Tests/GlobalUsings.cs +++ b/GFramework.Game.Tests/GlobalUsings.cs @@ -16,4 +16,8 @@ global using Moq; global using System; global using System.Collections.Generic; global using System.Linq; -global using System.Threading.Tasks; \ No newline at end of file +global using System.Threading.Tasks; +global using System.Reflection; +global using GFramework.Game.Abstractions.Enums; +global using GFramework.Game.Abstractions.UI; +global using GFramework.Game.UI; diff --git a/GFramework.Game.Tests/UI/UiRouterInteractionTests.cs b/GFramework.Game.Tests/UI/UiRouterInteractionTests.cs new file mode 100644 index 00000000..0920631d --- /dev/null +++ b/GFramework.Game.Tests/UI/UiRouterInteractionTests.cs @@ -0,0 +1,359 @@ +// 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. + +namespace GFramework.Game.Tests.UI; + +/// +/// 验证 UI 路由输入语义、层级排序与显示恢复生命周期的回归测试。 +/// +[TestFixture] +public class UiRouterInteractionTests +{ + /// + /// 验证模态层和顶层共享同一套阻塞型默认交互配置。 + /// + [Test] + public void CreateDefault_ForModalAndTopmost_ReturnsBlockingCancelProfile() + { + // Arrange + var modal = UiInteractionProfiles.CreateDefault(UiLayer.Modal); + var topmost = UiInteractionProfiles.CreateDefault(UiLayer.Topmost); + + // Assert + Assert.Multiple(() => + { + Assert.That(modal.CapturedActions, Is.EqualTo(UiInputActionMask.Cancel)); + Assert.That(modal.BlocksWorldPointerInput, Is.True); + Assert.That(modal.BlocksWorldActionInput, Is.True); + Assert.That(topmost.CapturedActions, Is.EqualTo(UiInputActionMask.Cancel)); + Assert.That(topmost.BlocksWorldPointerInput, Is.True); + Assert.That(topmost.BlocksWorldActionInput, Is.True); + }); + } + + /// + /// 验证只要动作被页面捕获，路由分发就会返回成功，即使页面没有显式消费该动作。 + /// + [Test] + public void TryDispatchUiAction_WhenCapturedButUnhandled_ReturnsTrue() + { + // Arrange + var router = CreateRouter(); + var page = new TestUiPage("capturing-page", UiLayer.Topmost) + { + InteractionProfile = new UiInteractionProfile + { + CapturedActions = UiInputActionMask.Cancel + }, + TryHandleUiActionResult = false + }; + + router.Show(page, UiLayer.Topmost); + + // Act + var dispatched = router.TryDispatchUiAction(UiInputAction.Cancel); + + // Assert + Assert.Multiple(() => + { + Assert.That(dispatched, Is.True); + Assert.That(page.TryHandleUiActionCallCount, Is.EqualTo(1)); + }); + } + + /// + /// 验证层级页面排序使用实例自增序号，而不是依赖固定宽度的字符串顺序。 + /// + [Test] + public void GetUiActionOwner_WhenInstanceIdWidthOverflows_UsesNumericOrder() + { + // Arrange + var router = CreateRouter(); + SetInstanceCounter(router, 999998); + + var olderPage = new TestUiPage("older", UiLayer.Topmost) + { + InteractionProfile = new UiInteractionProfile + { + CapturedActions = UiInputActionMask.Cancel + } + }; + var newerPage = new TestUiPage("newer", UiLayer.Topmost) + { + InteractionProfile = new UiInteractionProfile + { + CapturedActions = UiInputActionMask.Cancel + } + }; + + router.Show(olderPage, UiLayer.Topmost); + router.Show(newerPage, UiLayer.Topmost); + + // Act + var owner = router.GetUiActionOwner(UiInputAction.Cancel); + + // Assert + Assert.That(owner, Is.SameAs(newerPage)); + } + + /// + /// 验证恢复挂起的层级页面时，不会再对依赖 OnShow 触发恢复的页面重复调用 OnResume。 + /// + [Test] + public void Resume_WhenPageResumesDuringShow_DoesNotCallResumeTwice() + { + // Arrange + var router = CreateRouter(); + var page = new TestUiPage("resumable-layer-page", UiLayer.Overlay) + { + ResumeFromShow = true + }; + + var handle = router.Show(page, UiLayer.Overlay); + router.Hide(handle, UiLayer.Overlay); + var resumeCountBeforeResume = page.OnResumeCallCount; + + // Act + router.Resume(handle, UiLayer.Overlay); + + // Assert + Assert.That(page.OnResumeCallCount, Is.EqualTo(resumeCountBeforeResume + 1)); + } + + /// + /// 验证弹出栈顶页面后，恢复下层页面时不会重复触发恢复逻辑。 + /// + /// 表示异步测试执行过程的任务。 + [Test] + public async Task PopAsync_WhenPageResumesDuringShow_DoesNotCallResumeTwice() + { + // Arrange + var router = CreateRouter(); + var underlyingPage = new TestUiPage("underlying-page", UiLayer.Page) + { + ResumeFromShow = true + }; + var topPage = new TestUiPage("top-page", UiLayer.Page); + + await router.PushAsync(underlyingPage); + await router.PushAsync(topPage); + var resumeCountBeforePop = underlyingPage.OnResumeCallCount; + + // Act + await router.PopAsync(UiPopPolicy.Destroy); + + // Assert + Assert.That(underlyingPage.OnResumeCallCount, Is.EqualTo(resumeCountBeforePop + 1)); + } + + /// + /// 创建带有测试根节点的 UI 路由器。 + /// + /// 已绑定测试根节点的路由器实例。 + private static TestUiRouter CreateRouter() + { + var router = new TestUiRouter(); + router.BindRoot(new TestUiRoot()); + router.InitializeForTests(); + return router; + } + + /// + /// 把实例计数器调整到指定值，以便覆盖实例标识符宽度溢出的排序回归。 + /// + /// 目标路由器。 + /// 要写入的计数器值。 + private static void SetInstanceCounter(UiRouterBase router, int value) + { + var field = typeof(UiRouterBase).GetField("_instanceCounter", BindingFlags.Instance | BindingFlags.NonPublic); + Assert.That(field, Is.Not.Null, "UiRouterBase._instanceCounter 字段未找到，可能发生了内部重构。"); + Assert.That(field!.FieldType, Is.EqualTo(typeof(int)), "_instanceCounter 字段类型已变化，请同步调整测试。"); + + field.SetValue(router, value); + } + + /// + /// 测试用 UI 路由器实现。 + /// + private sealed class TestUiRouter : UiRouterBase + { + /// + /// 以测试专用的最小依赖集合执行路由器初始化。 + /// + public void InitializeForTests() + { + Initialize(); + } + + /// + /// 以测试最小依赖完成初始化，避免把测试绑定到完整的架构 Utility 配置上。 + /// + protected override void OnInit() + { + RegisterHandlers(); + } + + /// + /// 注册处理器。 + /// + protected override void RegisterHandlers() + { + } + } + + /// + /// 测试用 UI 根节点，占位记录添加/移除操作即可。 + /// + private sealed class TestUiRoot : IUiRoot + { + /// + /// 记录当前挂载的页面集合。 + /// + private readonly List _children = new(); + + /// + public void AddUiPage(IUiPageBehavior child) + { + _children.Add(child); + } + + /// + public void AddUiPage(IUiPageBehavior child, UiLayer layer, int orderInLayer = 0) + { + _children.Add(child); + } + + /// + public void RemoveUiPage(IUiPageBehavior child) + { + _children.Remove(child); + } + } + + /// + /// 可配置的测试页面，用于模拟路由器在不同交互语义下的可观察行为。 + /// + private sealed class TestUiPage : IUiPageBehavior + { + /// + /// 初始化测试页面实例。 + /// + /// 页面键。 + /// 页面层级。 + public TestUiPage(string key, UiLayer layer) + { + Key = key; + Layer = layer; + InteractionProfile = UiInteractionProfiles.Default; + IsAlive = true; + } + + /// + /// 获取或设置一个值，指示 是否要模拟 `CanvasItemUiPageBehaviorBase` 那样触发恢复逻辑。 + /// + public bool ResumeFromShow { get; init; } + + /// + /// 获取或设置页面处理动作时返回的结果。 + /// + public bool TryHandleUiActionResult { get; init; } = true; + + /// + /// 记录恢复回调触发次数。 + /// + public int OnResumeCallCount { get; private set; } + + /// + /// 记录动作处理方法调用次数。 + /// + public int TryHandleUiActionCallCount { get; private set; } + + /// + public UiHandle? Handle { get; set; } + + /// + public UiLayer Layer { get; } + + /// + public bool IsReentrant { get; init; } = true; + + /// + public object View => this; + + /// + public bool IsAlive { get; private set; } + + /// + public bool IsVisible { get; private set; } + + /// + public bool IsModal => Layer == UiLayer.Modal; + + /// + public bool BlocksInput { get; init; } + + /// + public UiInteractionProfile InteractionProfile { get; init; } + + /// + public string Key { get; } + + /// + public void OnEnter(IUiPageEnterParam? param) + { + } + + /// + public void OnExit() + { + IsAlive = false; + IsVisible = false; + } + + /// + public void OnPause() + { + } + + /// + public void OnResume() + { + OnResumeCallCount++; + } + + /// + public void OnHide() + { + IsVisible = false; + } + + /// + public void OnShow() + { + IsVisible = true; + + // The Godot page behavior resumes from OnShow(), so the router must not call OnResume() again on top. + if (ResumeFromShow) + { + OnResume(); + } + } + + /// + public bool TryHandleUiAction(UiInputAction action) + { + TryHandleUiActionCallCount++; + return TryHandleUiActionResult; + } + } +} diff --git a/GFramework.Game/GlobalUsings.cs b/GFramework.Game/GlobalUsings.cs index b91413e9..687ce844 100644 --- a/GFramework.Game/GlobalUsings.cs +++ b/GFramework.Game/GlobalUsings.cs @@ -20,4 +20,5 @@ global using System.Threading.Tasks; global using System.Globalization; global using System.IO; global using System.Text.Json; -global using YamlDotNet.RepresentationModel; \ No newline at end of file +global using YamlDotNet.RepresentationModel; +global using GFramework.Core.Abstractions.Logging; diff --git a/GFramework.Game/UI/UiInteractionProfiles.cs b/GFramework.Game/UI/UiInteractionProfiles.cs new file mode 100644 index 00000000..224de6b6 --- /dev/null +++ b/GFramework.Game/UI/UiInteractionProfiles.cs @@ -0,0 +1,59 @@ +using GFramework.Game.Abstractions.Enums; +using GFramework.Game.Abstractions.UI; + +namespace GFramework.Game.UI; + +/// +/// 为 提供运行时默认值与语义判定。 +/// +/// +/// 该 helper 保留在运行时程序集内，避免把默认策略和输入判定逻辑放回 Abstractions。 +/// UI 页面和路由器都应通过这里共享同一套默认语义，避免层级默认值漂移。 +/// +public static class UiInteractionProfiles +{ + /// + /// 获取不捕获动作、也不阻断 World 输入的默认配置。 + /// + public static UiInteractionProfile Default { get; } = new(); + + /// + /// 获取会捕获取消动作并阻断 World 输入的阻塞型默认配置。 + /// + public static UiInteractionProfile BlockingCancel { get; } = new() + { + CapturedActions = UiInputActionMask.Cancel, + BlocksWorldPointerInput = true, + BlocksWorldActionInput = true + }; + + /// + /// 为指定层级生成默认交互配置。 + /// + /// UI 层级。 + /// 该层级的默认交互语义。 + public static UiInteractionProfile CreateDefault(UiLayer layer) + { + return layer switch + { + UiLayer.Modal or UiLayer.Topmost => BlockingCancel, + _ => Default + }; + } + + /// + /// 判断指定配置是否捕获了目标 UI 语义动作。 + /// + /// 目标配置。 + /// 要查询的动作。 + /// 如果配置声明捕获了该动作则返回 。 + public static bool Captures(UiInteractionProfile profile, UiInputAction action) + { + return action switch + { + UiInputAction.Cancel => (profile.CapturedActions & UiInputActionMask.Cancel) != 0, + UiInputAction.Confirm => (profile.CapturedActions & UiInputActionMask.Confirm) != 0, + _ => false + }; + } +} diff --git a/GFramework.Game/UI/UiRouterBase.cs b/GFramework.Game/UI/UiRouterBase.cs index f105cbb6..ede1b51b 100644 --- a/GFramework.Game/UI/UiRouterBase.cs +++ b/GFramework.Game/UI/UiRouterBase.cs @@ -1,6 +1,5 @@ -using GFramework.Core.Abstractions.Logging; +using GFramework.Core.Abstractions.Pause; using GFramework.Core.Extensions; -using GFramework.Core.Logging; using GFramework.Game.Abstractions.Enums; using GFramework.Game.Abstractions.UI; using GFramework.Game.Routing; @@ -21,6 +20,11 @@ public abstract class UiRouterBase : RouterBase private readonly Dictionary> _layers = new(); + /// + /// 记录当前由页面可见性驱动持有的暂停令牌。 + /// + private readonly Dictionary _pauseTokens = new(); + /// /// UI切换处理器管道，用于执行UI过渡动画和逻辑 /// @@ -36,6 +40,11 @@ public abstract class UiRouterBase : RouterBase private int _instanceCounter; + /// + /// 可选暂停栈管理器。 + /// + private IPauseStackManager? _pauseStackManager; + /// /// UI根节点引用，用于添加和移除UI页面 /// @@ -324,6 +333,7 @@ public abstract class UiRouterBase : RouterBase + /// 获取当前拥有指定 UI 语义动作捕获权的页面。 + /// + /// 要查询的动作。 + /// 动作所有者；若没有页面声明捕获该动作则返回 。 + public IUiPageBehavior? GetUiActionOwner(UiInputAction action) + { + return EnumerateVisiblePagesByPriority() + .FirstOrDefault(page => UiInteractionProfiles.Captures(page.InteractionProfile, action)); + } + + /// + /// 尝试将语义动作分发给当前拥有捕获权的页面。 + /// + /// 当前动作。 + /// 如果已有页面捕获该动作则返回 。 + public bool TryDispatchUiAction(UiInputAction action) + { + var owner = GetUiActionOwner(action); + if (owner is null) + return false; + + var handled = owner.TryHandleUiAction(action); + if (!handled) + Log.Debug("UI action captured without explicit handler: key={0}, action={1}", owner.Key, action); + + return true; + } + + /// + /// 尝试将语义动作分发给当前拥有捕获权的页面。 + /// + /// 当前动作。 + /// 如果已有页面捕获该动作则返回 。 + [Obsolete( + "Use TryDispatchUiAction(UiInputAction action) to emphasize dispatch semantics instead of handler success.")] + public bool TryHandleUiAction(UiInputAction action) + { + return TryDispatchUiAction(action); + } + + /// + /// 判断当前可见 UI 是否阻断 World 指针输入。 + /// + /// 如果 World 指针输入应被阻断则返回 。 + public bool BlocksWorldPointerInput() + { + return EnumerateVisiblePagesByPriority() + .Any(page => page.InteractionProfile.BlocksWorldPointerInput); + } + + /// + /// 判断当前可见 UI 是否阻断 World 语义动作输入。 + /// + /// 如果 World 语义动作输入应被阻断则返回 。 + public bool BlocksWorldActionInput() + { + return EnumerateVisiblePagesByPriority() + .Any(page => page.InteractionProfile.BlocksWorldActionInput); + } + #endregion #region Initialization @@ -458,6 +530,7 @@ public abstract class UiRouterBase : RouterBase()!; + TryBindPauseStackManager(); // 输出调试日志，记录UI路由器基类已初始化及使用的工厂类型 Log.Debug("UiRouterBase initialized. Factory={0}", _factory.GetType().Name); @@ -472,6 +545,24 @@ public abstract class UiRouterBase : RouterBase protected override abstract void RegisterHandlers(); + /// + /// 路由销毁时释放所有由页面持有的暂停请求。 + /// + protected override void OnDestroy() + { + base.OnDestroy(); + + if (_pauseStackManager is null) + return; + + foreach (var token in _pauseTokens.Values.ToArray()) + { + _pauseStackManager.Pop(token); + } + + _pauseTokens.Clear(); + } + #endregion #region Internal Helpers @@ -525,6 +616,7 @@ public abstract class UiRouterBase : RouterBase @@ -646,11 +740,13 @@ public abstract class UiRouterBase : RouterBase 0) { var next = Stack.Peek(); - next.OnResume(); next.OnShow(); + SyncPauseRequest(next, isVisible: true); } } @@ -665,5 +761,117 @@ public abstract class UiRouterBase : RouterBase + /// 尝试绑定暂停栈管理器。 + /// + private void TryBindPauseStackManager() + { + try + { + _pauseStackManager = this.GetUtility(); + } + catch (InvalidOperationException) + { + _pauseStackManager = null; + Log.Debug("PauseStackManager not available. Pause integration is disabled for the UI router."); + } + } + + /// + /// 根据页面可见性同步暂停请求。 + /// + /// 页面行为。 + /// 页面是否应视为可见。 + private void SyncPauseRequest(IUiPageBehavior page, bool isVisible) + { + if (_pauseStackManager is null) + return; + + var profile = page.InteractionProfile; + if (!isVisible || profile.PauseMode == UiPauseMode.None) + { + ReleasePauseRequest(page); + return; + } + + if (_pauseTokens.ContainsKey(page)) + return; + + var reason = string.IsNullOrWhiteSpace(profile.PauseReason) + ? $"UI:{page.Key}" + : profile.PauseReason; + _pauseTokens[page] = _pauseStackManager.Push(reason, profile.PauseGroup); + } + + /// + /// 释放页面此前登记的暂停请求。 + /// + /// 目标页面。 + private void ReleasePauseRequest(IUiPageBehavior page) + { + if (_pauseStackManager is null) + return; + + if (!_pauseTokens.Remove(page, out var token)) + return; + + _pauseStackManager.Pop(token); + } + + /// + /// 按输入优先级枚举当前所有可见页面。 + /// + /// 可见页面序列。 + private IEnumerable EnumerateVisiblePagesByPriority() + { + foreach (var page in EnumerateVisibleLayerPages(UiLayer.Topmost)) + yield return page; + + foreach (var page in EnumerateVisibleLayerPages(UiLayer.Modal)) + yield return page; + + foreach (var page in EnumerateVisibleLayerPages(UiLayer.Overlay)) + yield return page; + + foreach (var page in Stack.Where(static page => page.IsAlive && page.IsVisible)) + yield return page; + + foreach (var page in EnumerateVisibleLayerPages(UiLayer.Toast)) + yield return page; + } + + /// + /// 枚举指定层级中的可见页面，层内按最近显示优先。 + /// + /// 目标层级。 + /// 该层级中的可见页面。 + private IEnumerable EnumerateVisibleLayerPages(UiLayer layer) + { + if (!_layers.TryGetValue(layer, out var layerDict)) + yield break; + + foreach (var page in layerDict + // Use the numeric sequence encoded in the instance id so ordering stays correct after width overflow. + .OrderByDescending(static pair => ExtractInstanceSequence(pair.Key)) + .Select(static pair => pair.Value) + .Where(static page => page.IsAlive && page.IsVisible)) + { + yield return page; + } + } + + /// + /// 从实例标识符中提取自增序号，供层内最近显示优先排序使用。 + /// + /// 实例标识符，预期格式为 ui_000001。 + /// 提取到的自增序号；若格式异常则返回 ，使异常值排在最后。 + private static int ExtractInstanceSequence(string instanceId) + { + return instanceId.Length > 3 && + int.TryParse(instanceId.AsSpan(3), NumberStyles.None, CultureInfo.InvariantCulture, out var sequence) + ? sequence + : int.MinValue; + } + #endregion -} \ No newline at end of file +} diff --git a/GFramework.Godot/GlobalUsings.cs b/GFramework.Godot/GlobalUsings.cs index 41d45db7..818d6b41 100644 --- a/GFramework.Godot/GlobalUsings.cs +++ b/GFramework.Godot/GlobalUsings.cs @@ -16,4 +16,5 @@ global using System.Collections.Generic; global using System.Linq; global using System.Threading; global using System.Threading.Tasks; -global using Godot; \ No newline at end of file +global using Godot; +global using GFramework.Godot.Extensions; diff --git a/GFramework.Godot/UI/CanvasItemUiPageBehaviorBase.cs b/GFramework.Godot/UI/CanvasItemUiPageBehaviorBase.cs index 59dc320b..565289e3 100644 --- a/GFramework.Godot/UI/CanvasItemUiPageBehaviorBase.cs +++ b/GFramework.Godot/UI/CanvasItemUiPageBehaviorBase.cs @@ -13,8 +13,7 @@ using GFramework.Game.Abstractions.Enums; using GFramework.Game.Abstractions.UI; -using GFramework.Godot.Extensions; -using Godot; +using GFramework.Game.UI; namespace GFramework.Godot.UI; @@ -36,6 +35,16 @@ public abstract class CanvasItemUiPageBehaviorBase : IUiPageBehavior /// private readonly IUiPage? _page; + /// + /// 视图可选提供的交互配置提供者。 + /// + private readonly IUiInteractionProfileProvider? _profileProvider; + + /// + /// 视图可选提供的 UI 语义动作处理器。 + /// + private readonly IUiActionHandler? _uiActionHandler; + /// /// 视图节点的所有者实例。 /// @@ -51,6 +60,8 @@ public abstract class CanvasItemUiPageBehaviorBase : IUiPageBehavior Owner = owner; _key = key; _page = owner as IUiPage; + _profileProvider = owner as IUiInteractionProfileProvider; + _uiActionHandler = owner as IUiActionHandler; } #region 抽象属性 - 子类必须实现 @@ -115,6 +126,13 @@ public abstract class CanvasItemUiPageBehaviorBase : IUiPageBehavior /// public bool IsVisible => Owner.Visible; + /// + /// 获取页面当前的交互配置。 + /// 若页面未提供自定义配置，则回退到层级默认值。 + /// + public UiInteractionProfile InteractionProfile => _profileProvider?.GetUiInteractionProfile(Layer) + ?? UiInteractionProfiles.CreateDefault(Layer); + #endregion #region 生命周期管理 @@ -153,6 +171,8 @@ public abstract class CanvasItemUiPageBehaviorBase : IUiPageBehavior Owner.SetProcess(false); Owner.SetPhysicsProcess(false); Owner.SetProcessInput(false); + Owner.SetProcessUnhandledInput(false); + Owner.SetProcessUnhandledKeyInput(false); } /// @@ -166,10 +186,14 @@ public abstract class CanvasItemUiPageBehaviorBase : IUiPageBehavior _page?.OnResume(); + ApplyPauseAwareProcessingMode(); + // 恢复处理 Owner.SetProcess(true); Owner.SetPhysicsProcess(true); Owner.SetProcessInput(true); + Owner.SetProcessUnhandledInput(true); + Owner.SetProcessUnhandledKeyInput(true); } /// @@ -193,5 +217,25 @@ public abstract class CanvasItemUiPageBehaviorBase : IUiPageBehavior OnResume(); } + /// + /// 尝试处理一个路由仲裁后的 UI 语义动作。 + /// + /// 当前动作。 + /// 如果视图显式处理了该动作则返回 。 + public virtual bool TryHandleUiAction(UiInputAction action) + { + return _uiActionHandler?.TryHandleUiAction(action) ?? false; + } + + /// + /// 根据交互配置调整节点在暂停态下的处理模式。 + /// + private void ApplyPauseAwareProcessingMode() + { + Owner.ProcessMode = InteractionProfile.ContinueProcessingWhenPaused + ? Node.ProcessModeEnum.Always + : Node.ProcessModeEnum.Pausable; + } + #endregion -} \ No newline at end of file +}