> 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/groups-templates.md).

# 分组与可复用模板

分组用于统一管理多个显示元素；模板用于保存常用分组，便于在其他菜单中重复使用。

Paper、Folia、Leaf 和 Spigot 都支持基础分组。模板文件与编辑器模板功能仅适用于 Paper 系服务端。

## 分组结构：`group`

分组写在 `frontend` 中，使用 `type: group`。子元素放入该分组的 `children`，仍按照“元素名称 → 类型与属性”配置。

```yaml
frontend:
  greeting-group:
    type: group
    offset: {x: 40, y: -20, z: 1}
    children:
      greeting-background:
        type: rectangle
        width: 60
        height: 18
        color: '#365E91'
      greeting-text:
        type: text
        content: '&fSay hello'
        size: 4
        offset: {z: 1}

backend:
  greeting-area:
    x: 40
    y: -20
    width: 60
    height: 18
    actions:
      right:
        - 'tell: &aHello!'
```

这是菜单片段，需合并到已有文件的对应配置节中。分组本身不显示内容，示例由矩形背景和文字组成按钮。

### 通用属性

分组支持 `offset`、`rotation`、`scale` 和 `visible`，作用于整个分组。具体取值规则见[前端元素类型](https://simple.superiormc.cn/arcmenu-wen-dang/cai-dan-pei-zhi/menus/pages/phk8Dy6jQrfp3TU7d7xK#通用属性)。

| 属性         | 对子元素的影响                    |
| ---------- | -------------------------- |
| `offset`   | 整体移动。                      |
| `rotation` | 围绕分组原点整体旋转。                |
| `scale`    | 缩放子元素的尺寸及其相对位置，支持 `x`、`y`。 |
| `visible`  | 为 `false` 时，隐藏全部子元素。       |

分组不使用 `width`、`height`、`color` 或 `opacity`。需要背景或透明度时，应在对应子元素中设置。

### 子元素：`children`

子元素的位置以分组原点为参考。在上方示例中，背景和文字都位于分组中心；文字额外使用 `z: 1`，显示在背景前方。

仅使用平移时，子元素的最终位置等于分组位置加上自身偏移。例如，分组为 `x: 40`，子元素为 `offset.x: 10`，最终位于 `x: 50`。

分组旋转或缩放后，子元素的相对位置也随之变化，此时不能只相加坐标。

### 嵌套分组

`children` 中可以继续包含 `type: group`，用于组织卡片、标题栏等组件。每一层都以其所在分组为参考，并继承外层的变化。

元素名称必须在整个菜单中唯一，不是仅在当前 `children` 中唯一。复制分组时，应同时修改分组及所有子元素的名称。

## 分组与点击区域

后端区域不属于分组的 `children`，仍在菜单顶层的 `backend` 中设置。

上方示例的分组中心为 `(40, -20)`，没有额外缩放或旋转，因此点击区域也使用 `x: 40`、`y: -20`，尺寸与按钮背景一致。

移动、旋转、缩放或隐藏分组，不会自动修改区域。分组隐藏后，原有区域仍可能接收点击，不能仅用 `visible: false` 禁用按钮。

点击区域是与画布对齐的矩形，不能通过前端分组旋转它。布局坐标和对齐方式见[画布、坐标与屏幕位置](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/canvas.md)。

## 模板文件

模板存放在 `plugins/ArcMenu/templates/`，用于保存一个完整前端分组。它不包含点击区域、菜单权限或打开与关闭事件。

### 顶层字段

| 字段               | 用途                        |
| ---------------- | ------------------------- |
| `schema-version` | 配置格式，使用 `1`。              |
| `id`             | 模板标识，同一模板目录中必须唯一。         |
| `frontend`       | 必须且只能包含一个根元素，类型为 `group`。 |

模板标识使用小写字母、数字、下划线和连字符，并以字母或数字开头。模板标识与根分组名称用途不同，不必相同。

### 完整示例

将以下内容保存为 `plugins/ArcMenu/templates/greeting-button.yml`：

```yaml
schema-version: 1
id: greeting-button
frontend:
  button-group:
    type: group
    children:
      button-background:
        type: rectangle
        width: 60
        height: 18
        color: '#365E91'
      button-text:
        type: text
        content: '&fSay hello'
        size: 4
        offset: {z: 1}
```

示例将根分组留在原点，插入后再调整位置。模板也可以保存分组的偏移、旋转和缩放，插入时会一并保留。

手动修改模板文件后，执行：

```
/arcmenu reload all
/arcmenu templates
```

第一条命令重新加载模板，第二条查看已加载的模板标识。普通 `/arcmenu reload` 不会更新模板列表。

## 使用模板

### 通过编辑器

需要 `arcmenu.admin`，并在管理员客户端安装兼容的 ArcMenu Editor。

1. 使用 `/arcmenu edit <菜单标识>` 打开目标菜单。
2. 使用编辑器的模板功能，选择已加载的模板并插入。
3. 调整新分组的位置、文字及其他属性。
4. 为需要交互的组件配置后端区域和动作。
5. 保存菜单，并实际打开菜单验证显示与点击。

编辑器插入时会处理元素名称冲突。若要将已有组件保存为模板，应先选中分组，再使用模板保存功能填写新的模板标识；不能直接将单个文字或矩形保存为分组模板，也不能用同名保存覆盖已有模板文件。

### 手动复制

不使用编辑器时，可把模板 `frontend` 下的根分组复制到目标菜单的 `frontend` 中，修改所有重复名称，再配置相应的点击区域。

菜单没有用于自动引用模板的 `template` 字段。不要将模板标识写成元素类型，也不要把整个模板文件直接放入菜单目录。

Spigot 可手动复用只包含受支持元素的分组配置，但不加载模板目录，也不提供编辑器模板功能。

### 后续修改

插入后的分组是菜单中的独立内容。修改或删除模板，不会自动改变已经插入的分组；修改菜单中的分组，也不会更新模板。

需要统一更新已有菜单时，应分别修改这些菜单，或重新插入调整后的模板。模板中的图片仍依赖对应的图片文件和资源包。

## 检查与加载

修改菜单中的分组后，执行 `/arcmenu validate` 和 `/arcmenu reload`。修改模板文件后使用 `/arcmenu reload all`。

检查显示效果时，应同时检查按钮区域的位置、尺寸及隐藏状态。模板只复用显示内容，交互配置需要在目标菜单中单独维护。

## 下一步

继续阅读[后端交互区域与点击事件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/backend.md)，为分组组件配置点击范围和操作。