> 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-game-ui-kit.md).

# UIDoc 游戏 UI 套件

***

Game UI 套件是美术团队手绘的 UI 组件集（`$AO/ui/kit/Game UI/**`）：模态框、按钮、选项卡、进度条、横幅、舷窗、物品槽、复选框和切换开关。引擎附带匹配的样式表，因此任何 UIDoc 资源都可以直接采用该套件外观，而无需复制 CSS。

**将套件作为最后的样式调整步骤应用。** 先搭建界面——布局、绑定、事件、视口行为——确认它能正常工作，然后再进行皮肤化。套件样式只是涂装和内边距；它绝不能用来修复布局。

## 启用套件

在资源的 `index.css`:

```css
@import "game-ui-kit";
```

在烘焙时，引擎会将 `res/ui/kit/kit.css` 替换为该导入，因此请把 import 放在最前面，并把你自己的规则写在下面——在级联冲突中，你的规则会获胜。该导入可与 Tailwind 工具类组合。编辑引擎样式表后，会在下一次构建时重新烘焙导入它的资源；UIDoc 在运行中的游戏里仍然不会热重载。

## 唯一需要掌握的模式

UIDoc 不支持位图 CSS 背景，因此套件素材通过普通的 `img` 元素引入。每个套件容器都是一个定位元素，它的第一个子元素是 `.kit-bg` 图像；div 负责形状和布局，图像只负责绘制，通过随套件提供的资源设置进行九宫切片：

```html
<div class="kit-modal">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_grey1.png">
  <!-- 内容 -->
</div>
```

`.kit-bg` 是 `object-fit: fill` 用于九宫切片素材（模态框、按钮、选项卡、进度条、横幅）。固定纵横比素材（复选框、切换开关、舷窗、槽位图标）使用 `.kit-bg--contain` 以及容器自身的宽/高。

在以下情况使用 `.kit-bg--shadow` 作为实际底图 `img` ，当素材需要投下阴影时。它使用支持 alpha 的 `drop-shadow(...)`，因此透明角和九宫切片后的绘制结果共同决定轮廓。 `box-shadow` 则会遵循容器矩形边框盒；而把 `drop-shadow(...)` 加在容器上还会把其文本和其他后代元素也包含进去。

将可见的按钮/选项卡文案放在素材之后的前景标签元素中。由容器直接拥有的原始文本可以绘制在其子图像下方：

```html
<button class="kit-btn kit-btn--green">
  <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_green1.png">
  <span class="kit-btn-label">开始</span>
</button>
```

套件会在视觉上将直接按钮标签下移 5px，以匹配素材。对于图标加价格这类复合前景，请把整个前景包在 `.kit-btn-content` 中，这样图标和文字会一起移动：

```html
<button class="kit-btn kit-btn--green">
  <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/shiny_buttons/button_large_green1.png">
  <span class="kit-btn-content price">
    <img src="coin.png">
    <span class="kit-btn-label">300</span>
  </span>
</button>
```

## 类参考

| 类                                                                                   | 在以下情况使用                                       |
| ----------------------------------------------------------------------------------- | --------------------------------------------- |
| `.kit-bg`, `.kit-bg--contain`, `.kit-bg--shadow`                                    | 素材底图、固定纵横比适配，以及支持 alpha 的图像阴影                 |
| `.kit-fg`                                                                           | 上方的通用前景层 `.kit-bg`                            |
| `.kit-modal`                                                                        | 带有套件内边距的定位 flex-column 面板                     |
| `.kit-modal-header`                                                                 | 居中的标题安全区，两侧各预留 72px                           |
| `.kit-modal-title`                                                                  | 居中的标题行；可与 `.kit-text-header`                  |
| `.kit-title-banner`                                                                 | `pointy_banner_*` 一起使用，作为模态标题后方的底图，且完全位于模态框内部 |
| `.kit-header-band`                                                                  | `modal_header_*` 横跨模态框已绘制顶部边缘的横条              |
| `.kit-dim`                                                                          | 模态框后方的全屏暗化层                                   |
| `.kit-btn`, `.kit-btn-label`, `.kit-btn-content`, `.kit-btn--<colour>`              | 按钮素材加上一个视觉下移的前景标签/组合，并带有与颜色匹配的描边              |
| `.kit-tab-row`, `.kit-tab`, `.kit-tab-label`, `.kit-tab--active`                    | 带有前景标签的胶囊式选项卡导航行                              |
| `.kit-progress`, `.kit-progress-fill`, `.kit-progress--N`, `.kit-progress--compact` | 轨道加绑定的填充；family 修饰符可对齐填充，compact 则选择 30px 尺寸  |
| `.kit-card`, `.kit-list-row`                                                        | 用于带素材底图的卡片和行的结构容器                             |
| `.kit-close`                                                                        | 位于模态框右上角、绝对定位的前景关闭控件                          |
| `.kit-slot`, `.kit-slot-icon`, `.kit-slot-qty`                                      | 带图标和数量的背包/商店方块                                |
| `.kit-porthole`                                                                     | 圆形边框；堆叠 `*_back.png` 在 `*_ring.png`           |
| `.kit-checkbox`, `.kit-toggle`                                                      | 固定纵横比状态控件                                     |
| `.kit-text-header/body/body-dark/info`                                              | 美术文档中四种获准使用的文本样式                              |

在标准逻辑视口下，文本尺寸遵循美术文档（65/55/45/40）；当某个界面需要不同缩放时，可在资源中覆盖。

## 组装规则

这些来自美术团队的 Game UI 文档和既定实践；类名编码了其中大部分，其余部分由标记模式覆盖。

* **标题**：白色、粗体、黑色描边、投影（`.kit-text-header`），可以直接设置在模态框上，或者设置在 `.kit-title-banner` 上（深色横幅底图，完全位于模态框内部——避免棕色的“黄色”尖角横幅），也可以设置在 `.kit-header-band` 上，只要配色搭配合适：亮色模态上的高饱和色条（如白底红字）效果很好；低饱和配低饱和（如灰底金色）则不行。不确定时，普通标题文字始终安全。
* **可关闭的模态标题栏**：保持 `.kit-close` 作为 `.kit-modal`的直接子元素， `.kit-modal-header`；其左右对称的 72px 侧边预留可让标题视觉居中，并避开关闭控件。模态框宽度应按所需标题/横幅宽度，加上左右两个 72px 预留，再加上面板的左、右内边距来预算。这会刻意让可关闭模态框比紧凑贴合的正文内容略宽一些。
* **素材阴影**: `box-shadow` 遵循矩形边框盒。对于不规则或九宫切片的套件素材，请将 `.kit-bg--shadow` 作为实际底图 `img` 这样阴影就会跟随其绘制出的 alpha 轮廓。不要把滤镜加在 `.kit-modal`上，因为那样会把模态框的文本和子素材也算进阴影轮廓里。
* **按钮**：文本为白色，并带有 **颜色描边** ，以补足按钮素材——绝不能用黑色。将普通标签直接放入 `.kit-btn-label` 中，这样它会绘制在素材之上，并获得套件 5px 的视觉基线下移。对于图标加文字的内容，请把两者都放在一个直接的 `.kit-btn-content` 子元素中，让这对元素一起获得该偏移。使用 `shiny_buttons` 用于购买和特殊交互， `basic_buttons` 用于其他所有情况，并为文字留足内边距。灰色按钮表示禁用状态。
* **正文文本**：在有颜色的模态框上使用细微的 20% 不透明描边（`.kit-text-body`）；在白色/灰色模态框上使用纯深色文本（`.kit-text-body-dark`）。
* **选项卡**：一个胶囊式行 *位于* 模态框主体内部，而不是贴着顶部边缘。将文案放在 `.kit-tab-label`中。当前激活的选项卡使用有颜色的素材变体（例如 `tabs_blue`）并配以匹配的文字描边；未激活选项卡使用 `tabs_black`。对动态标签使用 `tab_med.png` 或 `tab_large.png` 。 `tab_small.png` 源文件不一致，而且其中一些包含已烘焙的标签，所以它们有意不做九宫切片。
* **进度条**：每个 `progress_bar_N` 文件夹都会配对一个 `backing.png` 以及一个专门制作的 `fill_*.png`，但内部偏移会因系列而异，而且由于下边缘/投影，往往是不对称的。轨道素材放在 `.kit-bg`中；匹配的系列填充放在 `.kit-progress-fill`中，它使用 `object-fit: fill`；向容器添加匹配的 `.kit-progress--N` 修饰符，并绑定 `data-style-image-fill-amount`。不要用着色的图标或装饰性的透明图像替代：着色会保留源 alpha，而 `cover` 可能会把方形素材裁切到缝隙中，或者在较窄的轨道上裁成对角楔形。请在 `0`, `0.25`, `0.5`，以及 `1`处预览该条；当前诊断无法检测不适合的纹理 alpha。默认组件厚度为 40px；为按比例缩放的 30px 形式添加 `.kit-progress--compact` 。对于自定义厚度，请在容器上设置相等的 `font-size` 和 `height` 值，这样基于 em 的系列内边距也会随之缩放。套件轨道使用 `flex-shrink: 0`；应显式选择厚度，而不要依赖 flex 父容器压缩轨道，因为那样轨道及其填充可能会以不同尺寸解析。
* **物品槽**：有颜色的方块（`inv_square_<colour>1.png`）用于已填充槽位； `inv_square_empty2.png` 是设计好的空状态。
* **模态框系列素材共享同一缩放比例** （源像素中角为 37px、轮廓为 6px——随附的切片内边距已经考虑了这一点）。诸如模态框上方的标题横条这类需要组合的部件之所以能对齐，是因为它们按同一缩放绘制；不要手动编辑各个切片值。

## 示例：设置模态框

条纹模态框（`modal_stripe_*`）带有更深色的底部横带——将操作行作为最后一个普通流子元素放在其上。

```html
<div class="kit-modal settings">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_stripe_blue1.png">
  <div class="kit-modal-header">
    <div class="kit-modal-title kit-text-header">设置</div>
  </div>
  <button class="kit-close" data-on-click="event:settings:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <div class="rows">
    <div class="row">
      <span class="kit-text-body">音乐</span>
      <button class="kit-toggle" data-on-click="event:toggle:music">
        <img class="kit-bg kit-bg--contain" data-if="music.on" src="$AO/ui/kit/Game UI/Additional Elements/Sliders + Toggles/switch_long_on.png">
        <img class="kit-bg kit-bg--contain" data-if="music.off" src="$AO/ui/kit/Game UI/Additional Elements/Sliders + Toggles/switch_long_off.png">
      </button>
    </div>
    <div class="row">
      <span class="kit-text-body">季票</span>
      <div class="kit-progress kit-progress--1 pass-progress">
        <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/backing.png">
        <img class="kit-progress-fill" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/fill_yellow.png"
             data-style-image-fill-amount="pass.progress">
      </div>
    </div>
  </div>
  <div class="actions">
    <button class="kit-btn kit-btn--yellow" data-on-click="event:settings:save">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_yellow1.png">
      <span class="kit-btn-label">保存</span>
    </button>
    <button class="kit-btn kit-btn--red" data-on-click="event:settings:reset">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_red1.png">
      <span class="kit-btn-label">重置</span>
    </button>
  </div>
</div>
```

```css
@import "game-ui-kit";

.settings { width: 620px; }
.settings .rows { display: flex; flex-direction: column; gap: 18px; margin-bottom: 26px; }
.settings .row { display: flex; align-items: center; justify-content: space-between; gap: 20px; }
.settings .pass-progress { width: 260px; }
.settings .actions { display: flex; gap: 16px; justify-content: center; }
```

```csl
UI.uidoc_bind_bool("music.on", player.music_enabled);
UI.uidoc_bind_bool("music.off", !player.music_enabled);
UI.uidoc_bind_float("pass.progress", clamp(player.pass_progress, 0.0, 1.0));
```

## 示例：确认对话框（战斗请求）

亮色模态框上的高饱和标题横条、深色正文文本，以及一对黄色/红色的接受/拒绝按钮。

```html
<div class="kit-modal battle">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_white1.png">
  <div class="kit-header-band">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_header_red1.png">
    <div class="kit-modal-header">
      <span class="kit-text-header band-title">战斗请求</span>
    </div>
  </div>
  <button class="kit-close" data-on-click="event:battle:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <div class="kit-porthole challenger">
    <img class="kit-bg kit-bg--contain" src="$AO/ui/kit/Game UI/Additional Elements/Circle Portholes/blue_back.png">
    <img class="kit-bg kit-bg--contain" src="$AO/ui/kit/Game UI/Additional Elements/Circle Portholes/gold_ring.png">
  </div>
  <span class="kit-text-body-dark message">{{challenger.name}} 向你发起战斗挑战！</span>
  <div class="actions">
    <button class="kit-btn kit-btn--yellow" data-on-click="event:battle:accept">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_yellow1.png">
      <span class="kit-btn-label">接受</span>
    </button>
    <button class="kit-btn kit-btn--red" data-on-click="event:battle:decline">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/basic_buttons/button_large_red1.png">
      <span class="kit-btn-label">拒绝</span>
    </button>
  </div>
</div>
```

```css
@import "game-ui-kit";

.battle { width: 680px; align-items: center; }
.battle .band-title { font-size: 55px; }
.battle .challenger { margin-bottom: 10px; }
.battle .message { text-align: center; margin-bottom: 24px; }
.battle .actions { display: flex; gap: 16px; }
```

## 示例：每日奖励

灰色模态框上的横幅标题、奖励槽位、连胜条，以及一个闪亮的领取按钮。

```html
<div class="kit-modal reward">
  <img class="kit-bg kit-bg--shadow" src="$AO/ui/kit/Game UI/Modals/Basic Modals/modal_simple_grey1.png">
  <div class="kit-modal-header">
    <div class="kit-title-banner">
      <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Horizontal Banners/pointy_banner_blue.png">
      <span class="kit-text-header banner-title">每日奖励</span>
    </div>
  </div>
  <button class="kit-close" data-on-click="event:reward:close">
    <img src="$AO/ui/kit/Icons/misc_icons_2/exit_button_small.png">
  </button>
  <span class="kit-text-body-dark streak">第 {{streak.day}} 天——继续保持！</span>
  <div class="slots">
    <div class="kit-slot" data-for="reward in rewards" data-for-key="reward.id">
      <img class="kit-bg kit-bg--contain" src="{{reward.back}}">
      <img class="kit-slot-icon" src="{{reward.icon}}">
      <span class="kit-slot-qty">{{reward.count}}</span>
    </div>
  </div>
  <div class="kit-progress kit-progress--1 streak-bar">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/backing.png">
    <img class="kit-progress-fill" src="$AO/ui/kit/Game UI/Additional Elements/Progress Bars/progress_bar_1/fill_yellow.png"
         data-style-image-fill-amount="streak.progress">
  </div>
  <button class="kit-btn kit-btn--yellow claim" data-on-click="event:reward:claim">
    <img class="kit-bg" src="$AO/ui/kit/Game UI/Buttons/shiny_buttons/button_large_yellow1.png">
    <span class="kit-btn-label">领取</span>
  </button>
</div>
```

```css
@import "game-ui-kit";

.reward { width: 600px; align-items: center; }
.reward .banner-title { font-size: 50px; }
.reward .streak { margin-bottom: 16px; }
.reward .slots { display: flex; gap: 12px; margin-bottom: 18px; }
.reward .streak-bar { width: 320px; margin-bottom: 22px; }
```

已填充槽位绑定 `reward.back` 到 `$AO/ui/kit/Game UI/Item Backs/inventory_squares_1/inv_square_blue1.png` （或其他颜色）；空槽位使用 `inv_square_empty2.png` 且不带图标。

## 素材覆盖范围

九宫切片内边距随附于 `res/ui/kit/Game UI/.asset_settings` ，适用于：基础模态框（simple、stripe、headers）、基础和闪亮按钮、中/大型模态框选项卡胶囊和梯形、水平进度条底图/填充（不包括分段精灵和固定纵横比的 bar 12）、水平尖角横幅，以及水平内部面板。固定纵横比部件——包括物品方块、复选框、滑块和切换开关、舷窗、辅助遮罩和高光——不需要切片。其他系列（卡片、对话气泡、华丽横幅、排名底图）虽然也在套件中，但尚未调整内边距——在切片前先测量，并让需要组合的部件保持在同一共享缩放比例下。