WebUIX

概览

快速开始

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

编辑器工作流

Loading Config

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

编辑器界面

这些界面展示 WebUIX 的主要编辑体验：在 Unreal Editor 内同时处理 HTML/CSS、实时预览、Blueprint 逻辑、Loading Screen 配置、本地化文本和项目级设置。

支持的 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）会通过 WebUIX 资源解析与 cook 流程进入运行时资源缓存。

filter

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

.card {
  filter: drop-shadow(0 10dp 24dp #00000066);
}
.card:hover {
  filter: brightness(1.1) drop-shadow(0 14dp 32dp #00000088);
}

backdrop-filter

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

.glass-panel {
  background: rgba(255,255,255,.12);
  backdrop-filter: blur(16dp);
}

filter 与动画

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

CSS 属性

触发时机

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

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

使用示例

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

.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;
}

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; }
}

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

animation-watch 元素

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

项目级注册

1. 创建 Blueprint 组件类，父类选择 WebUIXComponent。
2. 设置组件 TagName。HTML 中写同名标签时，运行时会按归一化标签名匹配并展开该组件。
3. 在组件 Blueprint 中暴露属性、事件或函数；编辑器补全会读取这些描述，HTML 中可通过属性和事件回调使用。
4. 需要全项目可用时，把组件类添加到 Project Settings → Plugins → WebUIX Settings → Components。只给某个页面使用时，把组件类添加到对应 WebUIXUserWidget 的 Embedded Document Components 列表。

单个 Widget 配置

运行时会把 Project Settings 中的组件和当前 Widget Embedded Document 的组件合并为 active components，并按 HTML 标签名展开匹配项；不需要单独创建 HTML uasset 才能使用组件。

<my-card title="Sword" OnCardClicked="OnSwordPicked(id)"></my-card>
<span>{{UE::CallText(GetCardStatus)}}</span>

组件默认 HTML 可以继续嵌套 WebUIX 标签、模板变量和事件属性。把组件写进 HTML 后，它会像普通标签一样参与解析、样式计算、布局和事件桥。

直接写入 HTML

如果组件需要复用样式，CSS 仍可放在共享 UWebUIXCssStyleSheet 或当前 Embedded CSS 中；HTML 源码优先维护在 WebUIXUserWidget 的 Embedded Document 里。

DOM API

Dom->GetElementById("my-id");
Dom->QuerySelector(".my-class");
Dom->SetAttribute("badge", "5");
Dom->SetTextContent("Updated!");

示例：BP_InputIcon

BP_InputIcon 就是这套自定义组件系统的一个实际示例：一个 UWebUIXElementExtension 派生组件，根据当前输入设备渲染对应的键鼠或手柄按键图标。可以在 Element Extension Editor（见编辑器工作流）里打开并实时预览它的渲染效果。

上下文变量 {{变量}}

从 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::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>

模板指令

当前模板指令写在普通元素属性上。循环使用 for="(item, index) in Items"，条件分支使用 if / else-if / else，可见性切换使用 show；key 用于循环项稳定复用。

<!-- repeat an element -->
<div class="item-row" for="(item, index) in Items" key="item.Id">
  {{index}}. {{item.Name}} &times; {{item.Count}}
</div>

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

<!-- visibility toggle: keeps the element and toggles display -->
<div class="bonus" show="{{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>

属性与组件标签

本地化也可以写在属性值里，包括 label、placeholder、title 以及 WebUIX 组件属性。

<input placeholder="{{loc:login.name_placeholder|Player name}}" />
<my-card title="{{loc:item.sword|Sword}}"></my-card>

本地化面板流程

1. 在 WebUIX HTML / Embedded Document 中新增或修改 {{loc:key|fallback}}。
2. 在 Unreal Editor 的 Localization 面板中打开项目本地化目标，执行 Gather 收集文本。
3. 在同一个本地化面板中填写或导入目标语言翻译，然后执行 Compile 生成运行时资源。
4. 保存本地化面板生成/更新的资源即可；正常流程不需要手动编辑底层本地化文件。

运行时切换语言

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

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

打包检查清单

• 打包项目包含目标 culture，例如 en 或 zh-Hans。
• Localization 面板 Compile 生成的运行时本地化资源已保存并进入项目/插件内容。
• HTML fallback 可作为兜底文本，但正式文本应来自本地化资源。

支持的事件

使用示例

<button OnClick="StartGame">Start</button>
<input value="{{Model.SearchText}}" OnChange="OnSearchChanged(value)" />

Bridge Object

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

基本用法

<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-cell class="slot">#{{dragCell::DisplayIndex}}</drag-cell>
  <drag-item id="sword" col="0" row="0" cols="2" rows="2">2x2</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">Drag Panel</handle>
</div>

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

拖拽状态 CSS

drag-cell.slot:hot { background: #38bdf833; }
drag-item.item:dragging { opacity: .72; transform: scale(1.04); }

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)" />

Project Settings 与自动检测

手柄输入系统受 Project Settings 中的 bEnableWebUIXGamepadInputSystem 总开关控制（默认开启）；bAutoSwitchInputModeByDevice（默认开启）让插件根据最近一次输入事件的设备类型（键鼠/触控/手柄）自动切换当前输入模式，无需手动调用 Enter Gamepad Input Mode / Enter Mouse & Keyboard Input Mode。方向导航按键（上下左右）默认映射到手柄 D-Pad，二维导航摇杆默认使用左摇杆。

[/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

手柄模式下会显示一个由摇杆驱动的虚拟光标，行为与鼠标光标一致（可以点击、拖拽、悬停触发 CSS :hover）。UWebUIXGamepadCursorLibrary 蓝图函数库提供获取/覆盖当前输入设备、获取/覆盖导航配置，以及分别为键鼠光标和手柄光标设置独立外观（内置样式或自定义贴图+热点）的静态函数，具体函数签名见下方 Blueprint API 参考。

全局按键监听事件

OnAnyKeyDown / OnAnyKeyUp 是声明在 UWebUIXElementExtension（进而被 WebUIX User Widget / Widget 继承）上的被动监听委托，键盘、鼠标和手柄输入都会触发，且不会消费事件（不影响 HTML 元素自身的正常事件处理），常用来做全局按键提示/重映射 UI。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 属性

在 HTML 元素上添加 nav-order 属性可以显式声明该元素在方向键/摇杆 UI 导航中的顺序，插件会按 nav-order 数值升序在可聚焦元素之间移动焦点。

<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

一个可选的页面栈管理工具（纯 UObject，非 Widget），提供 PushWidget / PopWidget / ClearWidgets / GetActiveWidget / NumWidgets，用于管理多层全屏页面（如主菜单→设置→图形选项）的入栈/出栈与激活/挂起状态，只有栈顶页面会参与手柄回退焦点（Activate）。因为是普通 UObject，需要用 UPROPERTY 持有它以防止被垃圾回收。

图标包格式

每个 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 字形在图集阶段直接光栅化写入真彩色 BGRA 像素，渲染时不会被当作“仅透明度”的普通文字字形处理，因此不受 CSS 文字颜色（color 属性）影响，能保留图标本身的原始配色。

使用方式

// 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 底层字符流（中文输入不要只依赖它）。