> For the complete documentation index, see [llms.txt](https://simple.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simple.superiormc.cn/arcmenu-wen-dang/cai-dan-pei-zhi/menus/frontend.md). # 前端元素类型 `frontend` 定义菜单中的可见内容。每个元素先填写 `type`，再配置通用属性及该类型支持的专属属性。点击范围和动作另在 `backend` 中设置。 ## 元素结构 ```yaml frontend: title: type: text content: '&fWelcome' size: 5 offset: {y: 24, z: 1} ``` 层级依次为：**`frontend` → 元素名称（`title`）→ 属性（`type`、`content` 等）**。 元素名称由管理员设置，必须在同一菜单内唯一，包括分组内的元素和后端区域。`type` 使用下表中的小写值。 | 类型 | 用途 | Spigot | | ----------- | ------- | -------- | | `text` | 文字。 | 支持静态文字。 | | `rectangle` | 矩形背景。 | 支持。 | | `frame` | 矩形边框。 | 支持。 | | `line` | 直线或分隔线。 | 支持。 | | `image` | PNG 图片。 | 不支持。 | | `item` | 物品展示。 | 仅支持原版材质。 | | `block` | 方块展示。 | 支持。 | | `group` | 组合多个元素。 | 支持基础分组。 | 本页的 YAML 示例均为菜单片段。添加到已有文件时，将元素合并到原有的 `frontend` 下，不要重复创建顶层 `frontend`。 ## 通用属性 以下属性直接写在元素名称下，与 `type` 同级。 | 属性 | 用途 | 默认值 | | ---------- | --------------------------- | -------- | | `offset` | 元素位置，子字段为 `x`、`y`、`z`。 | 各轴为 `0`。 | | `rotation` | 旋转角度，单位为度，子字段为 `x`、`y`、`z`。 | 各轴为 `0`。 | | `scale` | 缩放倍数。 | 各轴为 `1`。 | | `visible` | 是否显示元素。 | `true`。 | ### `offset` 用于安排元素位置和前后层次。坐标方向与单位见[画布、坐标与屏幕位置](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/canvas.md)。分组内的元素位置以所在分组为参考。 ### `rotation` `rotation.z` 用于在菜单平面上旋转；`rotation.x` 和 `rotation.y` 用于倾斜元素。旋转只影响显示元素，不会自动旋转点击区域。 ### `scale` 文字、矩形、边框、线条、图片和分组使用 `scale.x`、`scale.y`。物品和方块还支持独立的 `scale.z`，用于调整深度。 缩放值不能为 `0`。隐藏元素应使用 `visible: false`。通常使用正数缩放；负数会翻转相应方向。分组缩放对其子元素的影响见[分组与可复用模板](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/groups-templates.md)。 ### `visible` `false` 隐藏元素；用于分组时会隐藏其所有子元素。它不关闭菜单，也不会自动移除对应的后端点击区域。 ## 类型专属属性 ### 文字：`text` | 属性 | 用途 | 默认值 | | ------------ | ------------------------------------- | -------------------- | | `content` | 显示文字，必须填写。 | 无。 | | `size` | 文字大小，必须大于 `0`。 | `10`。 | | `font` | 字体名称，格式为 `命名空间:路径`。 | `minecraft:default`。 | | `opacity` | 不透明度，整数，范围为 `0` 至 `255`。 | `255`。 | | `line-width` | 自动换行宽度，按字体像素计算，必须为正整数。 | `200`。 | | `alignment` | 多行文字的行对齐方式：`left`、`center` 或 `right`。 | `center`。 | | `update` | 定时刷新间隔，单位为游戏刻；`-1` 表示不定时刷新。 | `-1`。 | ```yaml frontend: player-name: type: text content: '&f%player_name%' size: 5 alignment: center offset: {y: 20, z: 1} ``` 文字可以使用颜色代码和支持的占位符。`update` 只接受 `-1` 或正整数，用于需要定时更新的内容；它不是动画速度。Spigot 的文字在打开时显示，不提供定时刷新，且仅支持默认字体和基础占位符。 自定义字体需要玩家加载包含该字体的资源包。字体名称本身不会创建字体。 ### 矩形：`rectangle` | 属性 | 用途 | 默认值 | | ---------------- | ------------------------ | ------------ | | `width`、`height` | 矩形尺寸，必须填写且大于 `0`。 | 无。 | | `color` | 颜色，格式为带引号的 `'#RRGGBB'`。 | `'#FFFFFF'`。 | | `opacity` | 不透明度，整数，范围为 `0` 至 `255`。 | `255`。 | ```yaml frontend: panel: type: rectangle width: 140 height: 80 color: '#182031' opacity: 235 ``` 尺寸使用画布单位。透明度通过 `opacity` 设置，不写入颜色值；`0` 表示完全透明，`255` 表示完全不透明。 ### 边框：`frame` 支持 `width`、`height`、`thickness`、`color` 和 `opacity`。 `width`、`height`、`thickness` 必须填写且大于 `0`。`thickness` 为边框粗细，必须小于宽度和高度各自的一半。颜色与不透明度规则同矩形。 ```yaml frontend: panel-border: type: frame width: 140 height: 80 thickness: 1 color: '#617DA0' offset: {z: 1} ``` 边框不填充内部区域。需要带边框的背景时，应分别配置矩形与边框。 ### 线条：`line` 支持 `width`、`thickness`、`color` 和 `opacity`。`width` 为长度，`thickness` 为粗细，两者必须填写且大于 `0`。颜色与不透明度规则同矩形。 ```yaml frontend: divider: type: line width: 100 thickness: 1 color: '#617DA0' offset: {y: 10, z: 1} ``` 默认是水平线。可设置 `rotation: {z: 90}` 改为竖线。线条使用 `thickness`，不使用 `height`。 ### 图片：`image` 仅适用于 Paper、Folia、Leaf 等服务端。 | 属性 | 用途 | 默认值 | | ---------------- | ------------------------ | -------------------- | | `source` | PNG 图片路径，必须填写。 | 无。 | | `width`、`height` | 图片显示尺寸，分别设置。 | 分别使用原图像素宽度和高度作为画布尺寸。 | | `opacity` | 不透明度，整数，范围为 `0` 至 `255`。 | `255`。 | | `color` | 可选的图片着色，格式为 `'#RRGGBB'`。 | 保留原色。 | | `update` | 图片路径内容的定时刷新间隔，规则同文字。 | `-1`。 | ```yaml frontend: logo: type: image source: /example.png width: 40 height: 40 offset: {z: 1} ``` `/example.png` 对应 `plugins/ArcMenu/images/example.png`。路径以 `/` 开头，使用小写名称和 `.png` 扩展名；子目录示例为 `/ui/logo.png`。 只填写宽度或高度时，另一项仍使用原图对应尺寸，不会自动按比例计算。保持原图比例时，应同时填写匹配的宽度和高度。 图片文件缺失时，该图片不会显示。`update` 不负责重新读取磁盘图片；修改文件后仍需重建资源并更新玩家的资源包，见[图片与资源包](/arcmenu-wen-dang/gong-neng-pei-zhi/resource-packs.md)。 ### 物品：`item` | 属性 | 用途 | 默认值 | | ---------- | --------------------- | ------ | | `material` | 物品材质或支持的自定义物品标识，必须填写。 | 无。 | | `context` | 物品展示方式。 | `GUI`。 | ```yaml frontend: sword: type: item material: minecraft:diamond_sword context: GUI scale: {x: 24, y: 24, z: 24} offset: {z: 2} ``` 物品尺寸使用 `scale` 调整，不使用 `width` 或 `height`。`scale.z` 独立设置，省略时为 `1`，不会跟随 `x`、`y`。 `context` 可使用 `GUI`、`HEAD`、`FIXED`、`GROUND`、`NONE`、`FIRSTPERSON_LEFTHAND`、`FIRSTPERSON_RIGHTHAND`、`THIRDPERSON_LEFTHAND`、`THIRDPERSON_RIGHTHAND`，按上述大写形式填写。 Paper 系服务端还支持 CraftEngine 物品标识和以下材质写法： | 写法 | 用途 | | ----------------------------------------- | ---------------------- | | `''` | 显示玩家头像，可使用玩家名称或 UUID。 | | `''` | 使用有效的皮肤纹理哈希或 Base64 值。 | | `'coal'` | 指定自定义模型数据，需要对应资源包模型。 | | `'leather chestplate'` | 为皮革装备设置 RGB 颜色。 | | `'white banner'` | 按顺序设置旗帜图案。 | `head` 与 `skull` 不能同时使用。染色只适用于皮革装备，旗帜设置只适用于旗帜。Spigot 仅支持原版材质名称，不支持上述材质标签或 CraftEngine 物品。 ### 方块：`block` `block-data` 必须填写，使用有效的原版方块名称，可附带方块状态。 ```yaml frontend: grass: type: block block-data: 'minecraft:grass_block[snowy=false]' rotation: {x: -20, y: 35} scale: {x: 24, y: 24, z: 24} offset: {z: 2} ``` 方块尺寸与物品相同，通过 `scale.x`、`scale.y`、`scale.z` 设置，不使用 `width` 或 `height`。方块名称和状态必须在所用服务端版本中存在。 ### 分组：`group` 分组本身不显示内容，使用 `children` 容纳子元素。它支持通用属性，可整体移动、旋转、缩放或隐藏多个元素。 子元素仍按“元素名称 → 类型与属性”配置。具体写法及模板复用见[分组与可复用模板](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/groups-templates.md)。 ## 修改后的操作 修改元素配置后，执行 `/arcmenu validate` 和 `/arcmenu reload`，重新打开菜单检查效果。涉及图片或模板时，使用 `/arcmenu reload all` 并按需更新资源包。 显示元素不会自行产生点击动作。需要交互时，还应配置后端区域；位置与范围关系见[画布、坐标与屏幕位置](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/canvas.md)。