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

# 提示框

提示框（Tooltip）可以在玩家将准星或鼠标指向某个按钮区域时，即时浮现一段说明文字。你无需让玩家先点击按钮，就能展示功能介绍、价格条件或实时变化的个人数据。

提示框的具体文字写在各个菜单的 `backend` 交互区域里，而提示框的整体外观、字号和背景皮肤则在 `plugins/ArcMenu/tooltip.yml` 中统一配置。

## 在交互区域中添加提示文字

在菜单配置文件的 `backend` 下，为任意交互区域加上 `tooltip` 和可选的 `update` 字段即可开启提示框：

```yaml
backend:
  information-area:
    x: 0
    y: 0
    width: 80
    height: 24
    tooltip:
      - '&f服务器指南'
      - '&7当前玩家：%player_name%'
      - '&e右键查看详细说明'
    update: 20
    actions:
      right:
        - 'tell: &a已为你打开详细说明。'
```

这两个字段的填写规则如下：

| 字段        | 填写内容与有效值                                                                            |
| --------- | ----------------------------------------------------------------------------------- |
| `tooltip` | 可填写单行字符串，或填写多行字符串列表（列表中的每一项显示为一行）。支持传统颜色代码、十六进制颜色与 PlaceholderAPI 占位符。              |
| `update`  | 提示文字的定时刷新间隔，单位为游戏刻（`20` 刻约为 1 秒）。可填写正整数（如 `20`），或填写 `-1` 表示不定时刷新。默认值为 `-1`，不接受 `0`。 |

当玩家把指针移入该区域时，提示框会自动显示并解析占位符；移出区域时立即隐藏。如果多个交互区域发生重叠，画面上会显示当前实际命中的那个区域的提示内容。

如果提示框里包含随时间变化的占位符（例如冷却倒计时或实时余额），可以把 `update` 设为正整数让它在玩家悬停期间自动刷新；你也可以在按钮动作中使用 `refresh: 区域名称` 手动刷新当前指向区域的提示文字。关于如何根据条件改变区域行为，可参考[条件](/cai-dan-pei-zhi/menus/conditions.md)。

## 配置提示框外观（`tooltip.yml`）

`plugins/ArcMenu/tooltip.yml` 负责管理所有菜单的提示框样式。文件顶层分为 `touch`（触控模式）和 `mouse`（鼠标模式与 Vision 模式）两个配置节，你可以为不同操作方式设置各自的字号与偏移位置。

如果你在文件中完全省略了 `mouse` 配置节，鼠标模式会直接继承 `touch` 的整套外观与皮肤设置。

### 基础属性与纯色背景

如果不使用图片皮肤，提示框会使用纯色半透明背景。下面是一个简洁的纯色背景配置示例：

```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` 配置节删掉即可。

每个模式下可以配置以下基础字段：

| 字段           | 填写内容与有效值                                                                                                                  |
| ------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `offset`     | 提示框相对于指向位置的偏移量，包含 `x`、`y`、`z` 三个有限数值。`x` 正值向右，`y` 正值向上，`z` 正值朝玩家方向前移。                                                     |
| `anchor`     | 提示框对齐到“指向位置 + 偏移量”的基准角。可选值：`top-left`、`top-right`、`bottom-left`、`bottom-right`。省略时默认为 `bottom-left`（内置配置文件设为 `top-left`）。 |
| `wrap`       | 是否按 `line-width` 自动折行，填写布尔值 `true` 或 `false`，默认为 `false`。                                                                 |
| `size`       | 提示框文字的缩放大小，填写大于 `0` 的数值。                                                                                                  |
| `line-width` | 开启自动折行时的单行最大宽度，填写大于 `0` 的整数，单位为文字像素（默认 `180`）。                                                                            |
| `background` | 未配置 `skin` 时的纯色背景，填写带引号的 8 位十六进制颜色 `'#AARRGGBB'`。前两位 `AA` 为透明度（`00` 全透明，`FF` 不透明），例如 `'#D0101010'` 为深色半透明。                |
| `skin`       | 可选的九宫格图片背景配置节。配置后会自动替代 `background` 纯色背景。                                                                                 |

### 对齐基准与文字换行

触控模式以准星落点作为对齐起点，鼠标模式以光标尖端作为起点。`anchor` 决定了提示框的哪一个角被固定在这个起点上，以及当文字变长、行数变多时提示框向哪个方向延展：

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

当 `wrap` 设为 `false` 时，`tooltip` 列表里的每一项都会保持在单独一行内，不会自动折行；如果你想自己控制分行位置，直接把文字拆成多行列表最为直观。当 `wrap` 设为 `true` 时，超出 `line-width` 文字像素宽度的长句会自动换行。注意 `line-width` 使用的是字体像素单位，与菜单画布的坐标宽度不是同一单位。

## 九宫格图片背景（`skin`）

通过配置 `skin`，你可以用自定义 PNG 图片为提示框绘制精致的面板与边框。ArcMenu 会采用九宫格（Nine-Slice）切分方式：保持图片四个角的造型不变，根据提示文字的实际宽高自动拉伸四条边与中心区域。

将以下 `skin` 配置节放在 `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}
```

上方示例使用的是首次安装附带的 `/ce/topaz_background.png` 和 `/ce/topaz_frame.png`，文件位于 `plugins/ArcMenu/images/ce/`。图片路径的书写规则与普通菜单图片完全一致，详见[图片与资源包](/gong-neng-pei-zhi/resource-packs.md)。

### 贴图切分与尺寸字段

| 字段            | 填写内容与有效值                                                                    |
| ------------- | --------------------------------------------------------------------------- |
| `background`  | 必填。背景底图 PNG 的路径（如 `/ce/topaz_background.png`）。                              |
| `frame`       | 可选。叠加在背景上的边框 PNG 路径；填写时，其原图像素宽高必须与 `background` 完全一致。                       |
| `border`      | 九宫格切分时四边保留的像素宽度，填写大于 `0` 的整数（默认 `8`）。该值必须小于原图宽度的一半，且小于原图高度的一半。              |
| `padding`     | 文字内容与背景四周边缘的内边距，包含 `left`、`right`、`top`、`bottom` 四个非负整数，单位为提示文字像素。          |
| `min-size`    | 提示框背景的最小宽高，包含整数 `width` 和 `height`（单位为提示文字像素）。每一项都必须大于或等于 `2 × border + 1`。 |
| `size-adjust` | 在自动测算的尺寸基础上额外增减宽高，包含整数 `width` 和 `height`。调整后的最小宽高依然不能低于 `2 × border + 1`。  |

在这里，`border` 按原始 PNG 文件的像素计算；而 `padding`、`min-size` 和 `size-adjust` 则按提示文字像素计算，会随模式下的 `size` 和皮肤的 `scale` 一起缩放。比如当 `border: 8` 时，原图宽高至少需要 `17` 像素，且 `min-size` 的宽高至少为 `17`（示例设为 `24` 以留出充裕的边距）。

### 背景与文字的独立位置调整

当你需要单独微调背景图与文字之间的层次或对齐关系时，可以使用 `skin` 下的这三个字段：

| 字段            | 子字段         | 填写内容与有效值                                                              |
| ------------- | ----------- | --------------------------------------------------------------------- |
| `offset`      | `x`、`y`、`z` | 仅移动图片背景，不移动提示文字。`x`、`y` 使用菜单坐标单位，`z` 使用深度单位（默认 `z: -0.25`，使背景处于文字后方）。 |
| `scale`       | `x`、`y`     | 图片背景的横向与纵向缩放倍率，填写大于 `0` 的数值（默认均为 `1.0`）。                              |
| `text-offset` | `x`、`y`、`z` | 仅微调提示文字的位置，不移动图片背景。各轴默认为 `0`。                                         |

请注意区分模式顶层的 `offset` 与 `skin.offset`：模式顶层的 `offset` 会把整个提示框（文字连同背景）一起移动，而 `skin.offset` 只平移背景图层。

### 九宫格拼接细节微调

`skin` 下还提供了一组可选的字形拼接微调参数，单位均为提示文字像素。日常使用保持默认的 `0` 即可；如果自定义贴图在特定缩放比例下出现细微接缝，可以按需调整：

| 字段              | 子字段                     | 填写内容与有效值                                  |
| --------------- | ----------------------- | ----------------------------------------- |
| `seam-overlap`  | `x`、`y`                 | 相邻九宫格切片之间的重叠像素量，用于消除拼接缝隙，填写大于或等于 `0` 的数值。 |
| `glyph-offset`  | `x`、`y`                 | 九宫格全套字形的整体位置偏移，填写有限数值。                    |
| `column-offset` | `left`、`center`、`right` | 分别微调左、中、右三列切片的水平位置，填写有限数值。                |
| `row-offset`    | `top`、`center`、`bottom` | 分别微调上、中、下三行切片的垂直位置，填写有限数值。                |

## 重载与生效

* 如果只修改了菜单里的 `tooltip` 文字、`update` 刷新间隔，或者调整了 `tooltip.yml` 中的偏移、字号、边距等数值，执行 `/arcmenu reload` 即可生效。
* 如果你在 `skin` 中更换了新的 PNG 贴图，或者修改了 `border` 切分宽度，需要重新生成资源包：配合自定义内容插件时执行 `/arcmenu resources` 后运行对应的打包命令（如 `/ce reload pack`、`/nexo reload pack` 或 `/iazip`），独立分发时执行 `/arcmenu reload all`。


---

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