> 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/gong-neng-pei-zhi/tooltips.md).

# 提示框

提示框在玩家指向交互区域时显示说明文字，不需要先点击。适用于按钮用途、操作提示和动态玩家信息。

此功能适用于 Paper、Folia、Leaf 等服务端，Spigot 不显示提示框。提示内容写在菜单的 `backend` 中，外观统一在 `plugins/ArcMenu/tooltip.yml` 中设置。

## 区域中的提示内容

层级为：**`backend` → 区域名称 → `tooltip` 与 `update`**。

```yaml
backend:
  information-area:
    x: 0
    y: 0
    width: 80
    height: 24
    tooltip:
      - '&fServer information'
      - '&7Player: %player_name%'
      - '&eRight-click to view details.'
    update: 20
    actions:
      right:
        - 'tell: &aDetails requested.'
```

这是菜单片段，需合并到已有菜单；对应按钮的显示内容仍在 `frontend` 中配置。

| 字段        | 用途                                        |
| --------- | ----------------------------------------- |
| `tooltip` | 一行文字或文字列表。列表中的每项为一行，支持颜色代码与占位符。           |
| `update`  | 提示文字定时刷新间隔，单位为游戏刻；`-1` 表示不定时刷新，正整数表示刷新间隔。 |

`update` 省略时为 `-1`，不接受 `0`。正常情况下 `20` 游戏刻约为 `1` 秒。玩家指向新区域时会更新提示；需要在停留期间显示变化的数据时，可设置刷新间隔，或使用 `refresh: 区域名称` 刷新当前指向区域的提示。

移出交互区域，或指向没有提示文字的区域时，提示框隐藏。多个区域重叠时，只显示选中区域的提示；即使该区域没有提示，也不会继续读取下层区域。

区域的 `condition` 控制点击动作，不会自动隐藏提示。提示文字不表示玩家已具备执行操作的权限，相关规则见[条件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/conditions.md)。

## 外观文件的结构

`tooltip.yml` 的顶层分别为 `touch` 和 `mouse`，用于触摸模式与鼠标模式。两者可以使用不同的大小、位置和背景，设置作用于该模式下的所有菜单。

若完全省略 `mouse` 配置节，鼠标模式继承触摸模式的整套外观。已有 `mouse` 配置节时，应直接修改其中的字段。

以下示例使用普通颜色背景，不使用图片背景：

```yaml
touch:
  offset: {x: 6, y: 4.27, z: 5}
  anchor: top-left
  wrap: false
  size: 2.989
  line-width: 180
  background: '#D0101010'

mouse:
  offset: {x: 6, y: 4.27, z: 5}
  anchor: top-left
  wrap: false
  size: 4.375
  line-width: 180
  background: '#D0101010'
```

内置配置包含图片背景的 `skin`。若改用上方普通背景，应删除对应模式下的整个 `skin` 配置节；仅修改 `background` 不会取消图片背景。

### 模式属性

以下字段位于 `touch` 或 `mouse` 下，处于同一层级。

| 字段           | 用途                                         |
| ------------ | ------------------------------------------ |
| `offset`     | 提示框相对于指向位置的偏移，包含 `x`、`y`、`z`。              |
| `anchor`     | 将提示框的哪一个角对齐到指向位置加偏移的位置。                    |
| `wrap`       | 是否按 `line-width` 自动换行，使用 `true` 或 `false`。 |
| `size`       | 提示文字大小，必须大于 `0`。                           |
| `line-width` | 自动换行的行宽，使用大于 `0` 的整数，单位为文字像素。              |
| `background` | 普通背景颜色，使用带透明度的 `'#AARRGGBB'`。              |
| `skin`       | 可选的图片背景配置，见下方。                             |

### 位置与对齐

触摸模式以准星指向位置为基准，鼠标模式以光标尖端为基准。`offset.x` 正值向右，`offset.y` 正值向上，`offset.z` 正值向玩家方向；横纵偏移使用菜单坐标单位。

| `anchor`       | 固定的角 | 提示框展开方向 |
| -------------- | ---- | ------- |
| `top-left`     | 左上角。 | 向右、向下。  |
| `top-right`    | 右上角。 | 向左、向下。  |
| `bottom-left`  | 左下角。 | 向右、向上。  |
| `bottom-right` | 右下角。 | 向左、向上。  |

根据按钮位置选择展开方向，避免长提示遮住按钮或超出屏幕。文字长度改变时，所选的角仍作为对齐基准。

### 文字与普通背景

`wrap: false` 时，每项列表文字占一行，不按 `line-width` 自动换行。需要控制多行内容时，优先使用 `tooltip` 文字列表。`wrap: true` 时，长行可按指定宽度换行。

`line-width` 使用文字像素，与区域的 `width` 不是同一种单位。修改 `size` 会同时影响文字显示大小；较长文字和不同字体应在实际客户端中检查。

`background` 必须保留八位十六进制颜色与引号，前两位 `AA` 表示透明度：`00` 为全透明，`FF` 为完全不透明。例如 `'#D0101010'` 为带透明度的深色背景。这里不使用前端矩形的六位颜色写法。

## 图片背景：`skin`

图片背景根据文字内容调整大小，四角保持形状，边缘与中心随提示框伸展。图片路径使用与菜单图片相同的规则，详见[图片与资源包](/arcmenu-wen-dang/gong-neng-pei-zhi/resource-packs.md)。

以下片段合并到 `tooltip.yml` 的 `touch` 下；鼠标模式可在 `mouse` 下配置相同结构：

```yaml
touch:
  skin:
    background: /ce/topaz_background.png
    frame: /ce/topaz_frame.png
    border: 8
    padding: {left: 8, right: 8, top: 8, bottom: 8}
    min-size: {width: 24, height: 24}
    size-adjust: {width: 0, height: 0}
    offset: {x: 0, y: 0, z: -0.25}
    scale: {x: 1.0, y: 1.0}
    text-offset: {x: 0, y: 0, z: 0}
```

示例引用插件自带的图片，不要求安装 CraftEngine。图片位于 `images/ce/`，玩家仍需加载包含这些资源的资源包。

配置 `skin` 时，图片代替模式属性中的普通 `background` 颜色。删除整个 `skin` 配置节可恢复普通颜色背景。

### 图片与尺寸

以下属性位于 `skin` 下。

| 字段            | 用途与要求                                                    |
| ------------- | -------------------------------------------------------- |
| `background`  | 背景 PNG 路径，必须填写且图片存在。                                     |
| `frame`       | 可选边框 PNG 路径。填写时图片必须存在，且宽高与背景图一致。                         |
| `border`      | 原图四边保留的边缘宽度，使用正整数像素；必须小于原图宽度和高度的一半。                      |
| `padding`     | 文字与背景边缘的内侧间距，包含 `left`、`right`、`top`、`bottom`，各为非负整数。    |
| `min-size`    | 提示框最小尺寸，包含整数 `width` 与 `height`；每项至少为 `2 × border + 1`。  |
| `size-adjust` | 在自动计算尺寸上增减宽高，包含整数 `width` 与 `height`；调整后不能使最小尺寸低于上述边缘要求。 |

`border` 使用原 PNG 像素。`padding`、`min-size` 和 `size-adjust` 使用提示文字像素，会随文字大小和图片背景缩放影响实际显示。

内置示例 `border: 8` 要求原图宽高均大于 `16` 像素，最小提示框宽高至少为 `17`。示例使用 `24`，为文字和边缘留出空间。

背景图或边框缺失会导致资源重建失败，不会像普通菜单图片一样仅隐藏缺失元素。

### 背景与文字的位置

| 字段            | 子字段         | 用途                                 |
| ------------- | ----------- | ---------------------------------- |
| `offset`      | `x`、`y`、`z` | 调整图片背景相对于原位置的偏移，不同时移动文字。           |
| `scale`       | `x`、`y`     | 图片背景的横纵缩放，必须大于 `0`；也影响文字在背景内的布局间距。 |
| `text-offset` | `x`、`y`、`z` | 单独微调文字位置，不移动背景。                    |

`skin.offset` 与 `skin.text-offset` 使用菜单坐标单位及前后层次。模式下的 `offset` 移动整个提示框，`skin.offset` 只调整图片背景，两者不是同一字段。

背景缩放不会代替模式下的 `size` 修改文字大小。需要放大整套提示时，先调整 `size`，再检查内侧间距与边缘效果。

### 图片拼接微调

内置配置还提供以下可选字段，均位于 `skin` 下。普通使用可保留 `0`，只有自定义背景出现缝隙或对齐问题时再调整。

| 字段              | 子字段                     | 用途                        |
| --------------- | ----------------------- | ------------------------- |
| `seam-overlap`  | `x`、`y`                 | 增加相邻图片部分的重叠量，用于减少缝隙，必须非负。 |
| `glyph-offset`  | `x`、`y`                 | 图片各部分的整体位置微调。             |
| `column-offset` | `left`、`center`、`right` | 分别微调左、中、右三列的位置。           |
| `row-offset`    | `top`、`center`、`bottom` | 分别微调上、中、下三行的位置。           |

这些微调使用提示文字像素，会随 `size` 与 `skin.scale` 缩放。它们不改变点击区域，也不移动提示文字。

## 加载与检查

只修改菜单提示内容、刷新间隔或现有背景的位置等设置时，执行 `/arcmenu validate` 和 `/arcmenu reload`，重新打开菜单检查。

新增或更换图片背景，修改 `skin.background`、`skin.frame`、`skin.border`，或修改 PNG 文件时，使用 `/arcmenu reload all` 并让玩家加载更新后的资源包。CraftEngine 的重建与分发流程见[图片与资源包](/arcmenu-wen-dang/gong-neng-pei-zhi/resource-packs.md)。

两种模式应分别通过正常打开的菜单检查：

* 指向区域时显示提示，移出时隐藏。
* 多行文字、占位符与定时刷新符合预期。
* 所选对齐角与偏移不会遮住主要操作内容。
* 图片边缘、文字间距与长提示显示正常。

预览模式不用于检查完整提示交互。若提示未出现，先检查区域是否被其他区域遮挡、是否配置 `tooltip`，以及当前是否为 Spigot；图片外观异常时再检查资源包。