> 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.md).

# 菜单文档结构

每个菜单使用一个 YAML 文件。本页按配置层级介绍菜单的顶层字段；画布、元素和点击区域的子字段可通过文中的链接查阅对应配置参考。

创建并加载菜单的步骤见[第一个菜单](/arcmenu-wen-dang/ru-men/first-menu.md)；菜单文件的保存目录见[配置文件说明](/arcmenu-wen-dang/pei-zhi-yu-guan-li/configuration-files.md)。

## 整体结构

下面是一份基础菜单配置，包含显示内容、关闭按钮和打开时的提示消息。它可用于 Paper、Folia、Leaf 和 Spigot。

```yaml
schema-version: 1
id: menu-guide
permission: arcmenu.use
main-menu: false

canvas:
  width: 320
  height: 180
  pixels-per-block: 42.7
  distance: 3

frontend:
  background:
    type: rectangle
    width: 140
    height: 80
    color: '#182031'
  title:
    type: text
    content: '&fMenu guide'
    offset: {y: 20, z: 1}
    size: 5
  close-button:
    type: rectangle
    width: 60
    height: 18
    offset: {y: -20, z: 1}
    color: '#365E91'
  close-label:
    type: text
    content: '&fClose'
    offset: {y: -20, z: 2}
    size: 4

backend:
  close-area:
    x: 0
    y: -20
    width: 60
    height: 18
    actions:
      right: close

events:
  open:
    - 'tell: &aMenu opened.'
```

示例未设为主菜单。将其加入已有菜单目录时，应保留原有主菜单。

## 顶层字段

以下字段都位于文件最外层，不应缩进到其他配置节中。

| 字段               | 内容形式             | 用途                       |
| ---------------- | ---------------- | ------------------------ |
| `schema-version` | 整数               | 菜单配置格式。                  |
| `id`             | 文字               | 菜单的唯一标识。                 |
| `permission`     | 文字               | 打开菜单所需的权限。               |
| `open-commands`  | 列表               | 自定义打开命令，仅适用于 Paper 系服务端。 |
| `main-menu`      | `true` 或 `false` | 是否作为主菜单。                 |
| `canvas`         | 配置节              | 画布设置。                    |
| `frontend`       | 配置节              | 显示元素。                    |
| `backend`        | 配置节              | 点击区域与交互设置。               |
| `events`         | 配置节              | 菜单打开、关闭时执行的动作。           |

### `schema-version`

使用 `schema-version: 1`。此值表示菜单配置格式，与插件版本号无关。

### `id`

菜单标识用于打开菜单和菜单之间的跳转。例如，`id: menu-guide` 对应：

```
/arcmenu open menu-guide
```

标识只能使用小写字母、数字、下划线和连字符，必须以字母或数字开头。同一菜单目录中不能出现重复标识。

文件名可以与标识不同，但建议保持一致，便于管理。打开命令使用 `id`，而非文件名。

### `permission`

设置打开菜单所需的权限，例如 `permission: myserver.menu.vip`。

玩家还需拥有 `arcmenu.use`。省略 `permission` 或将其设为空字符串时，不要求额外的菜单权限。

权限授予方式见[命令与权限](https://simple.superiormc.cn/arcmenu-wen-dang/cai-dan-pei-zhi/pages/X6IEXfGvXnUbMXQX0QIP#菜单权限)。

### `open-commands`

为菜单配置专用的打开命令，适用于 Paper、Folia、Leaf 等服务端。例如：

```yaml
open-commands:
  - menuguide
  - serverguide
```

加载后，玩家可使用 `/menuguide` 或 `/serverguide` 打开该菜单，仍需满足菜单权限要求。

命令名称不包含 `/`，只能使用小写字母、数字、下划线和连字符，必须以字母或数字开头，长度不超过 64 个字符。不能在列表中重复，也不能被其他菜单或插件占用。

不需要专用命令时可省略此字段，继续使用 `/arcmenu open <菜单标识>`。Spigot 不提供此功能，应使用 `/arcmenu open`。

### `main-menu`

`main-menu: true` 将菜单设为 Shift+F 打开的主菜单。未配置时为 `false`。

全部菜单中必须且只能有一个主菜单，即使关闭了 Shift+F 快捷键，也应保留该设置。更换主菜单时，应同时取消原主菜单的 `main-menu: true`。

快捷键开关位于服务端对应的 `config.yml`，见[配置文件说明](/arcmenu-wen-dang/pei-zhi-yu-guan-li/configuration-files.md)。

### `canvas`

集中设置画布的尺寸、显示比例与距离。文字、按钮及点击区域都按照菜单坐标进行布局。

本节只介绍它在文档中的位置；具体子字段及其与屏幕位置设置的关系见[画布、坐标与屏幕位置](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/canvas.md)。

### `frontend`

按元素名称组织可见内容，每个元素在自己的配置节中设置类型和属性。上方示例中的 `background`、`title`、`close-button` 和 `close-label` 都属于这一层。

阅读顺序为：**`frontend` → 元素名称 → `type` 与属性**。各类型可用属性见[前端元素类型](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/frontend.md)。

### `backend`

按区域名称组织交互设置，每个区域在自己的配置节中定义点击范围和对应操作。上方示例的 `close-area` 是一个区域。

阅读顺序为：**`backend` → 区域名称 → 区域属性与 `actions` → 点击类型与动作**。

显示元素与点击区域分别配置。更改按钮位置和大小时，需要同步调整对应区域；前端分组的变化不会自动应用到点击区域。

同一菜单内，显示元素和区域名称必须唯一，分组内的元素也不能使用已有名称。不要让按钮元素和点击区域共用同一个名称。

区域子字段见[后端交互区域与点击事件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/backend.md)。

### `events`

设置菜单打开或关闭时执行的动作。其下一层使用 `open` 和 `close`：

```yaml
events:
  open:
    - 'tell: &aMenu opened.'
  close:
    - 'tell: &7Menu closed.'
```

不需要事件动作时可省略。动作写法与按钮中的动作使用相同规则，具体用法见[动作与导航](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/actions.md)。

这里的 `close` 是关闭事件名称；按钮中的 `right: close` 则表示右键执行关闭动作，二者所处层级不同。

## 编写规则

* 使用空格缩进，保持同一层级对齐。
* 使用插件支持的字段名，不能自行增加未知字段。
* 同一配置节内不要重复填写同名字段。
* 包含颜色符号或特殊字符的文字应保留引号。
* 修改完成后，先检查配置，再执行重载。

使用的功能应符合[平台与插件兼容性](/arcmenu-wen-dang/pei-zhi-yu-guan-li/compatibility.md)。检查和重载命令见[命令与权限](/arcmenu-wen-dang/pei-zhi-yu-guan-li/commands-permissions.md)。