> 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 支持的 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` 将每个已绘制文档报告为一个已布局节点树，其中包含解析后的文本、屏幕 `矩形`、点击处理器和键、列表的每行键、已提交的绑定，以及运行时能够证明的问题（未绑定的 `data-if`、从未提交过的列表）；被以下内容隐藏的分支： `data-if` 或 `display:none` 会折叠为一项。当“启动游戏”正在运行时，其默认作用域为活动客户端；若没有运行中的客户端，请显式传入 `scope: "editor"` 以检查编辑器运行时。每个运行时响应都会说明其 `领域`，因此编辑器领域的结果并不描述客户端。其 `矩形`, `client_ui_tree`、 `client_input` `click_at` 均使用以左下角为原点的引擎视口坐标；截图像素使用左上角原点。

该 `compile` 工具会预检当前所有 `.uidoc` 位于以下目录中的源目录： `res` ，随后才会编译脚本或允许启动游戏。预检失败会报告 `阶段`, `文件`, `行`、 `列`，以及完整的结构化诊断信息。 `uidoc_diagnostics` 会从编辑器领域中的当前项目文件报告创作结果；特定节点的警告包括 `index.html` `行` 和一个 `元素` 选择器。请使用单独的 `uidoc_runtime_inspect` 工具获取实时 DOM 详情。使用 `viewportMatrix: true`时，每个资源都会报告 `viewport_matrix.entries` （配置文件/缩放情形）； `失败的`, `警告`，以及分组的 `问题` 仅在发现问题时出现。它只审计声明，不审计裁剪、重叠或屏幕外边界。没有诊断信息的资源会统一列在 `clean`下。只有错误会导致配置文件失败；警告仍仅供参考。详细输出将错误配置文件置于 `failing_entries` 中，将仅有警告的配置文件置于 `warning_entries`中。紧凑的问题组仅报告 `profiles_affected`；在命名的视口/缩放条目有用时，设置 `viewportMatrixVerbose: true` 。即使不同源节点共享选择器或 CSS 源行，它们也不会被合并，因此共享规则问题仍可能显示为多个组；修复一次规则后重新运行诊断。

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

* `dynamic_text_intrinsic_layout` 表示频繁变化的文本可能改变内在尺寸框，并使缓存的布局失效。添加 `data-text-reserve` ，并使用最宽的、考虑本地化的示例，或为元素提供确定的宽度和高度。这不是重复文本或渲染错误。
* `image_aspect_drift` 表示图像的宽度和高度相互独立，并使用了 `object-fit: fill`。对于普通美术资源，请使用 `contain`, `cover`，或 `aspect-ratio` 。线性 `image-fill-direction` 填充不受此限制。

## 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-style-`, `data-on-`, `data-bind-`, `data-for-`, `data-scroll-`，或 `data-text-`，以及受支持名称的大小写变体，例如 `data-style-Color`，均为 `unknown_binding_attribute` 编译错误。其他 `data-*` 属性会产生警告：UIDoc 不运行脚本且没有属性选择器，因此它们没有任何效果。

不存在 `data-style-background-color`。对于依状态变化的背景，请为背景层子元素提供 `background-color: currentColor` ，并绑定该子元素的 `data-style-color`。在元素自身上， `data-style-color` 也会重新着色其文本。

绑定表达式属性包含直接表达式，例如 `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(...)`；通常应与由以下内容解析的稳定 ID 相同： `data-for-key`。因此，重复按钮可能在 `client_ui_tree` 中显示为：

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

`client_ui_tree` 返回以下方法接受的最短唯一选择器： `Test.click_button`，不包含可选的 `/__widget`，因此类似 `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/type 特异性，并以源顺序作为决胜规则。内联 `style` 最后应用。绘制顺序使用 `z-index`，然后是文档顺序。

交互伪状态规则内影响布局的声明属于编译错误。悬停按钮可安全地改变其颜色或不透明度，但不应改变其大小或周围布局。

复合选择器，例如 `.row.upper`, `#panel.open`、 `button.primary` 不受支持；请改为添加专用类。不支持的选择器会导致编译错误，其中包括同级组合器、属性选择器、伪元素、 `: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`、安全区域 `env(...)`，以及加法或减法 `calc(...)` ，最多八项。百分比 padding 和 margin 会被诊断并忽略。百分比和视口单位同样不适用于 gap，但尺寸、flex basis 以及单独的 `top`/`right`/`bottom`/`left` 偏移量支持它们。

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

CSS 关键字和数学表达式会按属性检查，而不是因为浏览器可能在某处接受它们就全局接受。特别是：

* `auto` 仅对列出它的属性行有效，例如尺寸、flex basis、偏移量， `align-self`，以及溢出。
* `无` 仅在列出的情况下有效，例如 `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` 层；盒阴影可以是内阴影。
* 一个 `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`.
* 文本 `outline-color` 和 `outline-width`.
* `object-fit: cover`, `contain`，或 `fill` 用于图像。
* `image-tint`, `image-grayscale`, `image-fill-amount`、 `image-fill-direction`.
* `translate`, `scale`，以及 `translate(...)`, `translateX(...)`, `translateY(...)`、 `scale(...)` 的 transform 子集。平移百分比相对于元素自身的边框盒进行解析；视口平移单位仍不受支持。

颜色支持常见的 CSS 形式，包括十六进制、 `rgb()`/`rgba()`, `hsl()`/`hsla()`、命名颜色、 `transparent`、 `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`.

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

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

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

transform 子集不包括旋转、倾斜、3D 变换或多标记 `scale` 值。一个 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。覆盖的区域包括 display、position、flex、sizing、spacing、inset、alignment、text、color、border、radius、overflow、pointer events、opacity、z-index、aspect ratio、shadows、transforms 以及任意图像效果属性。

降级步骤支持 `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 动画                              | 动画化 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 模拟保持确定性。