> 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_runtime_inspect` 会暴露实时 DOM 节点、当前绑定、计算后的样式、事件处理器/键负载以及矩形。Start Game 运行时，其默认作用域是活动客户端；如果没有运行中的客户端，请显式传入 `scope: "editor"` 以检查编辑器运行时。每个运行时响应都会声明其 `realm`，因此编辑器域的 `live_instance_count` 并不能描述客户端。其 `screen_rect`, `client_ui_tree`，以及 `client_click` 都使用引擎视口的左下原点坐标；截图像素使用左上原点。

在 `compile` 工具会对当前每个 `.uidoc` 源目录进行预检，位置在 `res` 下，然后才会编译脚本或允许 Start Game 启动。预检失败会报告 `阶段`, `文件`, `行`，以及 `列`，以及完整的结构化诊断信息。 `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 属性

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

| 元素       | 行为                                            |
| -------- | --------------------------------------------- |
| `行内文本内容` | 从 src 加载的引擎资源图片                               |
| `img`    | Engine asset image loaded from `src`          |
| `button` | 指针交互和点击事件                                     |
| `input`  | 通过 data-bind-value 绑定的可编辑文本 `data-bind-value` |

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

| 属性                                 | 用途                                       |
| ---------------------------------- | ---------------------------------------- |
| `id`, `class`, `style`             | CSS 匹配和行内样式                              |
| `src`, `width`, `height`           | 图片来源和尺寸                                  |
| `value`, `placeholder`, `disabled` | 输入与控件状态                                  |
| `data-if="binding"`                | 当顶层布尔绑定为真时包含一个子树；可选的 `!` 会将其取反           |
| `data-for="item in items"`         | 为一个 CSL 绑定列表重复一个子树                       |
| `解析重复点击的`                          | 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-style-opacity="item.opacity"`，以及 `data-scroll-zoom="zoom"`。不要把这些表达式放在 `{{...}}`。Mustache 插值仅限于文本和图片 `src` 值。

`data-if` 比其他支持列表的绑定属性范围更窄：它会查找顶层布尔值，并不会解析诸如 `item.visible`。对于重复子树中的非交互视觉状态，请绑定 `item.opacity` 或 `item.color`。不透明度不会禁用命中测试，所以在构建 CSL 列表时应过滤结构性或交互性行，而不是让一个不可见按钮留在原地。

### 重复控件身份与测试

`data-for-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`, `字间距`, `文本对齐`, `空白处理`, `溢出换行`，以及 `单词换行`.
* 文本 `轮廓颜色` 和 `轮廓宽度`.
* `object-fit: cover`, `contain`，或 `填充` 适用于图像。
* `图像色调`, `图像灰度`, `图像填充量`，以及 `image-fill-direction`.
* `平移`, `缩放`，以及 `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`。使用矩形或渐变纹理，避免在进度条内部出现意外的透明空隙。

不要将图标或其他装饰性透明图像重复用作填充。 `图像色调` 是乘法运算，并保留源 alpha；它不会把透明像素变为不透明。 `object-fit: cover` 在轨道很窄时还会更激进地裁切方形图稿。两者结合，即使 UIDoc 的填充裁剪工作正常，也可能产生前导空白或对角楔形。

诊断目前不会检查纹理 alpha，也不会标记 `object-fit: cover` 进度填充中的问题。请在 `0`, `0.25`, `0.5`，以及 `1`处通过视觉检查进度条。 `fill_*.png` 资源是为其对应背景专门设计的，并且 `.kit-progress-fill` 会应用预期的适配方式。

UIDoc 默认使用内置 AllIn 字族，并具备真实的 400、700 和 900 字重。 `@font-face` 可以按资源 ID 声明项目 TTF 或 OTF 字体资源。样式和字重会选择最接近的已声明字形；缺失的加粗或倾斜可能会被合成。字体异步加载，因此在请求的字形就绪前，UIDoc 会使用下一个字族或 AllIn，然后在其就绪后使文本布局失效并重新计算。

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

`字间距` 会被继承，并接受 `normal`、无单位像素、 `px`, `rem`，或 `em`. `normal` 会解析为零。

变换子集不包括旋转、倾斜、3D 变换或多 token `缩放` 值。一个 filter 值包含一个 `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。覆盖范围包括显示、定位、flex、尺寸、间距、inset、对齐、文本、颜色、边框、圆角、溢出、指针事件、不透明度、z-index、宽高比、阴影、变换以及任意图像效果属性。

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

## 不支持的显著浏览器功能

| 浏览器功能                                       | UIDoc 方案                                                |
| ------------------------------------------- | ------------------------------------------------------- |
| JavaScript 和 DOM API                        | 通过 CSL 绑定驱动状态， `data-if`, `data-for`以及事件回调。             |
| CSS Grid                                    | 使用 flexbox、块级布局或显式定位。                                   |
| CSS 变量和自定义属性                                | 从 CSL 绑定值，或使用普通共享类。                                     |
| 过渡、关键帧和 CSS 动画                              | 为 opacity、translation、scale 或 scroll zoom 等 CSL 绑定制作动画。 |
| 伪元素和高级选择器                                   | 向文档中添加显式元素和类。                                           |
| 容器查询和大多数媒体特性                                | 使用受支持的 viewport-width 和 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 模拟保持确定性。