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

# 后端交互区域与点击事件

`backend` 定义菜单中的点击范围、提示文字和点击操作。显示按钮属于 `frontend`，交互区域需要单独配置，两者不会通过名称自动关联。

本页依次介绍区域属性、`actions` 下的点击类型，以及区域条件与拒绝动作。动作写法见[动作与导航](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/actions.md)，判断表达式与动作分支见[条件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/conditions.md)。

## 区域结构

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

层级为：**`backend` → 区域名称（`greeting-area`）→ 区域属性 → `actions` → 点击类型 → 动作**。

示例在 `(0, -20)` 创建一个宽 `60`、高 `18` 的区域：右键发送消息，Shift+右键关闭菜单。它是菜单片段，需合并到已有 `backend` 中，并配置对应的显示内容。

区域名称必须在整个菜单内唯一，不能与前端元素或分组名称重复。

## 区域属性

以下属性都位于区域名称下，与 `actions` 同级。

| 属性               | 用途                        | 默认值         |
| ---------------- | ------------------------- | ----------- |
| `x`、`y`          | 区域中心坐标。                   | 各为 `0`。     |
| `width`、`height` | 区域宽度和高度，必须填写且大于 `0`。      | 无。          |
| `priority`       | 重叠区域的选择优先级，使用整数。          | `0`。        |
| `tooltip`        | 指向区域时显示的提示文字，可用一行文字或文字列表。 | 不显示提示。      |
| `update`         | 提示文字的定时刷新间隔，单位为游戏刻。       | `-1`，不定时刷新。 |
| `actions`        | 按点击类型配置的动作。               | 无。          |
| `condition`      | 点击区域时必须满足的条件。             | 无条件限制。      |
| `deny`           | 区域条件不满足时执行的动作。            | 无。          |

### 位置与尺寸

区域使用画布坐标，`x` 正值向右，`y` 正值向上。宽度和高度以区域中心向两侧展开。

上方示例的横向范围是 `-30` 至 `30`，纵向范围是 `-29` 至 `-11`。坐标与单位说明见[画布、坐标与屏幕位置](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/canvas.md)。

区域不支持 `offset`、`rotation`、`scale`、`z` 或 `visible`。调整显示按钮的位置和大小时，应同步调整区域；隐藏显示元素不会自动禁用区域。

### 重叠优先级：`priority`

多个区域覆盖同一点时，只选中一个区域：`priority` 数值更高的区域优先；数值相同时，优先选择配置中较早出现的区域。

区域被选中后，如果没有匹配的点击动作，或条件检查失败，不会继续尝试下层区域。因此，大范围区域可能遮挡小按钮的操作范围，应通过布局或优先级明确区分。

这里的 `priority` 只决定区域选择，不表示某条动作的执行顺序。

### 提示文字：`tooltip` 与 `update`

仅 Paper、Folia、Leaf 等服务端提供提示框显示。

```yaml
backend:
  information-area:
    x: 0
    y: 0
    width: 80
    height: 24
    tooltip:
      - '&fServer information'
      - '&7Player: %player_name%'
    update: 20
```

`update` 接受 `-1` 或正整数，不接受 `0`。此设置刷新提示文字，不负责修改点击区域或刷新前端文字。

区域中的 `tooltip` 设置内容，提示框大小、背景等外观在 `tooltip.yml` 中设置。鼠标或视线指向区域即可显示提示，不要求先点击，也不因区域 `condition` 不满足而自动隐藏。

外观字段与图片背景的完整设置见[提示框](/arcmenu-wen-dang/gong-neng-pei-zhi/tooltips.md)。

Spigot 不显示提示框，也不提供提示文字定时刷新。

## 点击类型：`actions`

点击类型写在区域的 `actions` 下，不应直接写到区域名称下。

| 点击类型           | 触发操作              | Spigot                 |
| -------------- | ----------------- | ---------------------- |
| `all`          | 所有支持的点击操作。        | 支持。                    |
| `left`         | 不按 Shift 的左键。     | 支持。                    |
| `right`        | 不按 Shift 的右键。     | 支持。                    |
| `middle`       | 不按 Shift 的中键。     | 不支持。                   |
| `shift`        | 所有支持的 Shift+点击操作。 | 支持 Shift+左键和 Shift+右键。 |
| `shift-left`   | Shift+左键。         | 支持。                    |
| `shift-right`  | Shift+右键。         | 支持。                    |
| `shift-middle` | Shift+中键。         | 不支持。                   |

`right` 不包含 Shift+右键，`left` 不包含 Shift+左键。需要共同处理时，可分别配置，或使用适当的 `all`、`shift`。

`middle` 与 `shift-middle` 仅适用于 Paper 系服务端的鼠标模式，触摸模式不提供中键操作。模式选择与操作说明见[触摸与鼠标输入](/arcmenu-wen-dang/gong-neng-pei-zhi/input-modes.md)。

### 单条与多条动作

单条动作可直接填写；多条动作使用列表，按列表顺序执行。

```yaml
backend:
  notice-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      all:
        - 'sound: UI_BUTTON_CLICK-1-1'
      right:
        - 'tell: &aFirst message.'
        - 'tell: &bSecond message.'
      shift-right: close
```

普通右键会同时匹配 `all` 和 `right`，Shift+右键则匹配 `all` 和 `shift-right`。匹配的点击分组按配置出现顺序处理，并不是只选择最具体的一项。

关闭、切换菜单或结束执行的动作可能使后续动作不再执行。公共声音等操作可放在前面的 `all`，再填写对应点击操作。

## 区域条件与拒绝动作

`condition` 与 `deny` 写在区域属性层，而不是点击类型层。下面的区域仅允许拥有指定权限的玩家执行右键动作：

```yaml
backend:
  vip-area:
    x: 0
    y: 0
    width: 80
    height: 24
    condition: 'perm myserver.menu.vip'
    deny:
      - 'tell: &cYou do not have permission.'
    actions:
      right:
        - 'tell: &aAccess granted.'
```

处理顺序为：

1. 根据指向位置和优先级选中区域。
2. 检查该区域的 `condition`。
3. 条件不满足时执行 `deny`，不执行 `actions`。
4. 条件满足时，执行与当前点击类型匹配的动作。

因此，只要点击命中该区域且条件失败，即使没有为该点击类型配置动作，也可能执行区域的 `deny`。

区域条件不会自动隐藏按钮或提示框。若只想对某一种点击设置条件，应在该点击的动作配置中设置，具体写法见[条件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/conditions.md)。

## 检查与加载

修改后执行 `/arcmenu validate` 和 `/arcmenu reload`，正常打开菜单检查：

* 显示按钮与点击范围是否对齐。
* 普通点击和 Shift+点击是否执行正确动作。
* 重叠区域的优先级是否符合预期。
* 无权限玩家是否得到正确的拒绝提示。

Paper 系服务端可用 `/arcmenu preview <菜单标识> backend` 查看区域位置，但预览不执行点击动作。Spigot 应通过正常打开菜单测试。相关命令见[命令与权限](/arcmenu-wen-dang/pei-zhi-yu-guan-li/commands-permissions.md)。