> For the complete documentation index, see [llms.txt](https://docs.allout.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.allout.game/all-out-docs/docs-zh/ui/uidoc-html-css-support.md).

# UIDoc 的 HTML 和 CSS 支持

***

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

要获得可工作的首屏，请从以下内容开始 [UIDoc 快速入门](/all-out-docs/docs-zh/ui/uidoc-quick-start.md).

生成的仓库参考文档 `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`。不支持的媒体块会被丢弃，并给出诊断信息。

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

```css
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 模拟也能保持确定性。