ue5-ui-umg-slate

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quick Start

快速开始

Identify whether feature belongs to UMG, Slate, or hybrid bridge.
Define data source component/subsystem and UI binding point.
Output widget tree intent and runtime binding sequence.

判断功能属于UMG、Slate还是混合桥接类型。
定义数据源组件/子系统以及UI绑定点。
输出组件树设计意图和运行时绑定顺序。

UE5.7 API Anchors

UE5.7 API锚点

UMG lifecycle and viewport anchors:

UUserWidget::NativeConstruct()

UUserWidget::NativeDestruct()

```
UUserWidget::AddToViewport(...)
```
```
UWidget::RemoveFromParent()
```
```
UWidget::SetVisibility(...)
```
```
UWidget::SetKeyboardFocus()
```

UMG input mode anchors:

UWidgetBlueprintLibrary::SetInputMode_UIOnlyEx(...)

UWidgetBlueprintLibrary::SetInputMode_GameAndUIEx(...)

UWidgetBlueprintLibrary::SetInputMode_GameOnly(...)

UMG/Slate bridge anchors:

```
UWidget::TakeWidget()
```
for Slate bridge hand-off
```
SCompoundWidget
```
,
```
SLATE_BEGIN_ARGS(...)
```

FSlateApplication::SetKeyboardFocus(...)

SetUserFocus(...)

Viewport geometry anchor:

UGameViewportClient::GetViewportSize(...)

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 Stage Contract

UI阶段约定

Every UI task must define:
- UI layer ownership (UMG-only, Slate-only, or hybrid bridge)
- data source and update trigger (pull, push, event, or mixed)
- focus and input ownership transition
- viewport-safe placement behavior for tooltip/popup
- teardown/cleanup path for unbinds and widget removal
If any item is missing, the UI implementation is incomplete.

每个UI任务必须定义:
- UI层归属（仅UMG、仅Slate或混合桥接）
- 数据源与更新触发方式（拉取、推送、事件或混合模式）
- 焦点与输入权转移规则
- 提示框/弹窗的视口安全放置行为
- 解绑与组件移除的销毁/清理流程
若上述任意项缺失，则UI实现视为不完整。

Workflow

工作流

1) UI Architecture Decision

1) UI架构决策

Select UMG for standard game HUD/menu work.
Select Slate for custom rendering/input behavior that UMG cannot express cleanly.
Select hybrid when a
```
UWidget
```
host needs to embed custom Slate content.

标准游戏HUD/菜单开发选择UMG。
若UMG无法简洁实现自定义渲染/输入行为，则选择Slate。
当
```
UWidget
```
宿主需要嵌入自定义Slate内容时，选择混合模式。

2) Construct and Lifetime

2) 构造与生命周期

Initialize widget bindings in construct/init path.
Register event listeners once and store handles when required.
Define destruct/unregister logic explicitly to avoid stale bindings.

在构造/初始化流程中初始化组件绑定。
按需注册事件监听器并存储句柄。
显式定义销毁/注销逻辑，避免无效绑定。

3) Data Binding and Refresh

3) 数据绑定与刷新

Bind runtime data from one authoritative source (subsystem/component/view model).
Use event-driven refresh for high-frequency data where possible.
Keep display widgets read-only for gameplay state mutation.

从单一权威数据源（子系统/组件/视图模型）绑定运行时数据。
对于高频数据，尽可能使用事件驱动式刷新。
保持显示组件仅可读，避免修改游戏玩法状态。

4) Input and Focus Ownership

4) 输入与焦点权

Set input mode deliberately when opening/closing UI contexts.
Set keyboard/user focus to intended root widget.
Ensure focus return path back to gameplay on close.

打开/关闭UI上下文时，明确设置输入模式。
将键盘/用户焦点设置为目标根组件。
确保关闭UI后焦点能返回至游戏玩法。

5) Tooltip/Popup Viewport Clamp

5) 提示框/弹窗视口限制

Compute desired tooltip position from anchor and cursor/widget geometry.
Clamp final placement to viewport bounds to avoid off-screen rendering.
Debounce high-frequency hover updates to avoid flicker.

根据锚点和光标/组件几何计算提示框的期望位置。
将最终位置限制在视口边界内，避免渲染到屏幕外。
对高频悬停更新进行防抖处理，避免闪烁。

6) Remove and Cleanup

6) 移除与清理

Remove widget from parent or viewport on close.
Clear timers/delegates and transient references.
Confirm no duplicate instances persist after reopen.

关闭时将组件从父容器或视口中移除。
清除计时器/委托和临时引用。
确认重新打开后无重复实例残留。

Constraints

约束条件

Keep UI rendering and gameplay state mutation separated.
Avoid direct gameplay writes from passive display widgets.
Clamp tooltip and popup placement to viewport bounds.
Prefer deterministic input ownership and focus transitions.
Keep Slate-only code isolated behind clear bridge boundaries.
Do not rely on per-frame polling if event-driven updates are available.

分离UI渲染与游戏玩法状态修改逻辑。
避免从被动显示组件直接写入游戏玩法数据。
将提示框和弹窗的位置限制在视口边界内。
优先使用确定性的输入权和焦点转移规则。
将仅Slate代码隔离在清晰的桥接边界之后。
若有事件驱动更新可用，请勿依赖每帧轮询。

Failure Handling

故障处理

Symptom: widget appears but never refreshes.
- Locate: construct timing, binding registration, source event firing.
- Fix: bind after source readiness and verify event subscription path.
Symptom: widget refreshes once then stops.
- Locate: lost delegate handle or widget recreated without rebind.
- Fix: rebind on construct and unbind on destruct; prevent duplicate create/destroy churn.
Symptom: input is swallowed by UI unexpectedly.
- Locate: current input mode and focused widget path.
- Fix: enforce intended input mode and set explicit focus target.
Symptom: keyboard/controller navigation breaks after popup open.
- Locate: focus transfer and return path.
- Fix: store previous focus owner and restore on popup close.
Symptom: tooltip flickers near screen edges.
- Locate: oscillating clamp output and hover source jitter.
- Fix: debounce hover updates and clamp with stable viewport metrics.
Symptom: memory growth after repeated open/close.
- Locate: stale delegate/timer/reference retention.
- Fix: clear bindings and transient refs in teardown.

症状：组件显示但从不刷新。
- 排查：构造时机、绑定注册、源事件触发情况。
- 修复：在数据源就绪后进行绑定，并验证事件订阅路径。
症状：组件刷新一次后停止。
- 排查：委托句柄丢失或组件重建时未重新绑定。
- 修复：在构造时重新绑定，销毁时解绑；避免重复创建/销毁的频繁波动。
症状：输入意外被UI吞噬。
- 排查：当前输入模式和焦点组件路径。
- 修复：强制执行预期输入模式，并设置明确的焦点目标。
症状：弹窗打开后键盘/控制器导航失效。
- 排查：焦点转移和返回路径。
- 修复：存储之前的焦点所有者，弹窗关闭时恢复。
症状：提示框在屏幕边缘附近闪烁。
- 排查：限制输出的振荡和悬停源抖动。
- 修复：对悬停更新进行防抖处理，并使用稳定的视口指标进行限制。
症状：反复打开/关闭后内存增长。
- 排查：残留的委托/计时器/引用。
- 修复：在销毁流程中清除绑定和临时引用。

UE5.6 / UE5.7 Compatibility Notes

UE5.6 / UE5.7 兼容性说明

UMG lifecycle, input mode, and Slate focus APIs listed above are stable in UE5.6/UE5.7.
Prefer Enhanced Input + explicit UI input mode ownership in both versions.

上述列出的UMG生命周期、输入模式和Slate焦点API在UE5.6/UE5.7中均稳定。
在两个版本中，优先使用Enhanced Input + 明确的UI输入权归属。

Escalation

升级处理

Escalate when behavior requires engine-level Slate customization beyond project scope.
Escalate when UI architecture conflicts with existing CommonUI framework decisions.

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