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

# 动作与导航

动作决定玩家点击按钮、打开菜单或关闭菜单时执行什么操作。本页介绍动作写法、消息与命令、菜单导航，以及执行顺序和附加选项。区域与点击类型的配置见[后端交互区域与点击事件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/backend.md)。

## 配置位置与写法

动作可填写在以下位置：

| 位置                                  | 执行时机           |
| ----------------------------------- | -------------- |
| `backend` → 区域名称 → `actions` → 点击类型 | 点击指定区域时。       |
| `backend` → 区域名称 → `deny`           | 点击区域但不满足区域条件时。 |
| `events` → `open`                   | 菜单打开时。         |
| `events` → `close`                  | 菜单关闭时。         |

有参数的动作使用 `动作名称: 参数`；无参数的动作直接填写名称。单条动作可以直接填写，多条动作使用 YAML 列表。

```yaml
backend:
  notice-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'sound: UI_BUTTON_CLICK-1-1'
        - 'tell: &aWelcome!'
      shift-right: close
```

这是菜单片段，应与显示内容一起加入已有菜单。动作字符串建议保留引号，尤其是包含冒号、颜色代码或特殊字符时。

打开与关闭事件使用相同写法：

```yaml
events:
  open:
    - 'sound: UI_BUTTON_CLICK-1-1'
  close:
    - 'tell: &7Menu closed.'
```

## 消息与声音

| 动作          | 示例                                             | 用途                     | Spigot |
| ----------- | ---------------------------------------------- | ---------------------- | ------ |
| `tell`      | `tell: &aWelcome!`                             | 向玩家发送聊天消息。             | 支持。    |
| `tellraw`   | `tellraw: {"text":"Welcome!","color":"green"}` | 发送带格式的聊天消息，支持 JSON 文字。 | 不支持。   |
| `chat`      | `chat: Hello everyone!`                        | 让玩家向聊天频道发送消息。          | 不支持。   |
| `actionbar` | `actionbar: &aReady`                           | 在快捷栏上方显示文字。            | 不支持。   |
| `title`     | 见下方。                                           | 显示屏幕标题与副标题。            | 不支持。   |
| `bossbar`   | 见下方。                                           | 在屏幕顶部显示限时提示条。          | 不支持。   |
| `sound`     | `sound: UI_BUTTON_CLICK-1-1`                   | 向玩家播放声音。               | 支持。    |

`tell` 发送给当前玩家；`chat` 是玩家发出的聊天消息，两者用途不同。

### 声音参数

`sound` 使用 `声音名称-音量-音调`。上方示例的音量和音调均为 `1`；只写声音名称时，两项均使用 `1`。声音名称需在服务端对应的 Minecraft 版本中存在。

### 标题参数

`title` 使用以下顺序：主标题、副标题、淡入时间、停留时间、淡出时间。含空格的标题用反引号包围：

```yaml
events:
  open:
    - 'title: `&aServer menu` `&7Choose an option` 10 40 10'
```

时间单位为游戏刻；正常情况下 `20` 游戏刻约为 `1` 秒。省略时间时，默认依次为 `15`、`20`、`15` 游戏刻。

### 提示条参数

`bossbar` 依次填写文字、颜色、样式和显示时间：

```yaml
events:
  open:
    - 'bossbar: `&aWelcome to the server` green solid 60'
```

颜色可用 `pink`、`blue`、`red`、`green`、`yellow`、`purple`、`white`；样式可用 `solid`、`segmented_6`、`segmented_10`、`segmented_12`、`segmented_20`。默认颜色为 `white`，样式为 `solid`，显示时间为 `15` 游戏刻。

## 执行命令

| 动作        | 执行身份              | Spigot |
| --------- | ----------------- | ------ |
| `player`  | 点击菜单的玩家，使用玩家已有权限。 | 支持。    |
| `console` | 服务端控制台。           | 支持。    |
| `op`      | 以玩家身份使用管理员权限执行命令。 | 不支持。   |

动作名称后填写命令，通常省略开头的 `/`。

```yaml
backend:
  spawn-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'player: spawn'
```

本例要求服务端已提供 `/spawn`，玩家也必须拥有该命令的权限。ArcMenu 不会创建其他插件的命令。

`console` 和 `op` 应用于由菜单作者确定的命令。控制台命令不会自动以点击者为目标；需要指定玩家时，应使用命令本身的玩家参数，例如 `console: minecraft:give %player_name% minecraft:diamond 1`。

## 菜单导航

| 动作       | 写法              | 用途                          |
| -------- | --------------- | --------------------------- |
| `open`   | `open: welcome` | 打开指定菜单。                     |
| `back`   | `back`          | 返回导航历史中的上一菜单；没有上一菜单时关闭当前菜单。 |
| `close`  | `close`         | 关闭当前菜单。                     |
| `return` | `return`        | 结束当前动作流程，不负责关闭菜单。           |

以上四项均支持 Spigot。`open` 使用目标菜单顶层的 `id`，不是文件名或按钮名称。目标菜单必须已加载，且玩家满足其权限要求。

```yaml
backend:
  welcome-area:
    x: 0
    y: 20
    width: 80
    height: 18
    actions:
      right:
        - 'sound: UI_BUTTON_CLICK-1-1'
        - 'open: welcome'
  back-area:
    x: 0
    y: -20
    width: 80
    height: 18
    actions:
      right: back
```

本例要求已创建并加载[第一个菜单](/arcmenu-wen-dang/ru-men/first-menu.md)中的 `welcome`。导航按钮的显示内容仍需在 `frontend` 中配置。

每一页使用独立菜单，并通过 `open` 跳转。不要使用 `open: welcome:2` 表示第二页。

### 导航参数与扩展应用

Paper、Folia、Leaf 等服务端允许在菜单标识后传递参数，例如 `open: welcome survival`；含空格的单个参数用反引号包围，例如 `` open: welcome `Survival World` `` 。参数供目标菜单的占位符使用，不会自动创建文字或按钮。

这些服务端还支持 `open-app: 命名空间:应用标识`，用于打开其他插件提供的 ArcMenu 应用。只有已安装并提供相应应用的插件才能使用，应用标识及参数应按该插件的说明填写。

Spigot 的 `open` 只支持固定菜单标识，不支持附带参数、通过占位符决定目标或打开扩展应用。

### 跨服连接

`connect: lobby` 请求将玩家连接到代理中名为 `lobby` 的服务器。它需要服务器通过支持 BungeeCord 连接消息的代理连接，目标名称应与代理配置一致。此动作仅适用于 Paper 系服务端，不能代替代理配置。

## 执行顺序与刷新

动作列表通常按书写顺序处理。将消息、声音及命令放在前面，将 `open`、`back` 或 `close` 放在列表末尾，更便于控制操作结果。

* Spigot 成功打开目标菜单，或执行 `back`、`close`、`return` 后，会停止后续动作。
* Paper 系服务端执行导航或关闭动作后，同一列表中的后续即时动作仍可能执行，但后续匹配的点击分组或条件分支会停止处理。
* `return` 用于明确结束当前动作流程；它与返回上一菜单的 `back` 不同。

不要在菜单的打开事件中再次打开自身，也不要在关闭事件中再次关闭自身，以免反复触发事件。

Paper 系服务端可用 `refresh` 更新当前菜单的动态内容，而无需重新打开菜单。`refresh: title` 可更新名为 `title` 的文字元素；也可指定当前指向区域的名称来刷新提示文字。此动作不读取磁盘上的新配置，修改菜单文件后仍需执行 `/arcmenu reload`。

`animation: 动画标识` 播放当前菜单绑定的轨道，`stop-animation: 动画标识` 停止指定轨道。配置见[动画时间线与轨道](/arcmenu-wen-dang/gong-neng-pei-zhi/animations.md)。Spigot 不支持刷新与动画动作。

## 动作附加选项

附加选项写在单条动作字符串中，与区域属性不同。

| 选项                                   | 用途                                 | Spigot |
| ------------------------------------ | ---------------------------------- | ------ |
| `{chance=0.5}`                       | 以 `50%` 的概率执行本条动作；数值范围为 `0` 至 `1`。 | 支持。    |
| `{condition=perm myserver.menu.vip}` | 仅在满足指定条件时执行本条动作。                   | 支持。    |
| `{delay=20}`                         | 延后 `20` 游戏刻执行本条动作。                 | 不支持。   |
| `{players}`                          | 对所有在线玩家执行本条动作。                     | 不支持。   |
| `{players=perm myserver.notice}`     | 对满足条件的在线玩家执行本条动作。                  | 不支持。   |

概率或条件未通过时，只跳过该动作，不会自动执行区域的 `deny`。更完整的条件配置见[条件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/conditions.md)。

### 单条延迟与后续延迟

`{delay=20}` 只延迟所在动作，不会让下一条动作等待。若要延迟列表中后续所有动作，使用独立的 `delay`：

```yaml
events:
  open:
    - 'tell: &aMenu opened.'
    - 'delay: 20'
    - 'tell: &7One second later.'
    - 'delay: 20'
    - 'tell: &7Two seconds later.'
```

独立 `delay` 的时间会累加。玩家在等待期间关闭或切换菜单后，原菜单中尚未执行的延迟动作不会继续执行。不要将必须完成的操作放在关闭菜单之后的延迟动作中。

### 执行对象

动作默认针对触发菜单操作的玩家。`{players}` 和带条件的 `{players=...}` 会改变执行对象；动作文字中的玩家占位符仍以最初触发操作的玩家为准。

例如 `tell: &aA player opened the menu. {players}` 会向所有在线玩家发送消息。若使用 `{players=perm myserver.notice}`，则只发送给拥有该权限的在线玩家。

## 检查与后续配置

修改后执行 `/arcmenu validate` 和 `/arcmenu reload`，再正常打开菜单检查命令权限、导航目标、返回路径和延迟动作。预览模式不执行交互动作。

数据存取、菜单参数修改、余额、物品与聊天输入动作见[进阶动作](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/advanced-actions.md)。相关插件的前提见[平台与插件兼容性](/arcmenu-wen-dang/pei-zhi-yu-guan-li/compatibility.md)。