uxml-preview

English · 한국어 · 日本語 · 简体中文

无需 Unity 编辑器，即可在浏览器中渲染 Unity UI Toolkit 的 UXML/USS——由 UI Toolkit 自身使用的 Yoga 引擎负责布局，并与 Unity 实测结果进行了比对验证。

▶ 打开在线体验 (Playground)

粘贴你自己的 .uxml 和 .uss，或直接打开示例。所有内容都不会上传，完全在页面本地 运行。

验证方式

• 坐标·运行时主题（默认）： 在同样的 42 个布局用例中，1122 / 1148 个元素坐标值与真实的 Unity 6.3 运行时面板（6000.3.25f1，PanelSettings + UIDocument，Play 模式）完全一致。剩余差异均为编辑器主题同样存在的差异。测量方法 →
• 坐标·编辑器主题： 在包含三个完整界面（物品栏，以及使用全部 15 种已绘制控件的设置界面英文版和韩文版）在内的 42 个布局用例中，1122 / 1148 个元素坐标值与 Unity 6000.0.40f1 完全一致。查看全部差异明细 → 在 Unity 6.3（6000.3.25f1）中重新导出这批用例后，所有布局结果均与当天导出的 6000.0.40f1 结果一致。6.3 重新测量结果 →
• 文本，运行时主题（默认）： 在真实浏览器中绘制，并与真实的 Unity 运行时面板（6000.0.40f1 与 6000.3.25f1，每个探针单独启动一个 Unity 进程）逐个 Label 进行比对——行数 92 / 92、高度 84 / 92、宽度 92 / 92（误差在 1px 或 1% 以内），框边界处的换行用例 159 / 159。所有高度存在差异的用例，均是使用了不含韩文字符的拉丁字体 Inter 来排版韩文或混排文本；此时 Unity 会改用回退字体绘制，而本预览工具会针对该情况发出明确警告。运行时文本测试集 →
• 文本，编辑器主题： 同样的 92 个 Label 与 Unity 6000.3.25f1 编辑器比对——92 / 92、84 / 92、92 / 92，换行用例 157 / 159（其余 2 个：一个中文用例中编辑器的禁则处理，以及框边界处 1px 的自然宽度差）。文本测试集 →
• 测量条件： 坐标数值测量的是给定文字尺寸时的布局（测试工具用固定函数测量文字，文字测量由文本数值单独衡量）。文本数值是在向预览传入与 Unity 相同的字体文件的条件下测得的。若不传入字体，预览会用浏览器默认字体测量，文字宽度可能相差几个像素，多行文本的行数也可能不同。条件 →
• Unity 版本： 基准版本为 Unity 6.3 LTS。某项属性是否属于 USS，依据 Unity 官方属性表（截至 6.6）判定；6.7 在推出 LTS 版本之前暂不支持。支持范围 →
• 不一致之处会明确报告，绝不静默忽略。 遇到不支持的控件、属性或值时，工具会返回警告并说明原因；对于已实测的情况，还会一并告知 Unity 的实际处理方式。警告说明 →

三种使用方式

| 使用场景 | 推荐方案 | |---|---| | 设计界面 | 使用浏览器中的在线体验，或在项目文件旁使用 UXML Preview for VS Code | | 让 AI 智能体编写 UI | uxml-author —— 编写 UXML/USS、调用本库渲染并先验证结果再交付的技能（Skill） | | 构建工具 | 直接使用本库：npm install uxml-preview，详见 API 文档 |

安装

npm install uxml-preview

工具链需要 Node 22 或更高版本；渲染需要 DOM 环境（浏览器，或在测试中使用 happy-dom / jsdom）。

import { loadLayoutEngine, parse, render, serialize } from 'uxml-preview';

await loadLayoutEngine();                 // Yoga 基于 WebAssembly：预先加载一次即可

const doc = parse(uxmlText, ussText);     // 文本 → 模型
const view = render(doc, container, {     // 模型 → 画面
  size: { width: 1280, height: 720 },     // 面板尺寸，而非窗口尺寸
  resolveAsset: (path, form) => myAssetUrl(path, form),  // project://… → URL，不存在则返回 null
});

for (const w of view.warnings) console.log(w.reason ?? w.kind, w.message);

view.dispose();                           // Yoga 节点不会被垃圾回收，需手动释放
const { uxml, uss } = serialize(doc);     // 若未修改，输出与输入字节级完全一致

文档

• USS 不是 CSS（英文） — 导致迁移过来的样式表显示异常的各项差异，均附有示例
• 支持范围（英文） — 控件、属性、状态、版本，以及各项的验证程度
• 精度说明（英文） — 所有数据、测量方法及全部已知差异
• API（英文） — parse、render、serialize、钩子（Hooks）、警告、classifyVisibility
• 更新日志（英文）
• 视觉比对（韩文） — 将色彩与质感同 Unity 并排对比的单次记录（2026-08）

开发

pnpm install
pnpm dev            # 在本地启动在线体验页面（Playground）
pnpm test           # 无需浏览器或 Unity 即可运行的全部测试
pnpm test:text      # 文本测试集，在真实 Chromium 中运行（见 docs/accuracy.en.md）
pnpm build

复现 Unity 侧的基准数据需要安装 Unity，具体步骤见 精度说明。

许可证

Apache-2.0