# 输入组件 (Inputs)

`Inputs` 节点用于在菜单中添加交互式输入组件，允许玩家提交数值、文字或做出选择。输入的值可以在动作中通过 `$(键名)` 变量引用。

***

## 配置结构

```yaml
Inputs:
  组件键名:
    type: '组件类型'
    text: '组件标签文字'
    # 组件专属配置...
```

* **组件键名**：唯一标识，在动作中用 `$(键名)` 引用该组件的值
* **组件顺序**：按照 YAML 书写顺序从上到下排列

***

## 引用输入值

在 `Bottom` 的 `actions` 中，可以通过 `$(键名)` 引用对应输入框的当前值：

```yaml
Inputs:
  player_name:  # 输入内容将对应下方$(player_name)
    type: 'input'
    text: '请输入玩家名称'
    default: '请在此输入...'
  volume:  # 输入内容将对应下方$(volume)
    type: 'slider'
    text: '音量'
    min: 0
    max: 100
    step: 1
    default: 50
    format: '音量: %s%s'
  amount:  # 输入内容将对应下方$(amount)
    type: 'input'
    text: '请输入数量'
    default: '请在此输入...'
    
Bottom:
  type: 'notice'
  confirm:
    text: '&a确认'
    actions:
      - 'tell: &f你输入的名字是: &e $(player_name)'
      - 'tell: &f你选择的音量是: &e $(volume)'
      - 'tell: &f你输入的数量是: &e $(amount)'
```

***

## 组件类型

### input - 文本输入框

允许玩家输入任意文字。

**配置项：**

| 字段           | 类型        | 必须 | 默认值     | 说明             |
| ------------ | --------- | -- | ------- | -------------- |
| `type`       | `String`  | ✅  | —       | 固定值 `input`    |
| `text`       | `String`  | ✅  | —       | 输入框标签文字，支持条件判断 |
| `hide_text`  | `Boolean` | ❌  | `false` | 是否隐藏输入框自身的标签文字 |
| `default`    | `String`  | ❌  | `""`    | 默认填充文字         |
| `max_length` | `Int`     | ❌  | `256`   | 最大输入字符数        |
| `width`      | `Int`     | ❌  | `250`   | 输入框宽度（像素）      |
| `multiline`  | 节点        | ❌  | —       | 启用多行输入模式       |

**多行输入配置：**

| 字段                    | 类型    | 默认值   | 说明        |
| --------------------- | ----- | ----- | --------- |
| `multiline.max_lines` | `Int` | `5`   | 最大行数      |
| `multiline.height`    | `Int` | `100` | 输入框高度（像素） |

**示例：**

```yaml
Inputs:
  player_name:
    type: 'input'
    text: '&a请输入玩家名称'
    default: 'Steve'
    max_length: 16

  feedback:
    type: 'input'
    text: '&7留言内容'
    hide_text: true
    default: '请在此输入...'
    multiline:
      max_lines: 5
      height: 80
```

***

### slider - 数值滑块

允许玩家通过拖动滑块选择一个范围内的数值。

**配置项：**

| 字段        | 类型       | 必须 | 默认值      | 说明                         |
| --------- | -------- | -- | -------- | -------------------------- |
| `type`    | `String` | ✅  | —        | 固定值 `slider`               |
| `text`    | `String` | ✅  | —        | 滑块标签文字，支持条件判断              |
| `min`     | `Double` | ✅  | `0.0`    | 最小值                        |
| `max`     | `Double` | ✅  | `10.0`   | 最大值                        |
| `default` | `Double` | ❌  | 等于 `min` | 默认值                        |
| `step`    | `Double` | ❌  | `1.0`    | 每次移动的步长                    |
| `format`  | `String` | ❌  | `%s: %s` | 显示格式（第一个 `%s` 为标签，第二个为当前值） |

**示例：**

{% hint style="warning" %}
**重要：** `min` 值**必须小于** `max` 值。如果 `min` ≥ `max`，插件会：

* 在控制台输出警告日志
* 自动使用默认值（min=0.0, max=10.0）
  {% endhint %}

```yaml
Inputs:
  volume:
    type: 'slider'
    text: '&e音量'
    min: 0
    max: 100
    step: 5
    default: 50
    format: '&e音量: &f%s%%'

  purchase_amount:
    type: 'slider'
    text: '&6购买数量'
    min: 1
    max: 64
    step: 1
    default: 1
    format: '数量: %s'
```

***

### dropdown - 下拉选择框

允许玩家从预设选项列表中选择一项。

**配置项：**

| 字段           | 类型             | 必须 | 默认值     | 说明                                       |
| ------------ | -------------- | -- | ------- | ---------------------------------------- |
| `type`       | `String`       | ✅  | —       | 固定值 `dropdown`                           |
| `text`       | `String`       | ✅  | —       | 下拉框标签文字，支持条件判断                           |
| `hide_text`  | `Boolean`      | ❌  | `false` | 是否隐藏下拉框自身的标签文字                           |
| `options`    | `List<String>` | ✅  | —       | 选项列表，支持普通字符串、`id => display` 格式，以及条件判断列表 |
| `default_id` | `String`       | ❌  | —       | 默认选中的选项 ID                               |
| `width`      | `Int`          | ❌  | `200`   | 下拉框宽度（像素）                                |

**options 支持格式：**

1. **旧格式：显示值与提交值相同**

```yaml
options:
  - 'red'
  - 'green'
  - 'blue'
```

2. **新格式：使用 `id => display` 分离提交值与显示值**

```yaml
options:
  - 'red => &c红色'
  - 'green => &a绿色'
  - 'blue => &b蓝色'
```

3. **条件判断格式：兼容 `allow` / `deny` 返回字符串列表**

```yaml
options:
  - condition: "%player_is_op% == true"
    allow:
      - 'red => &cOP-红色'
      - 'green => &aOP-绿色'
    deny:
      - 'red => &c玩家-红色'
      - 'green => &a玩家-绿色'
```

> 当使用 `id => display` 时：
>
> * 左侧 `id` 会作为动作中 `$(变量名)` 的真实值
> * 右侧 `display` 是玩家在界面中看到的文本

**示例：**

```yaml
Inputs:
  color_select:
    type: 'dropdown'
    text: '&b选择颜色'
    hide_text: true
    options:
      - 'red => &c红色'
      - 'green => &a绿色'
      - 'blue => &b蓝色'
      - 'yellow => &e黄色'
    default_id: 'green'

  server_select:
    type: 'dropdown'
    text: '&7选择服务器'
    options:
      - 'lobby'
      - 'survival'
      - 'creative'
    default_id: 'lobby'
    width: 150
```

***

### checkbox - 复选框

允许玩家切换一个开/关状态。

**配置项：**

| 字段         | 类型        | 必须 | 默认值     | 说明             |
| ---------- | --------- | -- | ------- | -------------- |
| `type`     | `String`  | ✅  | —       | 固定值 `checkbox` |
| `text`     | `String`  | ✅  | —       | 复选框标签文字，支持条件判断 |
| `default`  | `Boolean` | ❌  | `false` | 默认是否勾选         |
| `on_true`  | `String`  | ❌  | `true`  | 勾选时传递给动作的值     |
| `on_false` | `String`  | ❌  | `false` | 未勾选时传递给动作的值    |

**示例：**

```yaml
Inputs:
  enable_notify:
    type: 'checkbox'
    text: '&a开启公告通知'
    default: true

  pvp_mode:
    type: 'checkbox'
    text: '&c开启 PvP 模式'
    default: false
    on_true: 'enabled'    # 勾选时 $(pvp_mode) = "enabled"
    on_false: 'disabled'  # 未勾选时 $(pvp_mode) = "disabled"
```

**在动作中使用：**

```yaml
Bottom:
  confirm:
    actions:
      - 'console: pvp set %player_name% $(pvp_mode)'
      # 勾选时执行: pvp set Steve enabled
      # 未勾选时执行: pvp set Steve disabled
```

***

## 完整示例

```yaml
Title: '&6玩家设置'

Inputs:
  nickname:
    type: 'input'
    text: '&e昵称'
    default: '%player_name%'
    max_length: 16

  chat_volume:
    type: 'slider'
    text: '&b聊天音量'
    min: 0
    max: 10
    default: 5
    format: '%s%s'

  language:
    type: 'dropdown'
    text: '&a语言'
    options:
      - 'zh_cn => 简体中文'
      - 'en_us => English'
    default_id: 'zh_cn'

  color_select:
    type: 'dropdown'
    text: '&b选择颜色'
    hide_text: true
    options:
      - condition: "%player_is_op% == true"
        allow:
          - 'red => &cOP-红色'
          - 'green => &aOP-绿色'
          - 'blue => &bOP-蓝色'
        deny:
          - 'red => &c玩家-红色'
          - 'green => &a玩家-绿色'
          - 'blue => &b玩家-蓝色'
    default_id: 'red'

  join_notify:
    type: 'checkbox'
    text: '&7接收玩家上线提醒'
    default: true

Bottom:
  type: 'confirmation'
  confirm:
    text: '&a[ 保存设置 ]'
    actions:
      - 'set-data: nickname $(nickname)'
      - 'set-data: chat_volume $(chat_volume)'
      - 'set-data: language $(language)'
      - 'set-data: join_notify $(join_notify)'
      - 'tell: &a设置已保存！'
      - 'sound: entity.experience_orb.pickup'
  deny:
    text: '&c[ 取消 ]'
    actions:
      - 'tell: &7操作已取消。'
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://katacr.gitbook.io/plugins/kamenu-cn/menu/inputs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.