> 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/wen-zi-ge-shi/text-placeholders.md).

# 占位符与文字格式

占位符将玩家信息、菜单参数或保存的数据放入文字中。它们可用于前端文字、提示框、动作参数和条件；图片路径只支持符合路径规则的占位符写法。

## 内置玩家占位符

| 占位符                                    | 内容        | Spigot |
| -------------------------------------- | --------- | ------ |
| `%player_name%`                        | 玩家名称。     | 支持。    |
| `%player_uuid%`                        | 玩家 UUID。  | 支持。    |
| `%player_world%`                       | 玩家所在世界名称。 | 不支持。   |
| `%player_x%`、`%player_y%`、`%player_z%` | 玩家坐标。     | 支持。    |

这些占位符无需 PlaceholderAPI。Paper 系服务端的坐标显示保留两位小数；不要依赖不同平台输出完全相同的文字格式。

```yaml
frontend:
  player-information:
    type: text
    content: '&fPlayer: %player_name%'
    size: 4
    update: 20
    offset: {x: 0, y: 20, z: 1}
```

将片段加入已有菜单。`update` 为正整数时定时更新文字，单位为游戏刻；`-1` 表示不定时刷新。静态文字通常无需刷新，坐标、余额等变化内容应按需求设置间隔。

定时刷新仅适用于 Paper 系服务端。Spigot 在打开菜单时显示文字，不提供定时刷新。

## 玩家数据与菜单参数

以下写法仅适用于 Paper、Folia、Leaf 等服务端。

| 简写                          | 对应写法                                  | 内容           |
| --------------------------- | ------------------------------------- | ------------ |
| `{meta:selected-world}`     | `%arcmenu_meta_selected-world%`       | 玩家临时数据。      |
| `{data:preferred-world}`    | `%arcmenu_data_preferred-world%`      | 玩家保存数据。      |
| `{globaldata:event-status}` | `%arcmenu_globaldata_event-status%`   | 全服共享数据。      |
| `{0}`、`{1}`                 | `%arcmenu_args_0%`、`%arcmenu_args_1%` | 第一个、第二个菜单参数。 |

参数从 `0` 开始编号，使用 `open: 菜单标识 参数...` 传入，或通过 `set-args` 修改。写入、清除与保留范围见[进阶动作](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/advanced-actions.md)。

未设置的数据显示 `null`。不存在的 `{编号}` 保留原文字，对应 `%arcmenu_args_编号%` 显示 `null`。需要默认说明时，应通过条件选择合适内容，而不是假定未设置的值为空或为 `0`。

聊天输入可用 `{meta:input}` 或 `{meta:input-阶段名称}` 读取；完整流程见[聊天输入](https://simple.superiormc.cn/arcmenu-wen-dang/wen-zi-ge-shi/pages/g5EbV05dwvvC3VQbnSrc#聊天输入)。

这些写法由 ArcMenu 在自身菜单和动作中处理，不代表其他插件也能直接识别它们。

## PlaceholderAPI

Paper 系服务端可通过 PlaceholderAPI 使用其他插件提供的占位符。除了安装 PlaceholderAPI，还需按占位符提供者的说明安装所需扩展或插件。

先确认占位符实际返回预期内容，再放入菜单。不同经济、等级或统计插件的占位符名称不同，不能仅根据用途猜测名称。Spigot 不支持这项联动。

占位符未被识别时可能保留原文字。尤其在[条件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/conditions.md)中比较余额或数量时，应检查实际结果，不能把未解析内容当作数值。

## 颜色与样式

菜单文字和普通消息使用 `&` 颜色代码，建议将 YAML 文字保留在引号中。

| 写法                  | 效果           |
| ------------------- | ------------ |
| `&f`、`&7`、`&a`、`&c` | 白色、灰色、绿色、红色。 |
| `&l`                | 粗体。          |
| `&o`                | 斜体。          |
| `&n`                | 下划线。         |
| `&r`                | 恢复默认颜色与样式。   |

例如 `'&a&lWelcome! &r&7Choose an option.'`。切换颜色时应留意前面的样式是否仍符合预期，需要重置时使用 `&r`。

前端文字的 `font` 用于选择字体，默认 `minecraft:default`。自定义字体需要玩家资源包提供对应字体；填写字体名称不会自动安装字体。普通 `content` 不应按 MiniMessage 标签或 JSON 消息编写。

Spigot 仅支持默认字体。

前端矩形、图片着色与提示框背景使用各自的颜色字段，不能用 `&a` 代替。提示框背景要求八位 `'#AARRGGBB'`，其他字段见对应参考页。

## 带交互的聊天文字

Paper 系服务端的 `tellraw` 可发送 JSON 聊天文字，适合悬停说明或点击链接。它用于聊天消息，不是前端文字的 `content` 格式。

例如：`tellraw: {"text":"Menu information","color":"green"}`。放入 YAML 动作列表时，使用外层单引号保留 JSON 的双引号。命令和动作位置见[动作与导航](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/actions.md)。

## 检查与加载

修改后执行 `/arcmenu validate` 和 `/arcmenu reload`。用普通玩家账号检查占位符、字体、颜色及定时更新；涉及自定义字体或动态图片时，还需检查最新资源包是否加载。

插件提示的语言设置不会自动翻译菜单作者填写的文字，相关区别见[语言管理](/arcmenu-wen-dang/gong-neng-pei-zhi/languages.md)。