基本概念¶
Markup UI 使用 HTML 文档描述界面结构，使用 CSS 设置布局与样式。页面引用的图片、字体等文件与文档一起构成界面资源，由平台插件加载并显示在引擎的界面控件中。
| 概念 | 含义 |
|---|---|
| HTML 文档 | 定义元素、文字及资源引用的页面源文件 |
| CSS 样式表 | 定义元素布局、尺寸、颜色和字体等样式的文件 |
| 资源 | 页面使用的样式表、图片、字体等文件 |
| 页面实例 | 文档加载后产生的运行时界面，具有当前显示和交互状态 |
| 数据上下文 | 提供给页面绑定使用的业务数据对象 |
| 平台插件 | 将页面资源、显示控件和输入操作接入引擎的集成组件 |
SDK 与平台插件¶
Markup UI SDK 提供 HTML / CSS 处理、布局、绘制、数据绑定与交互等共同能力。Unreal Engine 和 Unity 平台插件使用各平台的原生渲染系统，并接入引擎的编辑器、资产和界面系统。普通 App 可以基于 SDK 接入自定义渲染后端，例如 Skia，无需依赖游戏引擎。
图中的普通 App 分支表示基于 SDK 自行集成，不表示已经提供对应的应用框架插件。
HTML 文档与页面实例¶
HTML 文档是界面的内容定义。例如，一个玩家信息面板可以包含头像、角色名称、生命值和操作按钮。元素的排列与外观由 CSS 控制。
文档与页面实例是不同的对象：文档保存界面定义，页面实例保存加载后的界面状态。同一份文档可以用于创建多个页面实例；不应将引用同一文档理解为共享滚动位置、输入内容或焦点。
修改源文件后的资源更新
使用工程资产加载页面时，修改源文件后需要更新对应资产并重新加载页面。磁盘文件预览的更新方式以平台插件说明为准；源文件修改不代表运行中的页面会自动刷新。
CSS 样式表、图片和字体¶
页面通常由多个文件组成。以下为一个简单的设计时目录：
ui/
pages/
player.html
styles/
player.css
images/
avatar.png
fonts/
ui-font.ttf
在这个例子中，player.html 定义玩家面板的结构，player.css 设置样式，另外两个目录分别保存头像和字体。页面中的路径必须与实际资源位置一致。1
文档中的相对引用以文档所在目录为起点。例如，pages/player.html 引用样式表时可使用 ../styles/player.css。样式表内部的相对路径则以样式表所在目录为起点。
以 / 开头的路径表示全局配置的 资产目录。2 路径规则见资源路径。
设计文件与工程资产¶
设计文件是编辑器外维护的 HTML、CSS 和其他源文件；工程资产是通过平台插件导入或同步到引擎工程中的资源。
编辑器预览和游戏运行时使用各自配置的资源来源。
打包前确认资源已导入
源文件存在于磁盘上，不表示它已导入工程或包含在最终构建中。打包前应确认页面、样式表、图片和字体已进入平台插件的资源构建流程，否则可能出现页面或依赖资源加载失败。
页面尺寸与显示区域¶
引擎中的宿主控件为页面提供显示区域。HTML 元素在该区域内按 CSS 布局，页面内容与显示区域的大小共同决定最终显示结果。
- 显示区域尺寸：控件可用于显示页面的宽度和高度。
- 元素尺寸：由 CSS 及布局结果确定的元素大小。
- DPI 与缩放：影响逻辑尺寸与实际屏幕像素之间的对应关系。
调整控件大小不等于修改所有元素的固定尺寸。需要适应不同窗口或分辨率时，应结合页面布局和宿主控件设置进行检查。详细说明见布局与尺寸及 DPI 与缩放。
数据上下文与交互¶
静态页面可直接显示 HTML 中的文字和图片。需要显示角色名称、生命值或物品列表等运行时数据时，可以通过数据上下文向页面提供业务对象，再使用数据绑定将对象属性关联到文本、元素属性或样式。
数据绑定还涉及更新通知：业务数据修改后，应使用平台提供的通知方式更新界面，不能仅凭一次属性赋值就假设页面一定会刷新。
事件用于表示点击、输入等交互；命令用于调用业务操作。例如，按钮的点击事件可以关联“选择物品”命令，并传递当前物品作为参数。
平台接入¶
HTML、CSS 和资源路径描述页面本身；平台插件负责将页面接入引擎的资产管理、界面控件和输入系统。
平台功能支持范围
数据绑定、可用事件、输入回写和编辑器功能的支持范围以各平台说明为准。公共章节中的概念与语法不代表所有能力均已在 UE 和 Unity 中接入。