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

# Arcitx 文本输入

Arcitx 是 ArcMenu 内置的文本输入组件，用来在菜单里收集玩家输入的文字（例如搜索关键词、转账金额、兑换码或自定义昵称）。

在菜单结构上，一个完整的 Arcitx 输入框由三个相互配合的部分组成：

1. **前端文字节点（`type: text`）**：负责在菜单画面上显示提示语、正在输入的文字、闪烁光标以及最终的草稿或提交内容。
2. **后端编辑区域（`type: Arcitx`）**：玩家点击这块区域时开始输入文字。
3. **后端提交区域（普通点击区域）**：玩家结束文字编辑后，点击这块独立的按钮来正式提交内容并执行后续动作。

把“编辑”和“提交”分成两个独立步骤，可以让玩家在正式执行命令或扣款前看清自己填写的内容，有误时随时点击输入框重新修改。

## 玩家输入流程

1. **点击编辑区域**：唤起文本输入状态。
2. **输入文字**：支持中文输入法（IME）、英文、数字、符号、空格与表情。空格键在编辑期间仅作为普通字符输入，不会关闭菜单或直接提交。
3. **结束编辑（保存草稿）**：完成打字后退出编辑状态。此时文字作为“草稿”显示在菜单上，尚未触发提交动作，玩家可以随时再次点击编辑区域继续修改。
4. **点击提交区域**：点击菜单上对应的提交按钮，ArcMenu 将草稿保存为正式提交值，并执行该按钮上配置的动作。

不同输入模式下的编辑体验如下：

| 输入模式        | 编辑方式                                       | 如何结束编辑并回到菜单                       |
| ----------- | ------------------------------------------ | --------------------------------- |
| 触控 `touch`  | 打开原版铁砧界面，在改名栏中输入文字。                        | 按 `Esc` 键，或点击铁砧右侧的结果槽。            |
| 鼠标 `mouse`  | 打开由配套资源包隐藏了外观的原版铁砧控件，玩家视觉上直接看着菜单上的文字变化。    | 按 `Esc` 键（也可点击结果槽位置）。             |
| 视觉 `vision` | 不打开铁砧界面，直接在菜单画面内调用客户端本地的原生文本输入与系统输入法（IME）。 | 按 `Esc` 键、`Enter` 键，或直接用光标点击菜单画面。 |

在 Vision 模式下，如果玩家在输入期间直接点击了菜单上的某个按钮，客户端会先结束当前的文本编辑，接着立即响应那次点击。关于三种输入模式的切换与配置，可参考[触控、鼠标与 Vision 输入](/gong-neng-pei-zhi/input-modes.md)。

## 快速上手示例

将以下内容保存为 `plugins/ArcMenu/menus/arcitx-demo.yml`，执行 `/arcmenu reload` 后，用 `/arcmenu open arcitx-demo` 打开即可体验：

```yaml
schema-version: 1
id: arcitx-demo
canvas:
  width: 320
  height: 180
  pixels-per-block: 42.7

frontend:
  input-border:
    type: frame
    width: 260
    height: 30
    thickness: 1
    color: '#7494B8'
    offset: {y: 12, z: 1}

  input-buffer:
    type: text
    content: ''
    size: 8
    offset: {y: 9, z: 2}

  submit-background:
    type: rectangle
    width: 100
    height: 24
    color: '#3366AA'
    offset: {y: -34, z: 1}

  submit-label:
    type: text
    content: '&f提交'
    size: 8
    offset: {y: -37, z: 2}

backend:
  edit-input:
    type: Arcitx
    x: 0
    y: 12
    width: 260
    height: 30
    text: input-buffer
    submit: submit-input
    title: '输入文本'
    initial: ''
    max-length: 50
    mask: ''
    display:
      before: '&7点击我输入文本'
      editing: '&f{input}{caret}'
      draft: '&f{input}'
      complete: '&a{input}'
    caret:
      content: '_'
      interval: 10

  submit-input:
    x: 0
    y: -34
    width: 100
    height: 24
    actions:
      left: 'tell: &a已提交：{meta:input-edit-input}'
```

在这个例子中：

* 前端的 `input-buffer` 决定了文字的字号、字体、对齐方式和坐标位置。菜单运行时，它的实际显示文本由后端 `edit-input` 的 `display` 配置动态接管；你依然可以为 `input-buffer` 添加位移、缩放或透明度动画。
* 后端的 `edit-input` 声明了 `type: Arcitx`，通过 `text: input-buffer` 绑定显示节点，并通过 `submit: submit-input` 绑定提交按钮。
* 后端的 `submit-input` 是一个标准点击区域，玩家点击它时，才会真正读取输入结果并发送提示消息。按钮动作与点击触发的详细写法见[后端交互区域与点击事件](/cai-dan-pei-zhi/menus/backend.md)和[动作与导航](/cai-dan-pei-zhi/menus/actions.md)。

## 配置字段详解

在 `backend` 下的交互区域中设置 `type: Arcitx`（不区分大小写），即可将该区域设为文本输入框。除普通后端区域原有的 `x`、`y`、`width`、`height`、`priority`、`tooltip`、`condition`、`actions` 等字段外，Arcitx 区域支持以下专用字段：

| 字段                 | 有效值与填写要求                          | 默认值                     | 说明                                             |
| ------------------ | --------------------------------- | ----------------------- | ---------------------------------------------- |
| `type`             | 填写 `Arcitx`                       | 必填                      | 将该后端区域声明为 Arcitx 文本输入区域。                       |
| `text`             | 前端 `text` 节点的 ID 字符串              | 必填                      | 指定用于显示输入缓冲区的文字节点（支持引用 `group` 分组内的文字节点）。       |
| `submit`           | 后端普通区域的 ID 字符串                    | 必填                      | 指定用于确认提交的另一个后端点击区域。                            |
| `title`            | 任意字符串                             | `Enter text`            | 原版铁砧界面的标题文字，在触控模式下可见。                          |
| `initial`          | 长度不超过 `max-length` 的字符串           | `''`                    | 菜单首次打开时的初始草稿内容，支持解析菜单占位符。                      |
| `max-length`       | `1` – `50` 之间的整数                  | `50`                    | 允许输入的最大长度（按 UTF-16 编码单元计算）。                    |
| `mask`             | 空字符串 `''`，或单个 Unicode 字符（如 `'*'`） | `''`                    | 密码遮罩字符。留空时显示原文；填写单个字符时，用该字符替换 `{input}` 的显示内容。 |
| `display.before`   | 字符串                               | `&7Click to enter text` | 尚未编辑且尚未提交时的初始提示文字。                             |
| `display.editing`  | 字符串                               | `{input}{caret}`        | 正在输入期间显示的文字模板。                                 |
| `display.draft`    | 字符串                               | `{input}`               | 结束编辑后、尚未点击提交按钮时的草稿文字模板。                        |
| `display.complete` | 字符串                               | `{input}`               | 点击提交按钮之后的文字模板。                                 |
| `caret.content`    | 字符串                               | `_`                     | 编辑状态下闪烁的输入光标符号，可使用 `&` 颜色代码。                   |
| `caret.interval`   | 大于或等于 `1` 的正整数                    | `10`                    | 输入光标显示与隐藏的切换间隔，单位为游戏刻（tick，20 ticks = 1 秒）。    |

### 关于字符长度（`max-length`）

常规英文字母、数字和常用汉字每个占 1 个 UTF-16 单元，部分 Emoji 表情占 2 个单元。当玩家输入的内容超出 `max-length` 时，ArcMenu 会在上限处自动截断，并且会保护完整的代理对字符，不会把一个 Emoji 表情从中间切碎。

## 四种显示状态与模板标记

`display` 下的四个子字段对应输入框的四个阶段：

1. **输入前（`before`）**：玩家打开菜单后还没改动过输入框。如果玩家点开了输入框但一个字都没改就退出了编辑，也会恢复为这个状态。
2. **输入中（`editing`）**：玩家正在打字，此时会实时渲染 `{input}` 和闪烁的 `{caret}`。
3. **草稿（`draft`）**：玩家修改了文字并退出了编辑状态，等待点击提交按钮。此时玩家仍可再次点击输入框继续修改。
4. **已提交（`complete`）**：玩家点击了绑定的 `submit` 区域完成提交。如果菜单没有关闭，玩家可以继续点击编辑区域输入新内容，再次点击提交按钮即可更新提交值。

在 `display` 的四个字符串中，你可以使用：

* `{input}`：代表当前缓冲区里的玩家输入文字（若设置了 `mask`，则会替换为等长的遮罩字符）。
* `{caret}`：代表闪烁的光标符号（仅在 `editing` 状态下闪烁，其余三个状态下自动替换为空）。
* 颜色格式（如 `&a`、`&#FFAA00`）以及菜单支持的其他占位符。

玩家自己输入的文本会按字面原样展示。即使玩家在输入框里打出了 `&c`、`{caret}` 或 `%player_name%`，也会被当作普通文字显示出来，不会破坏你的颜色格式或解析出其他占位符。

## 读取提交后的文本

当玩家点击 `submit` 绑定的提交区域时，ArcMenu 会先把当前的草稿保存为正式提交值，然后按顺序执行提交区域里的 `actions`。你可以在动作中使用以下 `meta` 占位符获取玩家提交的真实文字（不受 `mask` 遮罩影响）：

| 占位符                     | 说明                                         |
| ----------------------- | ------------------------------------------ |
| `{meta:input}`          | 该玩家最近一次提交的输入文本（包含 Arcitx 提交或聊天输入捕获，跨菜单保留）。 |
| `{meta:input-<编辑区域ID>}` | 指定 Arcitx 编辑区域最近一次提交的输入文本。                 |

例如编辑区域的 ID 叫 `search-box`，那么在提交按钮的动作里就可以写 `{meta:input-search-box}`。当同一个菜单里放了多个输入框（比如“账号”和“密码”，或者“收款人”和“金额”）时，使用带 ID 的写法可以准确区分每个输入框的值：

```yaml
actions:
  left:
    - 'tell: &a正在向 {meta:input-target-player} 转账 {meta:input-amount} 金币'
```

### 草稿、提交值与校验

* **何时更新提交值**：只有在点击独立的 `submit` 区域时，`{meta:input-...}` 才会更新。在打字过程中、按 `Esc` 退出编辑或点击铁砧结果槽时，都不会更新提交值。
* **空文本与条件校验**：Arcitx 允许提交空字符串。如果你希望要求玩家必须填写内容，或者校验输入格式，可以在提交区域的动作中配合[条件](/cai-dan-pei-zhi/menus/conditions.md)进行判断（例如判断 `'{meta:input-edit-input}' != ''`）。
* **生命周期**：输入框本身的草稿与当前会话内通过 API 读取的已提交值都属于当前打开的菜单会话，关闭菜单后重新打开时，输入框会重新从 `initial` 初始值开始。而 `{meta:input}` 与 `{meta:input-<编辑区域ID>}` 写入的是玩家级别的临时数据（META），打开或关闭菜单不会自动清空它们，后续再次提交会覆盖对应的值，开启聊天输入捕获（Catcher）或执行 `remove-meta` 时则会将其清除。提交按钮本身不会自动关闭菜单；如果需要提交后关闭菜单或跳转页面，只需在提交区域的 `actions` 中加上 `close` 或 `open: 其他菜单ID`。

## 密码遮罩与自定义完成显示

### 密码框效果

设置 `mask: '*'` 后，菜单上显示的 `{input}` 会按照玩家输入文字的 Unicode 码点数量显示对应个数的星号，而 `{meta:input-...}` 依然能读取到玩家输入的真实密码：

```yaml
mask: '*'
display:
  before: '&7请输入密码'
  editing: '&f{input}{caret}'
  draft: '&f{input}'
  complete: '&f{input}'
```

注意：`mask` 作用于菜单画面上绑定的前端文字节点。在触控模式下，原版铁砧界面自身的改名框里依然会显示正在输入的明文；Mouse 模式（配合隐藏铁砧外观的资源包）和 Vision 模式则全程只在菜单画面上显示遮罩后的星号。

### 固定完成提示

如果你希望打字时让玩家看清原文，提交之后隐藏具体内容或显示固定提示，可以把 `mask` 留空，直接修改 `display.complete`：

```yaml
mask: ''
display:
  before: '&7点击输入兑换码'
  editing: '&f{input}{caret}'
  draft: '&f{input}'
  complete: '&a已确认，点击可重新修改'
```

## 结构与绑定规则

编写菜单配置时，ArcMenu 会自动校验以下绑定规则，帮助你在加载阶段发现配置问题：

1. **节点存在且类型匹配**：`text` 必须指向当前菜单 `frontend` 中实际存在的 `type: text` 节点；`submit` 必须指向 `backend` 中实际存在的普通点击区域（不能指向自身，也不能指向另一个 `Arcitx` 区域）。
2. **一对一独占绑定**：同一个菜单里如果有多个 `Arcitx` 区域，每个输入框都必须绑定各自独立的 `text` 节点和独立的 `submit` 区域，不能共用。
3. **编辑区域与提交区域在几何上完全分离**：编辑区域和它绑定的提交区域在画布上的矩形范围不能重叠，四条边缘也不能紧贴在一起。请为两块区域留出明确的间距（例如相差至少 1 个画布单位）。


---

# 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/arcitx.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.