在 UMG 中显示页面¶

MarkupUIWidget 是承载 Markup UI 页面的 UMG 控件，可放入 Widget Blueprint，并与其他 UMG 控件组合。创建界面并将其添加到 Viewport 的完整步骤见第一个游戏界面。

UMarkupUIWidget¶

UMarkupUIWidget 继承自 UWidget，用于在 UMG 界面中显示 Markup UI 页面。

• 类型：类
• 父类：UWidget
• 头文件：UMG/MarkupUIWidget.h
• 包含方式：#include "UMG/MarkupUIWidget.h"

class UMarkupUIWidget final : public UWidget

继承关系：UObject → UVisual → UWidget → UMarkupUIWidget。

属性¶

可在 Widget Blueprint 的 Designer 中选中 MarkupUI Widget，在 Details → MarkupUI 中配置以下属性：

Document 选择导入后的 HTML 文档资产。控件创建并同步属性时会打开该文档；未选择文档时，控件不会自动显示页面。

事件¶

函数¶

以上列出控件自身定义的属性、事件和函数；继承成员仍可按 Unreal Engine 的方式使用。

控件尺寸¶

Desired Size 是控件向父容器提供的期望尺寸，不保证最终尺寸。实际显示区域由父容器、布局规则及可用空间决定。

• 在 Canvas Panel 中，可通过锚点和偏移设置控件占用的区域。
• 在其他 UMG 容器中，可根据容器的填充、对齐和尺寸规则调整控件。
• 页面中的百分比和布局相对于控件的页面视口计算；改变控件尺寸后，应检查页面内容是否仍完整显示。

控件尺寸、DPI 和页面缩放的关系见 DPI 与缩放。

运行时打开和关闭页面¶

需要在游戏过程中切换页面时，可使用蓝图节点操作已有的 MarkupUI Widget：

例如，在 Widget Blueprint 的 Graph 中取得 MarkupUI Widget 的引用，调用 Open Document 并传入目标文档资产。处理完毕后，可以调用 Close Document。这些节点提供 Completed 和 Failed 引脚，用于处理操作结果。

HTML 文档资产的资源路径根据资产在资产目录中的位置解析；根路径 / 从全局配置的资产目录开始查找。详细规则见工作目录。

切换与重新加载¶

在同一个 MarkupUI Widget 上调用 Open Document 并传入另一个文档资产，即可切换页面；传入当前文档资产则会重新加载页面。对于 HTML 字符串，使用当前内容和需要的 Document Uri 再次调用 Open Document (Html) 即可重新加载。

打开新页面时，控件会先关闭当前页面，无需先调用 Close Document。切换或重新加载会创建新页面；需要保留的数据应保存在数据上下文或其他游戏对象中，并在新页面就绪后重新获取需要操作的元素。

修改设计时目录中的文件后，先同步资产并保存，再重新加载页面。同步资产不会自动重新打开正在显示的页面。

Document Uri 地址格式¶

使用 Open Document (Html) 打开 HTML 字符串时，可通过 Document Uri 指定该字符串在资产目录中的虚拟 HTML 文档位置。加载 HTML 引用的 CSS、图片等资源时，相对路径以该文档所在目录为起点解析。地址使用以下格式：

markupui-asset:///相对于资产目录的页面路径

例如，Document Uri 设置为 markupui-asset:///pages/index.html，页面中的相对路径以 pages/ 为起点：

<link rel="stylesheet" href="../styles/main.css">

该引用指向资产目录中的 styles/main.css。虚拟文档位置仅用于确定资源路径的解析基址，无需在该位置实际创建 HTML 文档资产。

Document Uri 可以留空；此时使用默认的内存地址 memory:///widget.html，不会以资产目录作为相对路径的基址。需要引用资产目录中的资产时，应设置 markupui-asset:/// 地址。

数据与交互¶

每个控件承载自己的页面实例。页面需要游戏数据时，可在控件上设置默认或命名数据上下文；页面中的事件可以绑定到上下文提供的命令。具体操作见属性绑定和命令绑定。

页面显示后，还需要根据界面用途配置 Unreal Engine 的输入模式、鼠标光标和焦点。控件本身是否可见与是否能够接收输入是不同的设置；交互行为应在运行时验证。

常见问题¶

可在编辑器预览中检查文档资产和资源诊断。