将 HTML+CSS 转换为 Unity UGUI 工具
HtmlToUGUI：将 HTML+CSS 一键转换为 Unity UGUI 的编辑器利器
引言
在 Unity 项目开发中，UI 搭建一直是一个高沟通成本、高重复劳动的环节。设计师出图 → 开发者对着效果图手动摆放 RectTransform → 反复调整锚点和对齐 — 这个流程不仅耗时，还容易产生偏差。如果能把设计师熟悉的 HTML+CSS 直接"翻译"为 UGUI 层级，那该多好？
这就是HtmlToUGUI要做的事情。
它是一个 Unity Editor 工具包，能在编辑器中把 HTML + CSS 内容转化为标准的 UGUI Canvas 层级结构，输出为原生 GameObject 树，运行时零额外开销，无缝兼容 Unity 的输入系统、预制体、射线检测和导航。
核心功能
1. 完整的 CSS 引擎
HtmlToUGUI 自建了一个微型 CSS 解析器，能力远超简单的正则匹配：
- 选择器：标签名、ID (
#)、类名 (.)、属性选择器 ([attr=value]、^=、$=、*=等)、后代选择器、子代选择器 (>) - 伪类：
:hover、:active、:disabled、:selected、:focus— 自动映射到 UGUI 的Selectable.ColorBlock - CSS 变量：
var(--my-color)完全支持，含回退值 - 相对单位：
em、rem、%完整支持 calc()表达式求值：自实现了含括号递归和四则运算的表达式解析器
/* 这些 CSS 都能被正确解析并映射到 UGUI */.button{--btn-color:#3498db;background:var(--btn-color);font-size:1.2rem;width:calc(100% - 20px);}.button:hover{background:#2980b9;}2. 三种布局计算器
这是 HtmlToUGUI 的核心创新点，解决了"CSS 绝对定位如何映射到 UGUI 锚点系统"这一难题：
| 计算器 | 行为 |
|---|---|
| 智能布局（默认） | 分析元素位置和尺寸，自动选择拉伸锚点 / 居中锚点 / 单侧锚点，可调节灵敏度阈值 |
| 全拉伸 | 元素包围盒直接转化为百分比锚点 min/max，最接近 CSS 语义 |
| 居中 | 所有元素置于父容器中心，使用(0.5, 0.5)锚点 |
用户可以在转换窗口或Hierarchy右键布局菜单中实时切换并看到效果差异。
3. 可插拔标签处理器系统
内置覆盖了常用 HTML 标签的处理逻辑：
| 处理器 | 支持的标签 | 生成的 UGUI 组件 |
|---|---|---|
ContainerTagHandler | div, span, p, a, section, label | Image + RectTransform |
InteractiveTagHandler | button, img, select | Button + Image / Dropdown |
InputTagHandler | input, textarea | InputField / Toggle / Slider / Button（根据 type 自动分派） |
ProgressTagHandler | progress, meter | Slider （非交互） |
HeadingTagHandler | h1~h6 | 容器 + 自动注入字号和粗体 |
InlineStyleTagHandler | b, strong, i, em, u, s, small | 容器 + 自动注入对应文字样式 |
关键设计：用户只需在自定义程序集中实现ITagHandler接口，并让程序集引用Xxhq.Htmltougui，标签处理器就会被自动发现并注册。
// 自定义标签处理器示例：支持 <card> 标签publicclassCardTagHandler:ITagHandler{publicIReadOnlyList<string>SupportedTags=>new[]{"card"};publicGameObjectCreateElement(HtmlNodenode,Dictionary<string,string>styles,Transformparent,IElementFactoryfactory){// 创建带有阴影效果的容器卡片returnfactory.CreateContainer(node,styles,parent);}}4. 文件监视与自动转换
启用后，Html 源文件一旦被外部编辑器修改保存，Unity 就会自动重新执行转换 — 形成"修改 CSS → 保存 → UGUI 自动更新"的实时迭代闭环。
5. 预制体模板系统
通过UiPrefabSettingsScriptableObject，可以为不同组件类型指定自定义预制体：
Create → Html To UGUI→ UiPrefabSettings这样转换出来的 Button / InputField / ScrollView 可以复用项目已有的 UI 设计规范预制体。
快速上手
安装
在 Unity Package Manager 中通过 Git URL 安装：
https://github.com/jixinhaoqi/HtmlToUGUI.git或（速度更快）
https://gitee.com/jixinhaoqi/HtmlToUGUI.git前提条件：Unity 2019.4.26f1+，自动依赖 TextMeshPro 和 2D Sprite。
基础用法
第 1 步：打开转换窗口
Tools → HTML to UGUI Converter第 2 步：准备 HTML 内容
HtmlToUGUI 要求 HTML 中的每个元素都带有绝对定位信息（data-u-left、data-u-top、data-u-width、data-u-height）。有两种方式获得这种格式的 HTML：
方式 A（推荐）：使用内置的"HTML 解构工具" — 在浏览器中打开
Tools/HTMLTools/HTML解构工具.html，粘贴普通 HTML，点击"解构 HTML"，得到带定位属性的输出方式 B：让 AI 直接生成 — 将
Tools/HTMLTools/AI生成HTML提示词/SKILL_动态定位.md的内容作为 System Prompt 发给 ChatGPT/Claude 等，AI 会自动生成带有定位信息的 HTML
| → | ||
| → |
<!-- 一个最小工作示例 --><body><divdata-u-name="container"data-u-left="0"data-u-top="0"data-u-width="1920"data-u-height="1080"style="background:#f0f0f0;"><divdata-u-name="title"data-u-left="660"data-u-top="200"data-u-width="600"data-u-height="80"style="font-size:48px;font-weight:bold;text-align:center;">欢迎使用 HtmlToUGUI</div><divdata-u-name="btn"data-u-left="810"data-u-top="400"data-u-width="300"data-u-height="60"class="button"style="background:#3498db;color:white;border-radius:8px;text-align:center;">开始转换</div></div></body>转换后，场景中会出现一个Canvas/HTML_Content的完整 UGUI 层级树。
SpriteAtlas 工具集
除了核心的 HTML 转换功能，包还提供了一套实用的 SpriteAtlas 处理工具，通过 Project 窗口右键菜单访问：
Assets → Html To UGUI→ 2D| 菜单项 | 功能 |
|---|---|
| SpriteAtlas → TMP_SpriteAsset | 将图集导出为 TextMeshPro 可用图标字体资产 |
| SpriteAtlas → Sprite(Multiple) | 导出为 Multiple 模式精灵表 |
| SpriteAtlas → TextureSheet | 所有精灵网格排列为单张纹理 |
| Sprite(Multiple) → Sprites | 拆分 Multiple 精灵图为独立碎图 |
选中的图标集一键转成 TMP_SpriteAsset，然后在 TextMeshPro 文本中通过<sprite>标签引用，非常方便。
架构设计亮点
从软件工程角度看，这个包有几个值得称道的设计决策：
1. Runtime / Editor 分离
CSS 解析器、布局计算器、样式应用器等核心逻辑放在 Runtime 程序集（Xxhq.Htmltougui），GameObject 创建、资源加载等放在 Editor 程序集（Xxhq.Htmltougui.Editor）。这样一方面确保了构建时不会将编辑器代码打入包体，另一方面 CSS 引擎理论上可在运行时复用。
2. 反射驱动的自动发现
AssemblyHelper.CreateSupTypeInstances<T>()会扫描指定程序集中所有ITagHandler和LayoutCalculator的子类，自动排除抽象类和基类，用户只需写实现并确保程序集被扫描到即可 — 零配置。
3. 层次分明的样式解析管线
<style> 标签 → CSS 规则列表 → 选择器匹配 → 特异性排序 → 继承合并 → 行内样式覆盖 → em 后处理 → 最终样式字典这条管线每一步都有清晰的输入输出边界，易于理解和调试。
限制与注意事项
开发者在选择 HtmlToUGUI 时，需要了解它的一些边界：
- 仅编辑期：不支持运行时动态加载 HTML 并渲染。它是纯 Editor 工具，产物是静态 UGUI 层级
- HTML 必须预处理：不能拿任意 HTML 直接丢进去，必须带有
data-u-*定位属性（通过解构工具或 AI 提示词生成） - 不支持 Flexbox/Grid：布局模型仅限于绝对定位和相对定位
- 不支持 HTML游离的文本：如
<div>游离的文本<div></div></div> border-radius尚未渲染：边框通过Outline组件实现简单的直角边框<a>标签链接事件未接入：需要手动挂载点击处理- 图片资源必须位于 Assets/ 或 Packages/ 目录
总结
HtmlToUGUI 是一个设计精巧的专用工具：它没有试图成为一个"Unity 里的浏览器"，而是选择了一条务实的路线 — 利用 HTML+CSS 作为 UI 的声明式描述语言，在编辑期将其编译为原生 UGUI 层级，从而实现"零运行时成本 + 可版本控制 + 可预制体化"的目标。对于需要频繁对接设计稿、或希望用前端技术栈参与 Unity UI 开发的团队而言，这是一个值得了解的工具。
欢迎在 GitHub 上给项目点个 Star，也欢迎提 Issue 和 PR！
项目地址：https://github.com/jixinhaoqi/HtmlToUGUI
在线体验：https://jixinhaoqi.github.io/HtmlToUGUI/
作者：xxhq
协议：MIT License