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

# 动作与导航

当玩家点击按钮、将准星或光标移入移出交互区域，或者打开、关闭菜单时，菜单可以通过“动作”作出响应。小到播放一声按键音效、发送一条欢迎消息，大到执行命令、切换页面或播放动画，都通过动作来完成。

## 基本写法

带参数的动作写成 `动作名称: 参数`，不带参数的动作直接写名称即可（如 `close`、`back`）。如果一个事件需要触发多步操作，把它们写成 YAML 列表，菜单会按从上到下的顺序依次执行：

```yaml
actions:
  right:
    - 'sound: UI_BUTTON_CLICK-1-1'
    - 'tell: &a欢迎，%player_name%！'
    - 'open: details'
```

除了写在交互区域的 `actions`、`deny`、`on-hover`、`on-leave` 中，动作也可以写在菜单顶层的 `events.open` 和 `events.close` 下。

如果你习惯把几条简短动作写在同一行，可以用 `_||_` 或 `&&&` 把它们连接起来，例如 `'sound: UI_BUTTON_CLICK-1-1 &&& open: details'`。

## 消息与声音

给玩家提供即时反馈是最常见的需求。下面这些动作只对当前触发事件的玩家生效（除非额外附加了全体玩家选项）：

| 动作          | 写法示例                                      | 参数与可填值说明                                                                                                                                                                |
| ----------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tell`      | `tell: &a欢迎！`                             | 向聊天栏发送普通文本。支持 `&` 颜色代码与占位符，可用 `\n` 分成多行发送。（别名：`message`、`msg`、`talk`）                                                                                                   |
| `tellraw`   | `tellraw: {"text":"欢迎！","color":"green"}` | 发送富文本消息。可填写标准 Minecraft JSON 文本组件，或使用 `<文字@hover=提示@command=/spawn>` 简写语法（支持 `hover`、`suggest`、`command`/`execute`、`url`/`open_url`）。（别名：`json`）                        |
| `chat`      | `chat: 大家好！`                              | 让当前玩家直接以自己的身份向聊天栏发送一句话。（别名：`send`、`say`）                                                                                                                                |
| `actionbar` | `actionbar: &a准备好了`                       | 在快捷栏正上方显示单行提示文字。（别名：`action`）                                                                                                                                           |
| `sound`     | `sound: UI_BUTTON_CLICK-1-1`              | 播放音效。格式为 `声音名称` 或 `声音名称-音量-音调`。声音可写 Bukkit 枚举名（如 `UI_BUTTON_CLICK`）或原版命名空间键（如 `minecraft:ui.button.click`）；音量填非负小数（默认 `1`），音调填 `0` 到 `2` 之间的小数（默认 `1`）。多条音效可用分号 `;` 隔开。 |
| `title`     | 见下方说明                                     | 在屏幕中央显示大标题和副标题。                                                                                                                                                         |
| `bossbar`   | 见下方说明                                     | 在屏幕顶部显示一条限时 BossBar 提示条。                                                                                                                                                |

### 标题与顶部提示条

`title` 和 `bossbar` 包含多个以空格分隔的参数。如果标题或提示条文字本身带有空格，需要用反引号 `` ` `` 把那一段文字包起来：

```yaml
events:
  open:
    - 'title: `&a服务器菜单` `&7选择一项功能` 10 40 10'
    - 'bossbar: `&a欢迎来到服务器` green solid 60'
```

* **`title` 参数顺序**：`主标题 副标题 [淡入] [停留] [淡出]`。 后三个时间参数为可选整数，单位是游戏刻（tick，正常服务器速度下 `20` 游戏刻约为 1 秒）。不填时默认使用 `15`、`20`、`15`。如果只想显示副标题，主标题位置可以写一对空反引号 \`\`。
* **`bossbar` 参数顺序**：`文本 [颜色] [样式] [停留时间]`。
  * **颜色**（可选，默认 `white`）：可填 `pink`、`blue`、`red`、`green`、`yellow`、`purple` 或 `white`。
  * **样式**（可选，默认 `solid`）：可填单条实心 `solid`，或分段样式 `segmented_6`、`segmented_10`、`segmented_12`、`segmented_20`（也可简写为 `6`、`10`、`12`、`20`）。
  * **停留时间**（可选，默认 `15`）：填写正整数游戏刻，到期后自动隐藏。

## 执行命令

菜单可以代替玩家或控制台执行服务器命令。命令开头的 `/` 可以省略；如果要连续执行多条命令，既可以分成多行动作，也可以在同一行内用分号 `;` 隔开。

| 动作        | 执行身份    | 写法示例与说明                                                                                                                                          |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `player`  | 当前玩家    | <p><code>player: spawn</code><br>完全按照玩家自身拥有的权限执行命令。（别名：<code>command</code>、<code>cmd</code>、<code>execute</code>）</p>                           |
| `console` | 服务器控制台  | <p><code>console: minecraft:give %player\_name% minecraft:diamond 1</code><br>由后台执行，不受玩家自身权限限制。需要指定目标玩家时，在命令中填入 <code>%player\_name%</code>。</p> |
| `op`      | 临时管理员身份 | <p><code>op: 某个玩家命令</code><br>执行瞬间临时赋予玩家 OP 权限，执行完毕后立即恢复原状。适合必须由玩家本人发起、但又不希望平时开放权限的命令。</p>                                                       |

## 菜单导航与流程控制

当你的菜单包含多个页面（例如主菜单、商店分类页、确认弹窗）时，每个页面都是一个独立的菜单配置文件，通过导航动作串联在一起。在同一个会话中切换菜单时，新页面会直接沿用首次打开菜单时的屏幕锚点位置，不会因为玩家中途轻微转头而发生跳动。

| 动作         | 写法示例                      | 用途与可填值                                                                          |
| ---------- | ------------------------- | ------------------------------------------------------------------------------- |
| `open`     | `open: welcome`           | 打开指定 ID 的菜单。目标 ID 可填小写字母、数字、下划线或连字符，也支持用占位符动态拼接。（别名：`gui`、`menu`、`open-gui`）    |
| `open-app` | `open-app: myplugin:shop` | 打开由第三方插件通过开发者 API 注册的应用页面。应用 ID 格式固定为 `命名空间:路径`。                                |
| `back`     | `back`                    | 不带参数。返回当前会话中的上一个页面；如果当前已经是第一页，则直接关闭菜单。                                          |
| `close`    | `close`                   | 不带参数。关闭当前打开的菜单并清空返回历史。（别名：`shut`、`force-close`、`silent-close`）                  |
| `connect`  | `connect: lobby`          | 将玩家跨服传送到代理端（BungeeCord / Velocity）下的指定子服，参数填写代理端配置的服务器名称。（别名：`bungee`、`server`） |
| `return`   | `return`                  | 不带参数。立即停止当前动作列表，不再往下执行后续动作。（别名：`break`）                                         |

### 页面传参

`open` 和 `open-app` 都支持在目标 ID 后面附加参数，多个参数之间用空格隔开；如果单个参数内部包含空格，用反引号 `` ` `` 包起来：

```yaml
actions:
  right: 'open: world-detail survival `生存世界`'
```

打开 `world-detail` 后，目标菜单里可以直接用 `{0}` 读取 `survival`，用 `{1}` 读取 `生存世界`。关于参数的更多用法，可以参考[占位符与文字格式](/wen-zi-ge-shi/text-placeholders.md)以及[进阶动作](/cai-dan-pei-zhi/menus/advanced-actions.md)。

## 动态刷新与动画

当你在点击动作里修改了玩家数据或余额，并希望当前画面上的文字、图片（包括设为 `update: -1` 的非自动轮询节点）或提示框立刻更新显示时，可以使用刷新动作（底层与开发者 API 的 `refresh` 走同一套运行逻辑）；如果菜单配置了时间线动画，也可以通过动作随时启停：

* **`refresh`**：不带参数（或写 `refresh: *`）时，刷新当前菜单里所有的文本节点、图片节点（含图像源与内容）以及当前悬浮的提示框。
* **`refresh: 目标ID`**：只刷新指定的单个或多个目标（多个 ID 用分号 `;` 隔开）。目标 ID 可以填前端 `text` 或 `image` 节点的 ID（即使节点设为 `update: -1` 也会立即重算并重绘），也可以填后端交互区域的 ID（当玩家正指向该区域时，立即刷新其悬浮提示框）。
* **`animation: 动画ID`**：播放当前菜单绑定的指定时间线动画（别名：`animate`、`play-animation`）。
* **`stop-animation: 动画ID`**：停止指定动画并恢复元素的初始状态（别名：`cancel-animation`）。将播放与停止动作分别放进交互区域的 `on-hover` 和 `on-leave` 中，就能做出丝滑的悬停动效。

## 延迟、概率、单条条件与目标玩家

在任何单条动作字符串的末尾，你都可以附加大括号选项 `{...}`，用来控制这一条动作的触发时机、概率、前置条件或作用对象：

| 附加选项             | 写法示例                                    | 参数取值与效果                                                                                |
| ---------------- | --------------------------------------- | -------------------------------------------------------------------------------------- |
| `{delay=刻数}`     | `tell: &a你好 {delay=20}`                 | 将这一条动作延后指定游戏刻执行，填入非负整数（别名：`wait`）。                                                     |
| `{chance=概率}`    | `give-money: 10 {chance=0.5}`           | 按概率执行这一条动作，填入 `0` 到 `1` 之间的小数（如 `0.5` 代表 50% 概率；别名：`rate`、`rand`、`random`）。            |
| `{condition=条件}` | `tell: &aVIP你好 {condition=perm my.vip}` | 只有满足条件表达式时才执行这一条动作（别名：`requirement`）。条件语法详见[条件](/cai-dan-pei-zhi/menus/conditions.md)。 |
| `{players}`      | `tell: &e全服广播 {players}`                | 对当前所有在线玩家执行这一条动作。                                                                      |
| `{players=条件}`   | `tell: &e通知 {players=perm my.staff}`    | 筛选出所有满足条件的在线玩家，并对他们执行这一条动作。                                                            |

### 独立延迟与单条延迟的区别

除了写在单条动作末尾的 `{delay=20}`，你也可以在动作列表里单独写一行 `delay: 刻数`（支持占位符）：

```yaml
events:
  open:
    - 'tell: &a菜单已打开。'
    - 'delay: 20'
    - 'tell: &7一秒后显示的消息。'
    - 'delay: 20'
    - 'tell: &7两秒后显示的消息。'
```

* **独立 `delay: 20`**：会把列表里排在它后面的**所有**动作整体往后推迟 20 游戏刻，多次出现的独立 `delay` 会继续累加。
* **行尾 `{delay=20}`**：只推迟当前这一行动作本身，不影响下一行动作的执行时间。

当玩家关闭菜单或切换到其他菜单页面时，原先页面里尚未到期的延迟动作会自动取消，不会在玩家退出菜单后突然冒出来。

### 导航动作后的执行顺序

在动作列表中，`open`、`back`、`close` 会改变当前会话状态，但同一个列表里紧跟在它们后面的即时动作仍然会继续跑完（例如先写 `close` 再写 `tell: &7再见`，消息依然会发出）。如果你在多分支判断中希望在某处彻底截断后续动作，请在后面加上一行 `return`。

掌握了基础动作后，如果你需要在菜单里存取自定义变量、扣款发奖、操作背包物品或捕获玩家聊天输入，请继续阅读[进阶动作](/cai-dan-pei-zhi/menus/advanced-actions.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/actions.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.