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

# 分组与可复用模板

当菜单里的元素多起来之后，把一张商品卡片、一排导航按钮或一个弹窗的各个部件塞进分组（`group`），管理起来会轻松很多。对于经常在不同菜单里重复出现的组件，你还可以把它保存为模板（Template），随时一键插入。

## 前端分组（`frontend` 中的 `group`）

前端分组是一个没有自身外观的容器，它通过 `children` 容纳任意数量的子元素（包括继续嵌套其他 `group`）：

```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: '&f打个招呼'
        size: 4
        offset: {z: 1}
```

`children` 内部元素的坐标、旋转和缩放，都是**相对于父分组中心**计算的。在上面的例子里：

* `greeting-background` 和 `greeting-text` 的 `x`、`y` 都是 `0`，代表它们位于 `greeting-group` 的正中心。
* `greeting-group` 设置了 `offset: {x: 40, y: -20, z: 1}`，于是背景和文字作为一个整体被放到了画布的 `(40, -20)` 位置。
* 文字的 `offset.z: 1` 叠加在分组的 `z: 1` 之上，最终深度为 `2`，稳稳显示在背景前面。

| 分组属性       | 填写内容与对子元素的影响                             |
| ---------- | ---------------------------------------- |
| `offset`   | 整体平移分组内的所有子元素（`{x, y, z}`）。              |
| `rotation` | 围绕分组的原点整体旋转所有子元素（`{x, y, z}`，单位：度）。      |
| `scale`    | 整体缩放子元素的尺寸以及它们相对于分组中心的距离（仅限非零的 `x`、`y`）。 |
| `visible`  | 填 `true` 或 `false`，一键显示或隐藏整个分组及其所有后代元素。  |
| `children` | 必填对象，按 `元素ID: {元素配置}` 的格式存放子元素。          |

## 后端分组（`backend` 中的 `group`）

如果你用前端分组做了一排按钮，后来决定把整排按钮往右挪 30 个单位，一个个去改后端点击区域的坐标会很麻烦。为此，`backend` 同样支持 `type: group`：

```yaml
backend:
  nav-hit-group:
    type: group
    x: 40
    y: -20
    scale: {x: 1, y: 1}
    children:
      greeting-area:
        x: 0
        y: 0
        width: 60
        height: 18
        actions:
          right: 'tell: &a你好！'
```

后端分组支持嵌套，它的字段非常简单：

* `type`：固定填写 `group`。
* `x`、`y`：分组相对于画布中心（或上层后端分组）的水平与垂直偏移，默认 `0`。
* `scale`：包含 `x`、`y` 的缩放系数（非零数值，默认 `1`），会同时缩放子点击区域的中心偏移和宽高尺寸。
* `children`：存放具体的点击区域或下一层后端分组。

加载菜单时，服务端会自动把后端分组的平移和缩放换算成每个点击区域的最终画布矩形。注意：无论放在前端还是后端、嵌套在第几层，**整份菜单里所有分组、视觉元素和点击区域的键名（ID）都不能重复**。

## 可复用模板文件

如果你设计好了一个漂亮的按钮或卡片分组，想在其他菜单里反复使用，可以把它做成模板文件，存放在 `plugins/ArcMenu/templates/` 目录下（支持建立子文件夹分类）。

每份模板文件包含一个顶层 `id` 和 `frontend` 下的**单个根分组**：

```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: '&f打个招呼'
        size: 4
        offset: {z: 1}
```

| 模板顶层字段           | 填写要求                                                        |
| ---------------- | ----------------------------------------------------------- |
| `schema-version` | 固定填 `1`。                                                    |
| `id`             | 模板唯一 ID。以小写字母或数字开头，只能包含小写字母、数字、下划线 `_` 和连字符 `-`，在所有模板中保持唯一。 |
| `frontend`       | 必须且只能包含一个 `type: group` 的根分组，里面可以自由包含任意前端元素和嵌套子分组。          |

假设把上面的内容保存为 `plugins/ArcMenu/templates/greeting-button.yml`，执行 `/arcmenu reload all` 即可刷新模板库，输入 `/arcmenu templates` 可以查看当前已加载的所有模板列表。

## 在可视化编辑器中保存与插入模板

相比手写模板文件，直接在 [可视化编辑器](/gong-neng-pei-zhi/editor.md) 里操作要直观得多：

1. **保存为模板**：在编辑器的前端视图中选中任意一个分组，点击保存为模板并输入模板 ID，服务端就会自动生成对应的模板 YAML 文件。
2. **插入模板**：在编辑另一份菜单时，从模板库中选择需要的模板插入画布。插入后的内容会成为当前菜单里一个独立的普通分组——如果里面有元素 ID 与当前菜单已有的元素重名，编辑器会自动为你重命名避让。
3. **后续调整**：你可以随意修改插入后分组的位置、文字和颜色，并在 `backend` 标签页为它画上对应的点击区域。

此外，打开 [项目管理器](/gong-neng-pei-zhi/projects.md) 还可以按文件夹浏览和预览模板，或者把模板连同菜单、Effect 一起打包导出为 [ArcPack](/gong-neng-pei-zhi/arcpack.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/groups-templates.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.