WebUIX

最小 HTML 示例

<div class="demo-shell">
  <h2>{{loc:demo.title|WebUIX Demo}}</h2>
  <button id="switch-image" onclick="SwitchImage">
    {{loc:demo.switch_image|Switch Image}}
  </button>
  <webuix-option-stepper
    id="demo-quality-stepper"
    label="{{loc:demo.graphics_quality|Graphics Quality}}"
    options="GraphicsQualityOptions"
    display-key="DisplayName"
    value-key="Value"
    data-webuix-bind-value="GraphicsQualityIndex"
    onchange="OnGraphicsQualityChanged">
  </webuix-option-stepper>
</div>

使用到游戏中

• 点击 Compile 和 Save。
• 运行时像普通 UMG 一样 Create Widget 后 Add to Viewport，也可以放进 HUD、其他 UMG 或 3D Widget 工作流。
• 多个界面需要共享同一套源码时，仍然可以引用独立 WebUIX HTML / CSS 资产；单个界面优先直接在 WebUIXUserWidget 内完成。

预览与页面状态

编辑器提供预览复用与滚动位置恢复，方便连续编辑同一页面。运行时切换页面时，可使用 Widget 组件池 复用实例并保留页面状态；局部内容变化优先使用模型、class 或 style 更新，刷新接口见 Blueprint API。

变换 HUD 与交互检查

嵌套 transform、hover 缩放和全屏尺寸变化涉及绘制、命中测试与裁剪。制作 HUD 时，在预览中同时检查视觉位置、鼠标或触摸命中区域和滚动容器裁剪，并用 调试控制台 查看元素。运行时 Inspector 的打包选项见 项目设置。

页面配置

模板变量

<div class="loading-screen startup-screen">
  <div class="brand">WebUIX</div>
  <div class="subtitle">{{LoadingStatus}}</div>
  <div class="bar">
    <div class="bar-fill" style="width: {{LoadingProgressPercent}}%;"></div>
  </div>
</div>

Timing 配置

Skip 配置

蓝图生命周期

在 Loading Config Blueprint 内实现这些事件和函数，可以控制开始显示、地图加载、加载完成、跳过请求、是否隐藏和是否允许跳过。

全局 Blueprint API

建议由加载管理器或 GameInstance 统一调用 WebUIX Set Loading Progress，页面只负责展示模板变量和响应生命周期事件。

支持的 HTML 标签

扩展元素：drag-area drag-cell drag-item handle radio-group radio-option checkbox-group checkbox-option dropdown dropdown-option password modal modal-title modal-footer tooltips tooltips-content animation-watch

CSS 属性速查

Pseudo-class 状态

扩展状态：:selected :open :dragging :valid :invalid :hot :occupied。部分 pseudo-state 会同步为 CSS class（.selected .open .disabled）。

资源引用

图片和音频通过 UE 资产路径引用：

<img src="/Game/UI/Icons/Sword.Sword" />

.icon { background-image: url("/Game/UI/Icons/Sword.Sword"); }
.banner { background: url(banner.png) center / cover no-repeat; }

散列图片文件（PNG、JPG）在 Cook 时嵌入到 UWebUIXHtmlDocument 的派生数据中。

filter

filter 属性对元素及其子元素的渲染结果应用图形效果。

.card {
  filter: drop-shadow(0 10dp 24dp #00000066);
}
.card:hover {
  filter: brightness(1.1) drop-shadow(0 14dp 32dp #00000088);
  transition: filter 200ms;
}
.inactive {
  filter: brightness(0.6) saturate(0.3);
}

backdrop-filter

backdrop-filter 对元素背后区域的内容应用滤镜（常用于毛玻璃效果）。

.glass-panel {
  background: rgba(255,255,255,.12);
  backdrop-filter: blur(16dp);
  border: 1dp rgba(255,255,255,.2);
  border-radius: 16dp;
}
.overlay {
  backdrop-filter: blur(8dp) brightness(0.5);
}

filter 与动画

filter 属性支持 CSS transition 和 animation 平滑过渡：

.btn {
  filter: brightness(1);
  transition: filter 150ms ease;
}
.btn:hover { filter: brightness(1.15); }
.btn:active { filter: brightness(0.92); }

@keyframes pulse-glow {
  0%, 100% { filter: drop-shadow(0 0 4dp #38bdf844); }
  50%      { filter: drop-shadow(0 0 16dp #38bdf8aa); }
}
.glow { animation: pulse-glow 2s ease-in-out infinite; }

CSS 属性

触发时机

音效在以下 pseudo-class 激活时自动播放：

• :hover — 鼠标悬停时
• :active — 按下时（鼠标/触摸）
• :focus — 获得焦点时（Tab 导航等）

使用示例

资产路径使用 asset:/// 前缀（编辑器资源选择器自动补全）：

/* Hover: glass sound, 50ms cooldown */
.ui-hover-sound:hover {
  background-sound: url("asset:///WebUIX/WebUIX/Sound/glass_001.glass_001");
  background-sound-volume: 0.35;
  background-sound-cooldown: 0.05s;
}

/* Click: crisp click sound, higher volume */
.ui-click-sound:active {
  background-sound: url("asset:///WebUIX/WebUIX/Sound/click_003.click_003");
  background-sound-volume: 0.55;
  background-sound-cooldown: 0.05s;
}

/* Focus: focus feedback sound */
.ui-focus-sound:focus {
  background-sound: url("asset:///WebUIX/WebUIX/Sound/close_002.close_002");
  background-sound-volume: 0.28;
}

<button class="btn primary ui-hover-sound ui-click-sound ui-focus-sound">
  Confirm
</button>

CSS Transitions

支持对所有可动画属性的平滑过渡。常用可动画属性：color background-color opacity transform filter width height margin padding。

.card {
  transform: scale(1);
  filter: brightness(1);
  transition: transform 180ms ease, filter 150ms;
}
.card:hover { transform: scale(1.04); filter: brightness(1.1); }

@keyframes

@keyframes slide-in {
  0%   { transform: translateY(-24dp); opacity: 0; }
  100% { transform: translateY(0);     opacity: 1; }
}
.modal-open { animation: slide-in 200ms ease-out; }

@keyframes fade-pulse {
  0%, 100% { opacity: 1; }
  50%      { opacity: 0.5; }
}
.loading { animation: fade-pulse 1.2s ease-in-out infinite; }

支持：timing-function、iteration-count、direction、fill-mode、delay、play-state。

animation-watch 元素

animation-watch 观察 CSS 动画状态并通过事件桥发送 JSON payload 给 Blueprint。详见扩展元素章节。

保留式动画路径

不需要布局且满足合成条件时，transform 和 opacity 动画可复用保留层；其他路径可能重新绘制。请用调试统计确认实际行为。

局部视觉变化优先使用 class、style 或模型更新，避免替换整份 HTML；改变 show、尺寸或布局样式仍可能触发布局。

快速创建

1. 创建 Blueprint，父类选择 UWebUIXComponent
2. 在 Class Settings 中填写 TagName（如 my-card）
3. 编写默认 HTML 模板和 CSS — 这构成组件内部结构
4. 实现 Construct / Tick / Destruct 事件，通过 Dom 操作内部 DOM

暴露属性与事件 — 点击"公开"即可

在 Blueprint 中编写 UFUNCTION(BlueprintCallable) 函数后，只需在函数上点击 公开到 HTML，该函数就会自动成为 HTML 中可用的 OnXxx 事件属性。同样，Blueprint 变量点击公开后，即可在 HTML 中作为自定义属性使用。

<!-- Exposed as event: bind directly in HTML -->
    <my-card title="Sword" OnCardClicked="OnSwordPicked(id)" OnRarityChanged="OnRarityUpdate(rarity)"></my-card>

    <!-- Exposed as attribute: pass values like native attributes -->
    <my-card title="Sword of Light" badge="{{Model.NewItems}}" rarity="epic" locked="true">
    <p>A legendary weapon.</p>
    </my-card>

    <!-- Exposed as function: call directly in templates -->
    <span>{{UE::CallText(GetCardStatus)}}</span>

编辑器的 HTML 代码补全会自动列出所有已注册组件的自定义属性、事件和函数，无需手动查找。

注册组件

全局：添加到 Project Settings → WebUIX → Components，所有文档可用。
文档级：添加到 UWebUIXHtmlDocument 的 Components 数组，仅该文档可用。

DOM API

Dom->GetElementById("my-id");
    Dom->QuerySelector(".my-class");
    Dom->SetAttribute("badge", "5");
    Dom->ClassListAdd("highlight");
    Dom->StyleSetProperty("color", "#ff0");
    Dom->SetTextContent("Updated!");
    Dom->AppendChild(newElement);

独立四边与线型

可使用 border、border-width/style/color，或 border-top/right/bottom/left 简写与长写。四边可混合宽度、线型和颜色，并按浏览器式角点归属绘制。

椭圆与百分比圆角

border-radius 支持一至四个角、斜杠分隔的水平/垂直半径、四角独立属性和百分比。

.panel {
  border-radius: 24dp 12dp 32dp 8dp / 16dp 28dp 12dp 20dp;
}
.avatar {
  border-radius: 50%;
}

圆角阴影

box-shadow 可配合 border-radius 绘制圆角外阴影与 inset 内阴影，支持多个逗号分隔的阴影层，以及偏移、模糊、扩展半径和透明颜色。外阴影会扩大绘制范围；大面积模糊阴影会增加绘制成本。

.shadow-panel {
  border-radius: 16dp;
  box-shadow: 0 8dp 24dp #00000066, inset 0 1dp 0 #ffffff33;
}

轮廓与偏移

outline 绘制在边框外侧且不占布局空间；outline-offset 可将其向内或向外偏移。

.focused {
  outline: 2dp dashed #67e8f9;
  outline-offset: 6dp;
}

九宫格边框图片

border-image 支持 source、slice、width、outset、repeat、fill 和简写形式，可用于可缩放框体。

.frame {
  border: 12dp solid transparent;
  border-image: url("/Game/UI/Frame.Frame") 24 fill / 12dp / 0 stretch;
}

混合边框示例

每条边和每个角都可以独立配置；相邻边按确定的浏览器式归属衔接，不会改变声明的边框宽度。

.mixed {
  border-top: 4dp solid #2563eb;
  border-right: 6dp dashed #0d9488;
  border-bottom: 7dp dotted #d97706;
  border-left: 8dp double #7c3aed;
  border-top-left-radius: 18dp 12dp;
  border-top-right-radius: 8dp 20dp;
  border-bottom-right-radius: 24dp 10dp;
  border-bottom-left-radius: 12dp 24dp;
}

兼容性说明

优先使用标准浏览器语法。WebUIX 将布局尺寸与边框绘制分开处理，因此轮廓和装饰边框无需额外补偿缝隙。

上下文变量 {{变量}}

从 Widget Blueprint 或 Bridge Target 的同名属性读取值。调用 NotifyContextChanged("VariableName") 刷新。

<span>{{PlayerName}}</span>
<div style="width: {{Percent}}%;">{{Score}}</div>

数据模型 {{Model.Key}}

通过 SetModelString/SetModelNumber/SetModelBool 写入，HTML 中用 {{Model.Key}} 读取。

Widget->SetModelString("PlayerName", "Alice");
Widget->SetModelNumber("Health", 85.0f);
Widget->SetModelBool("IsAlive", true);
Widget->NotifyContextChanged();

本地化 {{loc:key|fallback}}

<span>{{loc:ui.start_button|Start Game}}</span>
<span>{{loc:hud.health|Health}}: {{Model.Health}}</span>

运行时切换语言：Widget->SetCulture("zh-Hans"); Widget->RefreshLocalization();

UE 内置统计 {{UE::FPS}}

UE::CallText / UE::CallHtml

调用 UFUNCTION 并将返回值插入 HTML 中。CallText 插为纯文本，CallHtml 插为 HTML 片段。

<h2>{{UE::CallText(GetPanelTitle)}}</h2>
<span>{{UE::CallText(FormatScore, Value=Model.Score)}}</span>
<div html="UE::CallHtml(BuildInventoryRows)"></div>

模板指令

<!-- forEach loop -->
<template foreach="item in Model.Items">
  <div class="item-row">{{item.Name}} &times; {{item.Count}}</div>
</template>

<!-- Conditional rendering -->
<template if="{{Model.IsLoggedIn}}">
  <div class="welcome">Welcome, {{PlayerName}}!</div>
</template>
<template else>
  <div class="login-prompt">Please log in.</div>
</template>

<!-- switch -->
<template switch="{{Model.Tab}}">
  <template case="inventory"><div>Inventory</div></template>
  <template case="shop"><div>Shop</div></template>
  <template default><div>Unknown</div></template>
</template>

<!-- show visibility control -->
<div show="{{Model.HasBonus}}">Bonus Active!</div>

HTML 语法

所有可见文本都可以使用 {{loc:key|fallback}}。key 是稳定的翻译 ID；fallback 是翻译还不存在时使用的源文本。

<h2>{{loc:menu.title|Main Menu}}</h2>
<button onclick="StartGame">{{loc:menu.start|Start Game}}</button>
<span>{{loc:hud.health|Health}}: {{Model.Health}}</span>

属性与组件标签

本地化也可以写在属性值里，包括 label、placeholder、title、aria 文本以及 WebUIX 扩展元素配置。

<webuix-option-stepper
  label="{{loc:settings.graphics_quality|Graphics Quality}}"
  options="GraphicsQualityOptions"
  display-key="DisplayName"
  value-key="Value"
  onchange="OnGraphicsQualityChanged">
</webuix-option-stepper>

<input placeholder="{{loc:login.name_placeholder|Player name}}" />

Key 命名

推荐使用按功能域划分的 key，这样布局变化时翻译仍然稳定。不要用行号或临时控件名作为 key。

收集与编译流程

1. 在 WebUIX HTML 中新增或修改 {{loc:key|fallback}}，并保存资产。
2. 在 Unreal Editor 的 Localization 面板中打开项目本地化目标，确保资产收集范围包含 Content/WebUIX/Generated，然后运行 Gather。
3. 在同一面板中编辑或导入目标语言的翻译，然后运行 Compile。
4. 保存生成的本地化资源，并在项目打包设置中包含目标 culture。

运行时切换语言

在 WebUIX widget 上调用 Set Culture 可以切换 UE culture 并重新加载本地化文本。如果 culture 已经由外部系统切换，只需要刷新当前文档文本时使用 Refresh Localization。

Set Culture: zh-Hans
Set Culture: en
Refresh Localization

打包检查清单

• 打包项目包含目标 culture，例如 en 或 zh-Hans。
• 游戏可切换到的每个 culture 都包含对应的本地化资源（locres）。
• HTML fallback 可作为兜底文本，但正式文本应来自本地化资源。

常见问题

支持的事件

使用示例

<button OnClick="StartGame">Start</button>
<button OnClick="OpenSettings(panel='video')">Settings</button>

<input value="{{Model.SearchText}}" OnChange="OnSearchChanged(value)" />
<input value="{{Model.Name}}" OnInput="OnNameInput(value)" />

<div class="item-slot" OnClick="OnSlotClicked(id)" />
<drag-area OnDrop="OnItemDropped(event, id)" />

Bridge Object

创建 UWebUIXBridgeObject，设置 TargetObject，赋给 Widget 的 BridgeObject 属性。事件按名称路由到目标对象。

控件导航

使用 nav-order 设置导航目标，使用 OnFocus / OnBlur 响应焦点变化。焦点、键盘与手柄操作、方向规则和页面切换见 控件导航。

基本用法

<animation-watch id="hud-watch"
  scope="subtree"
  visible-only="true"
  emit-update="true"
  update-rate="8"
  OnAnimationStart="OnHudAnimationStart"
  OnAnimationUpdate="OnHudAnimationUpdate"
  OnAnimationEnd="OnHudAnimationEnd"
  OnAnimationCancel="OnHudAnimationCancel">
  <div class="animated-card">Reward</div>
</animation-watch>

网格拖拽

<drag-area id="bag" columns="5" rows="4" count="13" gap="8dp"
  drag-anchor="center" OnDragdrop="OnBagDrop(TargetId)">
  <drag-cell class="slot">
    <span>#{{dragCell::DisplayIndex}}</span>
    <span>{{dragCell::DisplayCol}},{{dragCell::DisplayRow}}</span>
  </drag-cell>
  <drag-item id="sword" col="0" row="0" cols="2" rows="2"
    OnDragstart="OnItemDragStart" OnDragend="OnItemDragEnd">
    <b>2x2</b>
  </drag-item>
</drag-area>

模板变量：{{dragCell::DisplayIndex}} {{dragArea::UsableCount}} {{dragItem::PreviewValid}}。可通过 var-scope="Inventory" 重命名作用域。

自由拖拽（浮动面板）

<div id="panel" class="floating-panel">
  <handle class="title-bar" move_target="panel" edge_margin="0dp">
    Drag Panel
  </handle>
  <p>This panel can be moved by dragging the title bar.</p>
</div>

handle 元素通过 move_target 指定被拖拽的目标，edge_margin 限制边界。拖拽预览渲染在独立透明 RT 上，主页面纹理不会被修改。

拖拽状态 CSS

drag-cell.slot:hot { background: #38bdf833; }
drag-cell.slot:occupied { border-color: #f59e0b; }
drag-item.item:dragging { opacity: .72; transform: scale(1.04); }
drag-item.item:invalid { filter: drop-shadow(0 0 8dp #ef4444); }

radio-group / radio-option

<radio-group value="comfortable" name="Density" OnChange="OnRadioChanged(value)">
  <radio-option value="compact">Compact</radio-option>
  <radio-option value="comfortable" selected>Comfortable</radio-option>
  <radio-option value="debug">Debug</radio-option>
</radio-group>

checkbox-group / checkbox-option

<checkbox-group value="svg,animation" OnInput="OnFeaturesInput(value)">
  <checkbox-option value="svg" selected>SVG</checkbox-option>
  <checkbox-option value="animation" selected>Animation</checkbox-option>
  <checkbox-option value="ime">IME</checkbox-option>
</checkbox-group>

多选值按 DOM 顺序保存为逗号分隔字符串。

dropdown / dropdown-option

支持单选和多选（multiple="true"）。打开时菜单在内部 Popup Layer 绘制，DOM 和事件冒泡保持在 dropdown 内。

<dropdown value="rhi" placeholder="Select mode"
  OnChange="OnDropdownChanged(value)">
  <dropdown-option value="rhi" selected>RHI</dropdown-option>
  <dropdown-option value="slate">Slate fallback</dropdown-option>
</dropdown>

modal

通过 value="true|false" 控制。modal-title 和 modal-footer 自定义标签；不写 footer 则自动生成按钮。

<button modal-action="open" modal-target="settings-modal">Open</button>
<modal id="settings-modal" value="{{SettingsModalOpen}}"
  width="420dp" mask="true" close-on-click-modal="true"
  close-on-press-escape="true" lock-scroll="true"
  OnChange="OnSettingsModalChanged(value)">
  <modal-title>Settings</modal-title>
  <modal-footer>
    <button modal-action="cancel">Cancel</button>
    <button modal-action="confirm">Confirm</button>
  </modal-footer>
</modal>

tooltips

<tooltips placement="top" effect="dark">
  <button>Hover me</button>
  <tooltips-content>
    <b>Tip title</b>
    <p>Explain this setting.</p>
  </tooltips-content>
</tooltips>

password

内部管理原生 password/text 输入和眼睛切换按钮。支持 visible="true|false" show-toggle="true|false" disabled。

<password value="" placeholder="Access code"
  name="AccessCode" OnInput="OnAccessCodeInput(value)" />

标记与模板

可以直接写 radial-item，也可以通过 for 生成子项。key 用于保持重复项稳定，value 是选中值，label 会传递给事件参数；radial-center 用于自定义中心内容。

<radial-menu
  value="{{ SelectedAction }}"
  size="42%"
  hollow="true"
  inner-size="24%"
  inner-gap="8dp"
  content-radius="72%"
  start-angle="-30"
  gap-width="2dp"
  border-mode="outer"
  hover-scale="1.06"
  hover-duration="120ms"
  OnChange="OnRadialChanged(value, index, key, label)">
  <radial-item
    for="(action, index) in Actions"
    key="{{ action.Id }}"
    value="{{ action.Id }}"
    label="{{ action.Label }}"
    OnHover="OnRadialHover(value, index, key, label)"
    OnUnhover="OnRadialUnhover(value, index, key, label)">
    <img src="{{ action.Icon }}" alt="" />
    <span>{{ action.Label }}</span>
  </radial-item>
  <radial-center>{{ SelectedAction }}</radial-center>
</radial-menu>

配置属性

选择与悬停事件

在 radial-menu 上绑定 OnChange，在 radial-item 上绑定 OnHover/OnUnhover。名为 value、index、key、label 的蓝图参数会自动接收对应子项数据。

OnChange="OnRadialChanged(value, index, key, label)"
OnHover="OnRadialHover(value, index, key, label)"
OnUnhover="OnRadialUnhover(value, index, key, label)"

CSS 样式

原生几何继续负责扇区形状和命中测试；可使用普通选择器、类、transition、filter、颜色、图片和 transform 定制子项内容与交互状态。

radial-item {
  color: #d7e8fb;
  transition: transform 120ms ease-out, filter 120ms ease-out;
}
radial-item:hover {
  transform: scale(1.06);
  filter: brightness(1.12);
}
radial-item.selected { color: #67e8f9; }
radial-center { background-color: #07111b; }

性能说明

建议保持 radial-menu 挂载，只修改 value、show、class 或绑定子项数据。稳定的 key 可复用循环子项；仅选择或显隐变化时不要替换整个文档。

图标包格式

每个 emoji 图标包是一个文件夹，内含按十六进制 Unicode codepoint 命名的 SVG 文件（如 1f600.svg），多 codepoint 组合用短横线连接。这个目录结构与 Twemoji、OpenMoji、Noto Emoji 等主流开源图标集完全一致，可以零转换直接导入使用。

twemoji-common/
  1f600.svg
  1f602.svg
  1f44d.svg
  1f680.svg

Emoji Library 编辑器面板

编辑器工具栏内置 Emoji Library 面板，可以直接输入 URL 下载单个图标包（Download）、从磁盘导入已有的文件夹（Import Folder...）、导出一份示例包（Save Example Pack...）、管理已导入的图标包列表并移除（Remove），以及将当前图标包烘焙成运行时可用的图集资源（Bake For Shipping）。插件本身不内置任何 emoji 美术资源，需要自行下载或导入图标包。

真彩色渲染

自定义 emoji 保留图标的原始配色，不受 CSS 文字颜色（color 属性）影响。

基本用法

普通页面使用数值 nav-order 指定参与导航的元素。按钮保留原有 OnClick 事件，使用 :focus 为键盘和手柄焦点提供视觉反馈。

<div class="menu">
  <button id="resume" class="menu-button" nav-order="0" OnClick="OnResume">继续游戏</button>
  <button id="settings" class="menu-button" nav-order="1" OnClick="OnSettings">设置</button>
  <button id="quit" class="menu-button" nav-order="2" OnClick="OnQuit">退出</button>
</div>

.menu { display: flex; flex-direction: column; gap: 12dp; }
.menu-button:focus {
  background-color: #214c75;
  outline: 2dp solid #67e8f9;
  outline-offset: 3dp;
}

数值越小，顺序导航的位置越靠前；建议使用不同的 nav-order 值确定顺序。普通页面仅设置 tabindex="0" 不会加入导航列表，仍需设置 nav-order。

页面焦点与元素焦点

页面先获得 UMG / Slate 键盘焦点，输入才能到达 WebUIX；页面内部还需要一个当前聚焦的 HTML 元素。显示页面不会自动选中普通菜单的第一个按钮。需要初始选中项时，调用 Focus By ID 或 Focus Next Element。

使用 WebUIXUserWidget 制作页面，在 PlayerController 中创建并保存菜单实例，然后连接：

Create Widget（Owning Player = 当前 PlayerController）
→ Add to Viewport
→ Set Input Mode Game And UI（Widget to Focus = 菜单实例）
→ 菜单实例：Focus By ID（Element ID = resume）

Focus By ID 返回 true 表示聚焦成功。也可在页面构建后调用 UMG 的 Set Focus；自己管理页面激活状态时可使用 Activate。这些操作应在 Construct 或页面加入视口之后执行。

Game And UI 允许未被界面处理的键继续进入 PlayerController。使用 UI Only 时，输入动作应由 UI 路由处理；不要依赖 PlayerController 接收未处理的键。关闭界面时，项目负责恢复游戏输入与焦点。

键盘输入

表中导航行为基于 Slate 默认键盘配置。项目应保持 Tab 和方向导航启用；接入显式外部导航路由时，由项目动作调用导航接口。

在使用 Enhanced Input 的项目中，可按下面的流程给普通菜单接入键盘操作：

1. 创建 Boolean 类型的 IA_UIActivate，在 IMC_UI 中将 Enter 和 Space Bar 映射到这个 Action。
2. 打开菜单时，向当前玩家的 Enhanced Input Local Player Subsystem 添加 IMC_UI。使用高于游戏输入的优先级，并启用 Action 的 Consume Input，避免 Space 同时触发游戏动作。
3. 按前面的流程显示并聚焦菜单。在 PlayerController 中，将 IA_UIActivate 的 Started 接到菜单实例的 Accept Focused Element；调用前检查实例有效、可见、仍是当前菜单，并通过 Has User Focus 或 Has User Focused Descendants 确认菜单持有当前玩家焦点。
4. 关闭菜单时移除 IMC_UI，移除或隐藏菜单，并恢复游戏输入模式与焦点。

IA_UIActivate：Started
→ 当前菜单有效、打开且持有当前玩家焦点
→ 当前菜单：Accept Focused Element

Accept Focused Element 会提交当前展开选择器的高亮项，或点击当前焦点元素。按钮继续调用原有的 OnClick。使用 Started 可按一次按键触发一次动作；已经由原生控件处理的键不会再次交给 PlayerController。

方向导航

上、下、左、右使用元素的布局矩形选择目标，优先同一行或列的候选，再比较距离。nav-order 决定顺序导航和首次进入的起点，不会把二维布局变成一条顺序列表。

尚未聚焦有效元素时，向下或向右从第一项进入，向上或向左从最后一项进入。导航会跳过隐藏、禁用、负 tabindex 及 nav-order="none" 的元素。滚动容器内的目标可以被选中，并自动滚入可见区域。

<div nav-group="items" nav-wrap="horizontal">
  <button id="item" nav-order="0" nav-right="#details">物品</button>
</div>
<div nav-group="details">
  <button id="details" nav-order="1" nav-left="#item" nav-down="none">详情</button>
</div>

nav-group 按最近容器实例划分范围；两个容器即使使用相同标识，也不会合并。分组只约束四方向的几何导航，Tab / Next / Previous 仍遍历当前页面或顶层 modal 的顺序列表。显式方向目标可跨组，但不能越过顶层 modal 的焦点范围。

nav-wrap 使用元素自身或最近祖先的设置，子元素可设置 none 覆盖祖先。目标失效时回退到几何导航；没有可用目标且未启用环绕时，焦点保持原位。

手柄输入

默认使用左摇杆和 D-Pad 移动焦点，底部面键激活控件，右侧面键取消。页面需要可见并持有键盘焦点；纯焦点导航时，将所属 PlayerController 的 Show Mouse Cursor 设为 false。默认手柄路径可直接使用，不需要为每个按钮重复接线。

需要摇杆控制鼠标式光标时，配置 Movement Stick 并显示光标。按键绑定、设备切换、光标与滚动配置见 手柄与控制器输入。

控件中的导航

modal 内会自动纳入可用原生控件、带 href 的链接和非负 tabindex 元素，仍可使用数值 nav-order 指定顺序。close-on-press-escape="false" 禁止 Escape / 手柄取消关闭该 modal。

Blueprint 接口

以下导航接口可用于 WebUIXUserWidget 和 WebUIXWidget。Activate / Deactivate 属于 WebUIXUserWidget 的页面生命周期。

页面切换

单个页面可自行 Create Widget、Add to Viewport、Activate；关闭时 Deactivate 并隐藏或移除页面。Deactivate 不会自动隐藏页面、清除 Slate 焦点或恢复游戏输入模式。关闭后由项目将焦点交给下一页或游戏。

主菜单 → 设置 → 图形设置这类多层界面，可以使用 WebUIXNavigationStack：

1. 在 PlayerController 中用 Construct Object from Class 创建 WebUIXNavigationStack，Outer 设为 PlayerController，并保存到 Blueprint 变量。
2. 用 Push Widget 传入 WebUIXUserWidget 页面类和 Owning Player。栈会创建新页面，暂停并隐藏旧页面，显示并激活新页面。
3. 返回时调用 Pop Widget。栈移除当前页面，并重新显示、激活上一页；暂停页保留 DOM、表单、滚动与元素焦点状态。
4. 退出全部菜单时调用 Clear Widgets，随后由项目移除菜单输入映射并恢复游戏输入。

Get Active Widget 返回当前栈顶，Num Widgets 返回页面数量。通过栈打开的页面由栈管理 Activate / Deactivate。栈不管理 Input Mode、鼠标显隐或 Mapping Context；这些由项目控制。

普通 HUD 只需 Add to Viewport 显示。需要持续游戏操作的 HUD 不应作为菜单焦点目标或进入页面导航栈。

接入项目输入系统

项目可以把自己的输入动作接到 Navigate、Accept Focused Element 和 Handle Back。多页面项目应只向当前活动页面派发动作。OnAnyKeyDown / OnAnyKeyUp 是不消费输入的全局监听事件，适合按键提示和改键界面；不要同时用它们和已有 Action 重复激活同一控件。

可选的 CommonUI / Enhanced Input 适配模板用于接入项目已有的页面和动作路由。适配器接管显式导航动作时，应通过该路由调用上述接口。普通页面的默认键盘导航、原生手柄配置与项目输入动作，应各有明确的处理入口。

页面显示但不能导航时，先检查 UMG 页面焦点、HTML 初始元素、nav-order 和控件可见/可用状态，再检查项目的输入模式与按键路由。

Project Settings 与自动检测

WebUIX 默认启用手柄输入系统和按设备自动切换输入模式。最近使用的键鼠、触控或手柄输入会更新活动设备。菜单应可见并持有键盘焦点，使用 UI Only 或 Game And UI 输入模式；页面焦点与导航规则见 控件导航。在 Project Settings → Game → WebUIX → Gamepad Input 中调整配置。

[/Script/WebUIX.WebUIXSettings]
bEnableWebUIXGamepadInputSystem=True
bAutoSwitchInputModeByDevice=True
; GamepadInput defaults (mirrors stock UE gamepad feel):
; ConfirmKey=Gamepad_FaceButton_Bottom, CancelKey=Gamepad_FaceButton_Right
; DirectionalNavStick=Gamepad_Left2D
; NavUpKey=Gamepad_DPad_Up, NavDownKey=Gamepad_DPad_Down
; NavLeftKey=Gamepad_DPad_Left, NavRightKey=Gamepad_DPad_Right

虚拟光标与 UWebUIXGamepadCursorLibrary

进入手柄模式不会自动显示虚拟光标。需要摇杆移动光标时，配置 Movement Stick，并将活动页面所属 PlayerController 的 Show Mouse Cursor 设为 true；此时确认点击光标位置。隐藏光标后，确认作用于当前焦点元素。Scroll Stick 可独立滚动焦点所在区域，不受光标显隐影响。UWebUIXGamepadCursorLibrary 提供设备覆盖、配置覆盖和光标外观接口。

全局按键监听事件

OnAnyKeyDown / OnAnyKeyUp 是 WebUIX User Widget、Widget 和 Element Extension 上的被动全局监听事件，键盘、鼠标与手柄输入都会触发，且不会消费输入。可用于按键提示与改键界面。OnInputDeviceChanged 在活动设备变化时触发，提供设备类型及手柄型号名称。

DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FWebUIXKeyEventDelegate, FKeyEvent, KeyEvent);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_TwoParams(FWebUIXInputDeviceChangedDelegate, EWebUIXInputDeviceType, DeviceType, FName, GamepadModel);

// UWebUIXElementExtension / UWebUIXUserWidget / UWebUIXWidget:
UPROPERTY(BlueprintAssignable) FWebUIXKeyEventDelegate OnAnyKeyDown;
UPROPERTY(BlueprintAssignable) FWebUIXKeyEventDelegate OnAnyKeyUp;
UPROPERTY(BlueprintAssignable) FWebUIXInputDeviceChangedDelegate OnInputDeviceChanged;

nav-order 属性

普通页面用数值 nav-order 声明导航目标。Tab / Next / Previous 按其顺序移动；方向键、D-Pad 与导航摇杆按二维布局选择目标。方向覆盖、分组和环绕设置见 控件导航。

<div class="menu">
  <button nav-order="0" OnClick="OnResume">Resume</button>
  <button nav-order="1" OnClick="OnSettings">Settings</button>
  <button nav-order="2" OnClick="OnQuit">Quit</button>
</div>

UWebUIXNavigationStack

WebUIXNavigationStack 用于管理菜单、设置等多层页面。栈管理页面显示与激活，暂停页保留状态；项目管理输入模式与菜单按键。创建、Push / Pop 和返回游戏流程见 控件导航。

默认绑定

取消操作不会自动返回项目的上一页面。需要返回菜单时，项目可先调用 Handle Back；未处理时再执行自己的页面返回流程。

运行时改键

WebUIX Get Gamepad Input Config
→ Set Members（修改需要的按键或摇杆字段）
→ WebUIX Set Gamepad Input Config Override

使用 Get 取得当前配置，再修改需要的字段。将玩家配置保存到 SaveGame 后，可在下次运行时重新应用。WebUIX Clear Gamepad Input Config Override 恢复项目默认配置。

增量更新

使用方式

// C++
PoolComponent->ShowWebUIXWidget(MyWidgetClass, ViewportZOrder);
PoolComponent->HideWebUIXWidget(MyWidgetClass);
// Calling Show again reuses the same instance — no recreation

Blueprint 中对应节点：Show WebUIX Widget → Hide WebUIX Widget → Show WebUIX Widget（复用实例）。

配置条件

1. Widget Blueprint 父类必须是 UWebUIXUserWidget。
2. 设置 bWarmupOnGameStart = true。
3. 必须设置 DocumentAsset。

预热模式

预计算内容

事件属性

CSS 属性速查

输入与 IME

Windows IME 通过 UE 文本输入接口接入。OnInput 实时同步、OnChange 提交语义、OnTextInput 底层字符流（中文输入不要只依赖它）。

圆盘菜单与边框速查

完整语法、事件参数、尺寸行为和示例请参阅 CSS 边框与圆盘菜单章节。