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

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

`backend` 负责处理玩家的鼠标或视线交互。你在 `frontend` 里摆好了按钮的图案和文字后，只需在 `backend` 里相同的位置放一块矩形交互区域，就能让它响应点击、悬停并弹出提示框。

如果你需要做文本输入框，也可以在 `backend` 中配置 `type: Arcitx`（详见 [Arcitx 文本输入](/gong-neng-pei-zhi/arcitx.md)）；如果需要批量移动多块点击区域，可以使用 `type: group`（详见 [分组与可复用模板](/cai-dan-pei-zhi/menus/groups-templates.md)）。普通点击区域不需要写 `type` 字段。

## 区域属性一览

```yaml
backend:
  greeting-area:
    x: 0
    y: -20
    width: 60
    height: 18
    priority: 1
    tooltip:
      - '&f欢迎按钮'
      - '&7右键打个招呼'
    update: 20
    actions:
      right: 'tell: &a你好，%player_name%！'
      shift-right: close
```

| 属性               | 填写内容与说明                                                                 | 省略时的默认值   |
| ---------------- | ----------------------------------------------------------------------- | --------- |
| `x`、`y`          | 区域中心点的画布坐标，填有限数值。                                                       | `0`       |
| `width`、`height` | 必填，区域的宽度与高度，必须填大于 `0` 的数值。                                              | 必填        |
| `priority`       | 整数优先级。当两个区域在画布上有重叠时，指针会命中 `priority` 更大的那一个；若优先级相同，则命中在 YAML 中写得更靠前的区域。 | `0`       |
| `tooltip`        | 指针悬停在区域上时显示的提示文字，可填单行字符串或字符串列表。                                         | 空（不显示提示框） |
| `update`         | 提示框内占位符的刷新间隔（单位：tick）。填正整数定时刷新，填 `-1` 则不定时刷新。不能填 `0`。                   | `-1`      |
| `condition`      | 区域的准入条件表达式（字符串）。用于判断点击时执行 `actions` 还是 `deny`，以及是否触发悬停动作。               | 无条件限制     |
| `actions`        | 满足条件（或未设条件）时点击触发的动作配置。                                                  | 空         |
| `deny`           | 设有 `condition` 且点击时不满足条件所执行的动作（单条动作或动作列表）。                              | 空         |
| `on-hover`       | 指针刚进入该区域时触发的动作或条件动作组。                                                   | 空         |
| `on-leave`       | 指针刚移出该区域时触发的动作或条件动作组。                                                   | 空         |

管理员在游戏内调试时，可以执行 `/arcmenu preview <菜单ID> backend`，直接在画面上看到所有后端区域的实际边框位置，核对它们是否准确覆盖了前端按钮。

## 点击类型（`actions`）

`actions` 既可以直接写单条动作、动作列表（此时任意点击都会触发），也可以按点击按键细分：

| 点击键名           | 触发方式               |
| -------------- | ------------------ |
| `all`（或 `any`） | 任意点击都会触发           |
| `left`         | 普通左键               |
| `right`        | 普通右键               |
| `middle`       | 鼠标中键（通过原版选取方块操作触发） |
| `shift`        | 按住潜行键（Shift）时的任意点击 |
| `shift-left`   | Shift + 左键         |
| `shift-right`  | Shift + 右键         |
| `shift-middle` | Shift + 中键         |

你可以把通用反馈（比如按键音）写在 `all` 里，再把具体功能分给不同的按键。当一次点击同时匹配多个键名时（例如按 `Shift+右键` 会同时匹配 `all`、`shift` 和 `shift-right`），它们会按照你在 YAML 里书写的先后顺序依次执行：

```yaml
backend:
  item-slot:
    x: 0
    y: 0
    width: 36
    height: 36
    actions:
      all: 'sound: UI_BUTTON_CLICK-1-1'
      left: 'open: item-details'
      right: 'cmd: shop buy 1'
      shift-right: 'cmd: shop buy 64'
```

## 悬停与离开事件（`on-hover` / `on-leave`）

当玩家的视线（触控模式）或光标（Mouse / Vision 模式）移入、移出某个区域时，可以用 `on-hover` 和 `on-leave` 做出灵动的悬停反馈——比如播放清脆的提示音，或者驱动一段按钮放大高亮的动画：

```yaml
backend:
  card-area:
    x: 0
    y: -20
    width: 80
    height: 24
    on-hover:
      - 'sound: UI_BUTTON_CLICK-0.4-1.8'
      - 'animation: card-hover-in'
    on-leave:
      - 'stop-animation: card-hover-in'
      - 'animation: card-hover-out'
    actions:
      right: 'tell: &a已选择这张卡片。'
```

悬停机制有几个贴心的细节：

* **单次触发**：移入区域时触发一次 `on-hover`，指针停留在区域内移动不会每 tick 重复触发；移出区域时触发一次 `on-leave`。
* **平滑切换**：当指针从一个按钮直接滑到紧挨着的另一个按钮时，会先执行旧区域的 `on-leave`，再执行新区域的 `on-hover`。
* **支持条件**：如果区域本身配置了顶层 `condition`，只有满足条件的玩家把指针移上去才会触发 `on-hover` 和 `on-leave`；你也可以直接在 `on-hover` 内部编写[条件动作组](/cai-dan-pei-zhi/menus/conditions.md)。

关于如何编写 `card-hover-in` 这样的元素位移动画，请参考 [动画时间线与轨道](/gong-neng-pei-zhi/animations.md)。

## 区域条件与拒绝反馈

给按钮加上 `condition` 和 `deny` 后，你可以轻松实现“未达到要求时点击弹出提示，达到要求后正常执行”的交互：

```yaml
backend:
  vip-area:
    x: 60
    y: 0
    width: 70
    height: 22
    tooltip:
      - '&6会员专享礼包'
      - '&7点击领取每日奖励'
    condition: 'perm myserver.vip'
    deny:
      - 'sound: ENTITY_VILLAGER_NO-1-1'
      - 'tell: &c你需要先开通会员才能领取这份礼包。'
    actions:
      right:
        - 'sound: ENTITY_PLAYER_LEVELUP-1-1'
        - 'console: give %player_name% diamond 5'
```

即使玩家还不满足 `condition`，把指针移到按钮上依然能正常看到 `tooltip` 提示框，方便玩家了解这个按钮的用途。有关提示框样式定制、边框与背景图的配置，请查看 [提示框](/gong-neng-pei-zhi/tooltips.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/backend.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.