ue5-ui-umg-slate

快速入门

• 判断功能属于 UMG、Slate，还是混合桥接。
• 定义数据源组件／子系统和 UI 绑定点。
• 输出控件树意图和运行时绑定顺序。

API 锚点（UE5.6-UE5.8）

• UMG 生命周期和视口锚点：
  • UUserWidget::NativeConstruct()、UUserWidget::NativeDestruct()
  • UUserWidget::AddToViewport(...)
  • UWidget::RemoveFromParent()
  • UWidget::SetVisibility(...)
  • UWidget::SetKeyboardFocus()
• UMG 输入模式锚点：
  • UWidgetBlueprintLibrary::SetInputMode_UIOnlyEx(...)
  • UWidgetBlueprintLibrary::SetInputMode_GameAndUIEx(...)
  • UWidgetBlueprintLibrary::SetInputMode_GameOnly(...)
• UMG／Slate 桥接锚点：
  • UWidget::TakeWidget() 用于 Slate 桥接交接
  • SCompoundWidget、SLATE_BEGIN_ARGS(...)
  • FSlateApplication::SetKeyboardFocus(...)、SetUserFocus(...)
• 视口几何锚点：
  • UGameViewportClient::GetViewportSize(...)

UI 阶段契约

• 每项 UI 任务都必须定义：
  • UI 层所有权（仅 UMG、仅 Slate 或混合桥接）
  • 数据源和更新触发方式（拉取、推送、事件或混合）
  • 焦点和输入所有权的转换
  • 工具提示／弹出窗口在视口内的安全放置行为
  • 取消绑定和移除控件时的拆除／清理路径
• 如果缺少任何一项，UI 实现就不完整。

工作流

1) UI 架构决策

• 标准游戏 HUD／菜单工作选择 UMG。
• 对 UMG 无法清晰表达的自定义渲染／输入行为，选择 Slate。
• 当 UWidget 宿主需要嵌入自定义 Slate 内容时，选择混合模式。

2) 构建和生命周期

• 在构造／初始化路径中初始化控件绑定。
• 仅注册一次事件监听器，并在需要时保存句柄。
• 明确定义析构／取消注册逻辑，以避免绑定失效。

3) 数据绑定和刷新

• 从一个权威数据源（子系统／组件／视图模型）绑定运行时数据。
• 对于高频数据，尽可能使用事件驱动刷新。
• 显示控件应保持只读，不修改游戏状态。

4) 输入和焦点所有权

• 打开／关闭 UI 上下文时，明确设置输入模式。
• 将键盘／用户焦点设为预期的根控件。
• 确保关闭时焦点能返回游戏。

5) 工具提示／弹出窗口的视口边界限制

• 根据锚点和光标／控件几何信息计算所需的工具提示位置。
• 将最终位置限制在视口边界内，避免渲染到屏幕之外。
• 对高频悬停更新进行防抖，避免闪烁。

6) 移除和清理

• 关闭时从父级或视口中移除控件。
• 清除计时器／委托和临时引用。
• 确认重新打开后不会残留重复实例。

约束

• 将 UI 渲染与游戏状态修改分离。
• 避免从被动显示控件直接写入游戏状态。
• 将工具提示和弹出窗口的位置限制在视口边界内。
• 优先采用确定性的输入所有权和焦点转换。
• 将仅使用 Slate 的代码隔离在清晰的桥接边界后。
• 如果可以使用事件驱动更新，就不要依赖逐帧轮询。

故障处理

• 症状：小组件出现后却从不刷新。
  • 排查：构造时机、绑定注册、源事件触发。
  • 修复：在源就绪后绑定，并验证事件订阅路径。
• 症状：小组件刷新一次后就停止。
  • 排查：委托句柄丢失，或小组件重建时未重新绑定。
  • 修复：在构造时重新绑定，在析构时解除绑定；避免重复创建和销毁。
• 症状：输入被 UI 意外拦截。
  • 排查：当前输入模式和获得焦点的小组件路径。
  • 修复：强制使用预期的输入模式，并设置明确的焦点目标。
• 症状：弹出窗口打开后，键盘／控制器导航失效。
  • 排查：焦点转移及返回路径。
  • 修复：存储先前的焦点所有者，并在弹出窗口关闭时恢复。
• 症状：工具提示在屏幕边缘附近闪烁。
  • 排查：夹紧输出振荡和悬停源抖动。
  • 修复：对悬停更新进行防抖，并使用稳定的视口指标进行夹紧。
• 症状：反复打开／关闭后内存持续增长。
  • 排查：过期的委托／计时器／引用仍被保留。
  • 修复：在拆除时清除绑定和临时引用。

UE5.6-UE5.8 兼容性说明

• 上文列出的 UMG 生命周期、输入模式和 Slate 焦点 API 在 UE5.6-UE5.8 中保持稳定。
• 在所有受支持的版本中，优先使用 Enhanced Input，并明确管理 UI 输入模式的所有权。

升级处理

• 当行为需要超出项目范围的引擎级 Slate 自定义时，升级处理。
• 当 UI 架构与现有 CommonUI 框架决策冲突时，升级处理。