UIDoc 的 HTML 和 CSS 支持

UIDoc 支持的 HTML、CSS、响应式布局、交互、滚动和绑定功能，以及它省略的重要浏览器特性。

---

UIDoc 故意实现了一个适用于游戏 UI 的实用浏览器式子集。它会提前编译资源，并通过引擎渲染；它不会运行浏览器、JavaScript 或实时 DOM。

要获得可工作的首屏，请从以下内容开始 UIDoc 快速入门.

生成的仓库参考文档 docs/uidoc_supported_css.md，是完整的属性/值列表。它由 UIDoc::debug_supported_css_reference() 输出，并由 UIDoc 测试检查。本页从创作层面说明这一约定。

未知声明、被拒绝的值、不受支持的选择器、格式错误的 HTML，以及不受支持的媒体查询，都会被视为编译错误。解析器可能继续收集诊断信息，但在错误修复前该资源无效。不受支持的 CSS 块级 at-rule 会被静默跳过；不要依赖浏览器 at-rule 的行为。

运行中的游戏不会热重载 UIDoc 的 HTML 和 CSS。资源变更后请重启游戏。用于运行时调试， uidoc_runtime_inspect 可暴露实时 DOM 节点、当前绑定、计算后的样式、事件处理器/键值载荷以及矩形。其 screen_rect, client_ui_tree，以及 client_click 都使用以左下角为原点的引擎视口坐标；截图像素使用左上角原点。

以下 compile 工具在资源预处理失败时会内联包含结构化 UIDoc 诊断信息。 uidoc_diagnostics 在 viewportMatrix: true 会返回汇总通过次数，并将同一配置文件中同一源节点的相同问题类别分组。 unique_issue_count 是该分组后的节点/类别计数； issue_occurrence_count 是跨所有视口/缩放条目的原始总数。仅当每个失败条目都很有用时，才设置 viewportMatrixVerbose: true 只有在每个失败条目都值得关注时才这样做。即使不同源节点共享选择器或 CSS 源行，它们也不会被合并，因此共享规则问题仍可能显示为多个组；修正一次规则后重新运行诊断。

有两类常见的创作警告需要结合上下文理解：

• dynamic_text_intrinsic_layout 表示频繁变化的文本可能改变固有尺寸盒并使缓存布局失效。添加 data-text-reserve 使用预期最宽、考虑本地化的样本文本，或者给元素一个明确的宽度和高度。这不是重复文本或渲染错误。
• image_aspect_drift 表示某个图像的宽度和高度彼此独立，并且使用 object-fit: fill。请使用 contain, cover，或 aspect-ratio 用于普通美术资源。专门制作、故意拉伸以填充轨道的进度条填充是一个有效例外；请视觉检查该情况。

HTML 和 UIDoc 属性

元素名称会被接受为通用布局节点。这些元素在运行时具有专门行为：

元素	行为
span	行内文本内容
img	从以下位置加载的引擎资源图像 src
button	指针交互和点击事件
input	使用以下方式绑定的可编辑文本 data-bind-value

非空文本内容会创建文本节点。请使用 {{name}} 用于顶层文本绑定，以及 {{item.name}} 在重复列表中使用。图像 src 值也支持这种插值。类名和 data-key 值是静态的。

属性	用途
id, class, style	CSS 匹配和行内样式
src, width, height	图像来源和尺寸
value, placeholder, disabled	输入和控件状态
data-if="binding"	当顶层布尔绑定为 true 时包含一个子树；可选地 ! 对其取反
data-for="item in items"	为受 CSL 绑定的列表重复一个子树
data-for-key="item.id"	解析重复点击的 event.key ，来自一个直接表达式
data-key="role"	为节点赋予静态的交互/输入角色
data-bind-value="name"	将输入连接到 UIDoc 文本值
data-text-reserve="00:00"	在绘制实时绑定文本时，测量一个稳定的字面样本
data-on-click="event:name"	将点击事件发送给 CSL 回调； event.handler 接收完整的精确值，包括 event:
data-style-transform-x/y	绑定数值位移而不重新布局
data-style-transform-scale	绑定数值视觉缩放
data-style-opacity	绑定数值不透明度
data-style-color	绑定受支持的 CSS 颜色字符串，而不改变结构
data-style-image-fill-amount	绑定图像填充量
data-scroll-zoom	在可滚动视口上绑定完整内容缩放

绑定表达式属性包含直接表达式，例如 data-for-key="item.id", data-style-opacity="item.opacity"，以及 data-scroll-zoom="zoom"。不要将这些表达式放在 {{...}}中。Mustache 插值仅限于文本和图像 src 值。

data-if 比其他列表感知绑定属性更受限：它查找顶层布尔值，不会解析诸如 item.visible这样的重复别名。对于重复子树中的非交互视觉状态，请绑定 item.opacity 或 item.color。不透明度不会禁用命中测试，因此在构建 CSL 列表时应过滤结构性或交互性行，而不是留一个不可见按钮在原处。

重复控件身份与测试

data-for-key 决定重复点击的 event.key。运行时控件身份是独立的：它以静态的 data-key （然后是 HTML id，再到匿名标签回退）开头，并附加 #key:index 到每个外层循环。这里 key 是传给 UI.uidoc_list_item(...)；通常它应与由 data-for-key解析出的相同稳定 ID 一致。因此，重复按钮可能会在 client_ui_tree 中显示为：

UI/board.uidoc:seed-cell#seed-42:7/__widget

使用 client_ui_tree 来复制精确的实时身份。 Test.click_button 接受完整名称或后缀，并将最后的 /__widget 视为可选，因此 Test.click_button("seed-cell#seed-42:7") 当后缀唯一时会选中该实例。仅按角色查询可能会选择任意一个最近的重复实例。嵌套列表会附加多个 #key:index 对。处理器字符串和可见标签不是身份选择器。

原始 style 和 script 块在 HTML 中属于编译错误。请将编写的 CSS 放在 index.css中；这里没有 JavaScript 运行时。

CSS 选择器与层叠

支持的选择器包括：

• 元素名称、 .class, #id，以及 *.
• 后代选择器和直接子代（>）组合符。
• 用逗号分隔的选择器列表。
• :hover, :focus, :active, :pressed, :mouse-down, :dragging, :scroll-state，以及 :disabled.

UIDoc 使用正常的 id/class/类型特异性，并以源顺序作为平局决胜。行内 style 会最后应用。绘制顺序使用 z-index，然后是文档顺序。

交互伪状态规则中的会影响布局的声明会被忽略并给出诊断。悬停按钮可以安全地改变其颜色或不透明度，但不应改变其大小或周围布局。

不受支持的选择器形式包括兄弟组合符、属性选择器、伪元素、 :not(), :nth-*, :is(), :where()，以及 :has().

CSS 布局

UIDoc 支持 display: block, display: flex，以及 display: none。其他 display 值会被诊断并回退到 block。其布局属性包括：

• width, height, min-*, max-*, aspect-ratio，以及 box-sizing.
• margin, padding, gap, row-gap，以及 column-gap.
• flex, flex-direction, flex-wrap, flex-grow, flex-shrink，以及 flex-basis.
• align-items, align-self, align-content，以及 justify-content.
• position: static, relative, absolute，或 fixed，以及 inset, top, right, bottom，以及 left.
• overflow, overflow-x，以及 overflow-y 使用 visible, hidden, auto，或 scroll.

长度支持无单位像素的相关组合、 px, rem, em, %, vw, vh、safe-area env(...)，以及加法或减法的 calc(...) ，最多可包含八个项。百分比 padding 和 margin 会被诊断并忽略。百分比和视口单位对 gap 也无效，但它们受尺寸、flex basis 以及单独的 top/right/bottom/left 偏移量支持。

padding, margin，以及 inset 接受标准的一值、二值、三值和四值形式。百分比值在 inset 简写中不受支持；当需要百分比时请使用单独的偏移属性。

CSS 关键字和数学表达式按属性检查，不会因为浏览器在某处接受就全局接受。具体而言：

• auto 仅对列出它的属性行有效，例如尺寸、flex basis、偏移量、 align-self以及 overflow。
• none 仅在列出的位置有效，例如 display、受支持的绘制/滤镜重置、 pointer-events，以及 image-fill-direction.
• calc(...) 仅可用于文档中说明的长度字段。它允许最多八个简单长度项的加法和减法。乘法、除法、嵌套数学表达式、 min(), max()，以及 clamp() 均不受支持，并且百分比项需要一个确定的包含块。

如有疑问，请查看 docs/uidoc_supported_css.md中的确切属性行；另一个属性接受的值并不意味着同一标记在这里也有效。

文本、图像与绘制

支持的展示特性包括：

• color, background, background-color，以及一种线性、径向或圆锥 background-image 渐变。
• border, border-width, border-color，以及单一统一的 border-radius 值。诸如 border-bottom、按角设置的圆角以及百分比圆角均不受支持。仅需要单边时，请使用一个具有固定高度/宽度和背景色的显式子分隔线。
• 最多八个以逗号分隔的 box-shadow 或 text-shadow 层；box shadow 可以是 inset。
• 一种 filter: blur(...) 或 filter: drop-shadow(X Y [blur] [color])，以及 backdrop-filter: blur(...).
• opacity, z-index，以及 pointer-events.
• font-family, font-size, font-style, font-weight, line-height, letter-spacing, text-align, white-space, overflow-wrap，以及 word-break.
• Text outline-color 和 outline-width.
• object-fit: cover, contain，或 fill 用于图像。
• image-tint, image-grayscale, image-fill-amount，以及 image-fill-direction.
• translate, 缩放，以及 translate(...), translateX(...), translateY(...)，以及 scale(...) 变换子集。平移百分比会相对于元素自身的边框盒解析；视口平移单位仍不受支持。

颜色支持常见的 CSS 形式，包括十六进制、 rgb()/rgba(), hsl()/hsla()、命名颜色、 透明，以及 currentColor （如适用）。

渐变最多支持八个颜色停靠点、CSS 方向/角度和位置、 currentColor，以及 在 oklab 中 或 在 srgb 中；Oklab 为默认值。不支持多个背景层和 CSS 图像 URL。请使用一个 img 带有引擎资源路径的位图背景。

box-shadow 遵循元素的矩形边框盒。 filter: drop-shadow(X Y [blur] [color]) 遵循经过滤镜处理后的元素绘制出的 alpha，包括透明图像角。若省略颜色，则默认为元素的 currentColor。将其放在实际的 img 用于不规则或九宫格切片位图；放在容器上时，也会将容器中已绘制的后代包含在阴影轮廓中。

进度图像填充

对于连续进度条，请放置一个全尺寸的 img 在固定尺寸轨道内，绑定一个归一化的 0..1 值与 data-style-image-fill-amount，并设置 image-fill-direction: right 加上 object-fit: fill。使用矩形或渐变纹理，避免在进度条内部出现非预期的透明空隙。

不要将图标或其他装饰性透明图像重复用作填充。 image-tint 是乘法性的并保留源 alpha；它不会把透明像素变成不透明。 object-fit: cover 在轨道很窄时，还会强力裁剪方形图稿。综合这些选择，即使 UIDoc 的填充裁剪工作正常，也可能产生空白前导空间或对角楔形。

诊断当前不会检查纹理 alpha，也不会标记 object-fit: cover 进度填充上的。请在 0, 0.25, 0.5，以及 1处通过视觉检查进度条。Game UI kit 的配对 fill_*.png 资源是专为其对应底图打造的，并且 .kit-progress-fill 会应用预期的适配。

UIDoc 默认使用内置的 AllIn 字族，带有真实的 400、700 和 900 字重。 @font-face 可以通过资源 ID 声明项目的 TTF 或 OTF 字体资源。样式和字重会选择最近的已声明字形；缺失的粗体或倾斜可能会被合成。字体异步加载，因此 UIDoc 会先使用下一个字族或 AllIn，直到所请求的字形就绪，然后使文本布局失效。

省略 line-height 以使用随字号缩放的默认行高。显式 line-height: normal 不被接受。无单位值表示倍率；长度值表示固定的继承长度。

letter-spacing 会被继承，并接受 normal、无单位像素、 px, rem，或 em. normal 会解析为零。

变换子集不包括旋转、倾斜、3D 变换，或多标记 缩放 值。一个滤镜值包含一个 blur(...) 或一个 drop-shadow(...)；不支持滤镜链和其他滤镜函数。filter 和 backdrop-filter 合成器作用域最多可嵌套四层。

响应式样式和安全区域

支持媒体查询，但仅限以下明确条件白名单：

• (min-width: N) 和 (max-width: N).
• 组合的最小和最大宽度查询。
• Tailwind 风格 (width >= N) 和 (width <= N).
• (hover: hover).

宽度值接受无单位像素、 px，以及 rem。不支持的媒体块会被丢弃，并给出诊断信息。

在接受安全区域长度的地方使用这些值：

env(safe-area-inset-top)
env(safe-area-inset-right)
env(safe-area-inset-bottom)
env(safe-area-inset-left)

UIDoc 的顶部安全区域内边距也会预留游戏的顶部栏带。

滚动和缩放

overflow-x 和 overflow-y 彼此独立，因此一个视口可以水平、垂直或双轴滚动。双轴视口在拖动时会同时平移两个轴。启用垂直滚动时，鼠标滚轮会进行垂直滚动；仅水平的视口会将滚轮映射为水平滚动。

运行时当前会绘制垂直滚动条滑块。即使没有绘制水平滑块，仍可通过拖动访问水平内容。

data-scroll-zoom="zoomBinding" 会为交互式滚动视口添加类似浏览器的内容缩放。它会缩放后代几何、文本、图像、变换、命中测试和滚动范围，而视口及其同级元素保持固定。绑定发生变化时，引擎会保留视口中心周围的可视区域，并重新限制滚动位置。引擎安全范围为 0.05 到 20；应用通常应使用更窄的范围。

Tailwind 风格类

UIDoc 资源可以使用受支持的 Tailwind 风格实用类。实用类会在资源处理期间解析并降级为 UIDoc CSS；游戏中并不会运行 Tailwind。涵盖的领域包括 display、position、flex、尺寸、间距、inset、对齐、文本、颜色、边框、圆角、溢出、指针事件、不透明度、z-index、宽高比、阴影、变换以及任意图像效果属性。

降级步骤支持 hover:, focus:, active:, disabled:，响应式 sm:/md:/lg:/xl:/2xl:，以及诸如 w-[320px]，以及 CSS @apply。不包含 Tailwind preflight/base reset。UIDoc 无法表示的输出会导致资源烘焙失败。

不支持的主要浏览器特性

浏览器特性	UIDoc 方案
JavaScript 和 DOM API	使用 CSL 绑定驱动状态， data-if, data-for以及事件回调。
CSS Grid	使用 flexbox、块布局或显式定位。
CSS 变量和自定义属性	从 CSL 绑定值，或使用普通共享类。
过渡、关键帧和 CSS 动画	对 opacity、translation、scale 或 scroll zoom 等 CSL 绑定进行动画。
伪元素和高级选择器	向文档添加显式元素和类。
容器查询和大多数媒体特性	使用受支持的视口宽度和 hover 查询。
CSS URL 背景和多个背景层	使用受支持的渐变或一个 img 引擎资源。
按角圆角和多于八个阴影	使用受支持的单圆角/八阴影限制，或显式嵌套元素。
min(), max()，以及 clamp() CSS 数学函数	将 width/height 与受支持的 min-* 和 max-* 属性结合。
旋转、倾斜、3D 变换、滤镜链以及其他滤镜函数	将视觉效果制作为资源，或使用受支持的 translate/scale/blur/drop-shadow 效果。
Web 表单、导航、fetch、iframe、canvas、SVG DOM、音频和视频	使用 CSL 和相应的引擎系统。
浏览器语义和可访问性行为	UIDoc 元素是游戏 UI 节点；HTML 标签名并不意味着浏览器行为。

UIDoc 的目标是让常见游戏 UI 易于编写，而不是复现每一项 HTML 和 CSS 特性。请将布局保持在此子集内，这样资源烘焙才会可预测，客户端/服务器 UI 模拟也能保持确定性。