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 内完成。

页面配置

模板变量

<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。详见扩展元素章节。

快速创建

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

上下文变量 {{变量}}

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

支持的事件

使用示例

<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 属性。事件按名称路由到目标对象。

UMG 导航 (nav-order)

通过 nav-order 属性控制手柄/键盘导航顺序：

<button nav-order="10">First</button>
<button nav-order="20">Second</button>
<button nav-order="auto">Auto</button>
<div nav-order="none">Skipped</div>

基本用法

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

使用方式

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

预热模式

预计算内容

DOM 与元素查询

模板与数据绑定

HTML 可以使用模板表达式绑定蓝图或运行时数据，也可以通过事件属性调用同名 Blueprint 函数或事件。

元素材质 API

这些节点用于控制 HTML 元素上的材质。元素可以是使用材质作为 background-image 的 div，也可以是使用材质资源的 img。只要元素最终由 WebUIX 解析为材质资源，就可以通过同一套 API 获取和修改。

<div id="hud-minimap" style="background-image: url('/Game/UI/M_UI_Minimap.M_UI_Minimap');"></div>

Loading API

事件属性

CSS 属性速查

输入与 IME

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