> For the complete documentation index, see [llms.txt](https://docs.myarc.icu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.myarc.icu/cai-dan-pei-zhi/menus/frontend.md).

# 前端元素类型

`frontend` 用来定义菜单上所有看得见的视觉元素。你在 `frontend` 下写的每一个键名就是该元素的唯一 ID，里面通过 `type` 指定元素种类，再配合位置、尺寸和外观属性完成排版。点击与悬停等交互则写在对应的 `backend` 区域里。

## 所有元素通用的属性

无论哪种前端元素，都支持以下四个基础变换与显示属性：

| 属性         | 填写内容与说明                                                                       | 省略时的默认值              |
| ---------- | ----------------------------------------------------------------------------- | -------------------- |
| `offset`   | 包含 `x`、`y`、`z` 的对象，填有限数值，控制元素相对于画布中心（或父分组中心）的位置。                              | `{x: 0, y: 0, z: 0}` |
| `rotation` | 包含 `x`、`y`、`z` 的对象，单位为角度（度）。`z` 在菜单平面内旋转，`x` 和 `y` 让元素前后倾斜。                   | `{x: 0, y: 0, z: 0}` |
| `scale`    | 缩放倍数对象，填非零数值。平面元素填 `x`、`y`；三维的 `item` 和 `block` 还可以填 `z`。填负数可镜像翻转。            | 各轴均为 `1`             |
| `visible`  | 填 `true`（显示）或 `false`（隐藏）。注意不能把静态 `scale` 填为 `0` 来隐藏元素，隐藏请用 `visible: false`。 | `true`               |

## 文字（`text`）

用于在菜单上显示标题、按钮标签或包含占位符的动态数据：

```yaml
frontend:
  player-info:
    type: text
    content: '&f%player_name%'
    size: 5
    offset: {x: 0, y: 20, z: 1}
    update: 20
```

| 属性           | 填写内容与说明                                                                          | 省略时的默认值             |
| ------------ | -------------------------------------------------------------------------------- | ------------------- |
| `content`    | 必填字符串。支持颜色代码、渐变色、换行符 `\n` 以及 PlaceholderAPI 占位符。                                 | 必填                  |
| `size`       | 大于 `0` 的数值，控制字号大小。                                                               | `10`                |
| `font`       | 资源包中的字体 ID，格式为 `命名空间:路径`（全小写字母、数字、下划线、点、连字符或斜杠）。                                 | `minecraft:default` |
| `opacity`    | `0` 到 `255` 之间的整数，控制文字不透明度（`255` 为完全不透明）。                                        | `255`               |
| `line-width` | 大于 `0` 的整数，控制自动换行的宽度（单位为字体像素）。                                                   | `200`               |
| `alignment`  | 多行文本在段落内的对齐方式，可选 `left`、`center` 或 `right`。                                      | `center`            |
| `update`     | 占位符定时刷新间隔（单位：游戏刻 tick）。填正整数定时刷新（如 `20` 代表约每秒刷新一次），填 `-1` 则只在打开菜单时解析一次。注意不能填 `0`。 | `-1`                |

**关于文字定位与对齐的小提示**： `offset` 定位的始终是**整个文字块的中心点**，而 `alignment` 控制的是当文字有多行且长短不一时，各行在段落内部是左对齐、居中还是右对齐。如果文字只有一行，`left`、`center`、`right` 看起来会在同一个位置。需要把文字挪到左边或右边时，请直接调整 `offset.x`。

## 矩形、边框与线条（`rectangle` / `frame` / `line`）

这三种几何图形非常适合直接搭建干净的现代 UI 面板、按钮底色和分割线，不需要额外制作图片资源。

它们共用两个外观属性：

* `color`：引号包裹的 6 位十六进制颜色字符串，格式为 `'#RRGGBB'`，默认为 `'#FFFFFF'`（白色）。
* `opacity`：`0` 到 `255` 的整数，控制不透明度，默认为 `255`。

| 类型 (`type`) | 尺寸属性与填写要求                                                                                                    | 常见用途            |
| ----------- | ------------------------------------------------------------------------------------------------------------ | --------------- |
| `rectangle` | `width`（宽）、`height`（高），均填大于 `0` 的数值。                                                                         | 面板背景、卡片底板、按钮色块。 |
| `frame`     | `width`（外宽）、`height`（外高）、`thickness`（边框粗细，默认 `1`）。三项均需大于 `0`，且必须满足 **`2 * thickness < min(width, height)`**。 | 窗口描边、选中高亮框。     |
| `line`      | `width`（长度）、`thickness`（线条粗细）。两项均填大于 `0` 的数值。配合 `rotation: {z: 90}` 可变为竖线。                                   | 标题下划线、区域分隔线。    |

```yaml
frontend:
  panel:
    type: rectangle
    width: 140
    height: 80
    color: '#182031'
    opacity: 235
  panel-border:
    type: frame
    width: 140
    height: 80
    thickness: 1
    color: '#617DA0'
    offset: {z: 1}
  divider:
    type: line
    width: 100
    thickness: 1
    color: '#617DA0'
    offset: {y: 10, z: 1}
```

**边框粗细注意事项**： `frame` 是向内绘制的空心框，两边的粗细加起来不能把整个宽高填满。例如你想做一个宽度只有 `2` 的极窄边框，默认的 `thickness: 1` 会因为 `1 * 2 >= 2` 没有内部空隙而报错。此时只需把 `thickness` 调小（如 `0.5`）即可正常使用：

```yaml
frontend:
  narrow-border:
    type: frame
    width: 2
    height: 10
    thickness: 0.5
```

当面板（`z: 0`）和边框（`z: 1`）处于不同深度又希望边缘完全对齐时，记得在 `canvas` 中开启 `depth-mode: layered`（详见[画布、坐标与屏幕位置](/cai-dan-pei-zhi/menus/canvas.md)）。

## 图片（`image`）

你可以使用自定义 PNG 图片来装饰界面：

```yaml
frontend:
  logo:
    type: image
    source: /ui/logo.png
    width: 96
    height: 32
    offset: {z: 1}
```

| 属性        | 填写内容与说明                                                                                           | 省略时的默认值     |
| --------- | ------------------------------------------------------------------------------------------------- | ----------- |
| `source`  | 必填，PNG 图片路径（也可使用别名 `path`、`image` 或 `material`，四选一）。以 `/` 开头，对应 `plugins/ArcMenu/images/` 目录下的文件。 | 必填          |
| `width`   | 画布上的显示宽度（大于 `0` 的数值）。                                                                             | 原图像素宽度      |
| `height`  | 画布上的显示高度（大于 `0` 的数值）。                                                                             | 原图像素高度      |
| `opacity` | `0` 到 `255` 的整数，控制不透明度。                                                                           | `255`       |
| `color`   | 用 `'#RRGGBB'` 或 `'&#RRGGBB'` 给图片染色（适合给纯白图标换色）。                                                    | 不染色（保持原图色彩） |
| `update`  | 当路径中包含占位符时的定时刷新间隔（正整数 tick，或 `-1` 不刷新）。                                                           | `-1`        |

图片文件放在 `plugins/ArcMenu/images/` 下，文件夹和文件名全部使用小写字母、数字、下划线 `_`、点 `.` 或连字符 `-`。例如 `images/ui/logo.png` 在配置里写作 `/ui/logo.png`。

图片路径同样支持占位符动态切换，例如写 `source: /ranks/%player_rank%.png` 并配合 `update: 20`，就能根据玩家当前的段位实时更换图标。

## 动图（`gif`）

用于在界面上播放 GIF 动画：

```yaml
frontend:
  banner:
    type: gif
    source: /ui/banner.gif
    width: 160
    height: 40
    speed: 1
```

`gif` 支持 `image` 的全部属性（路径后缀为 `.gif`，存放在 `images/` 目录下），并额外提供一个 `speed` 属性：

* `speed`：填大于 `0` 的数值，控制每游戏刻（tick）推进的帧数，默认为 `1`。详细的拆帧与资源包工作流请参考 [GIF 动图](/gong-neng-pei-zhi/gif.md)。

## 物品（`item`）

展示原版物品、玩家头颅、自定义模型或第三方插件（CraftEngine、Nexo、ItemsAdder）的物品：

```yaml
frontend:
  sword:
    type: item
    material: minecraft:diamond_sword
    context: GUI
    scale: {x: 24, y: 24, z: 24}
    offset: {z: 2}
```

| 属性         | 填写内容与说明                                                                                                                                       | 省略时的默认值              |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| `material` | 必填字符串，指定物品材质、头颅标签或自定义物品 ID。                                                                                                                   | 必填                   |
| `context`  | 物品渲染视角，可选 `GUI`、`HEAD`、`FIXED`、`GROUND`、`NONE`、`FIRSTPERSON_LEFTHAND`、`FIRSTPERSON_RIGHTHAND`、`THIRDPERSON_LEFTHAND`、`THIRDPERSON_RIGHTHAND`。 | `GUI`                |
| `scale`    | 物品的大小由 `scale` 的 `x`、`y`、`z` 控制（默认各轴为 `1`）。制作常规图标时，通常把三个轴都设为 `16` 到 `32` 左右的值。                                                                | `{x: 1, y: 1, z: 1}` |

### `material` 支持的丰富写法

1. **原版物品**：忽略大小写，可以用下划线也可以直接用空格，例如 `minecraft:diamond_sword`、`diamond_sword` 或 `'Cyan Stained Glass Pane'`。
2. **玩家头颅与自定义纹理头颅**：
   * 指定玩家名或 UUID：`'<head:BlackSKY>'`
   * 当前打开菜单的玩家头像：`'<head:%player_name%>'`（在线玩家直接读取，离线玩家异步获取皮肤并在加载完成后自动刷新头颅）
   * 纹理哈希或 Base64 皮肤值：`'<skull:纹理哈希>'` 或 `'<skull:皮肤Base64>'`
3. **附加修饰标签**（可加在原版材质后面，支持多个标签组合）：
   * 自定义模型数据：`'coal<model-data:1>'`
   * 皮革染色（RGB）：`'leather chestplate<dye:255,255,0>'`
   * 旗帜图案（按顺序叠加）：`'white banner<banner:RED MOJANG,WHITE>'`
   * 组合示例：`'leather chestplate<model-data:1><dye:255,255,0>'`
4. **第三方自定义物品插件**：
   * **CraftEngine**：直接填写 `命名空间:物品ID`，或明确加前缀 `craftengine:命名空间:物品ID`
   * **Nexo**：填写 `nexo:物品ID`
   * **ItemsAdder**：填写 `ia:命名空间:物品ID` 或 `itemsadder:命名空间:物品ID`

## 方块（`block`）

直接在界面上渲染三维方块模型及其方块状态：

```yaml
frontend:
  grass:
    type: block
    block-data: 'minecraft:grass_block[snowy=false]'
    rotation: {x: -20, y: 35, z: 0}
    scale: {x: 24, y: 24, z: 24}
    offset: {z: 2}
```

* `block-data`：必填字符串，填写原版方块 ID 及可选的方括号状态参数（如 `'minecraft:oak_stairs[facing=north,half=bottom]'`）。
* 尺寸同样通过 `scale` 的 `x`、`y`、`z` 三个轴控制，稍微加一点 `rotation.x` 和 `rotation.y` 就能做出漂亮的立体等轴测图标。

## 分组（`group`）

分组通过 `children` 把多个元素打包成一个整体，支持多层嵌套。移动、旋转、缩放或隐藏父分组时，里面的所有子元素都会跟着一起变化。详细用法与模板复用请看下一篇：[分组与可复用模板](/cai-dan-pei-zhi/menus/groups-templates.md)。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.myarc.icu/cai-dan-pei-zhi/menus/frontend.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.