输入框组件

输入框组件用于接收玩家在当前页面会话中输入的文字。它支持提示文字、文字偏移、普通与聚焦背景图片，以及聚焦状态下的独立 GIF 和源图选区。

适用场景

搜索、名称和数量输入
表单与确认页面
页面脚本读取或修改临时输入值
普通/聚焦两种外观的文本框

输入值保存在当前客户端页面会话中。关闭并重新打开页面后，会重新建立输入状态；服务端不会因为玩家输入文字就自动执行命令或业务操作。

通用配置

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`id`	ID	字符串	自动生成 `input_N`	页面内唯一 ID	用于脚本和状态更新。
`type`	类型	只读字符串	`input`	固定值	创建后不能修改。
`parent`	父级	字符串	空	布局组件 ID	为空表示根级元素。
`z`	层级	整数	`0`	任意整数	控制输入框绘制顺序。
`visible`	显示	布尔值	`true`	`true`、`false`	静态显隐开关。
`enabled`	启用	布尔值	`true`	`true`、`false`	为假时不能聚焦和输入。
`pointerEvents`	指针处理	枚举	`auto`	`auto`、`block`、`pass`	输入框在 `auto` 下天然参与命中；`pass` 后无法获得焦点。
`scale`	缩放	数字或公式	`1`	非负值	以输入框中心缩放背景、文字和命中范围，不改变布局值。
`opacity`	透明度	数字或公式	`1`	`0` 至 `1`	控制输入框背景和文字透明度，不改变命中。
`visibleWhen`	显示条件	条件表达式	空	只读条件	条件为假时隐藏。
`enabledWhen`	启用条件	条件表达式	空	只读条件	条件为假时禁用输入。
`tooltip`	多行提示	字符串列表	空	最多 32 行，每行最多 256 字符	鼠标悬浮提示。
`containerBinding`	容器绑定	字符串	空	当前容器的语义槽位 ID	仅容器替换页面使用，可读取绑定物品信息。
`containerTooltip`	容器提示	布尔值	`true`	`true`、`false`	没有显式 `tooltip` 时是否显示绑定物品提示。
`layout.x`	X	数字或公式	创建时画布位置	合法布局公式	输入框左上角 X。
`layout.y`	Y	数字或公式	创建时画布位置	合法布局公式	输入框左上角 Y。
`layout.width`	宽	数字或公式	`80`	合法布局公式	输入框宽度。
`layout.height`	高	数字或公式	`24`	合法布局公式	输入框高度。
`events.leftPress` `/rightPress/middlePress`	按下脚本	ChaUI Script	空	多行脚本	对应按键按下时触发。
`events.leftRelease` `/rightRelease/middleRelease`	松开脚本	ChaUI Script	空	多行脚本	对应按键捕获仍有效并松开时触发。
`events.leftClick`	左键脚本	ChaUI Script	空	多行脚本	左键点击时触发，同时可获得输入焦点。
`events.rightClick`	右键脚本	ChaUI Script	空	多行脚本	右键点击时触发。
`events.middleClick`	中键脚本	ChaUI Script	空	多行脚本	中键点击时触发。
`events.hoverEnter`	悬浮进入脚本	ChaUI Script	空	多行脚本	鼠标进入时触发。
`events.hoverLeave`	悬浮离开脚本	ChaUI Script	空	多行脚本	鼠标离开时触发。

专属配置

文字与会话值

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`input.placeholder`	提示	字符串	新建时组件 ID；字段缺失为空	任意安全文字	输入值为空时显示的提示。
`input.value`	当前编辑器会话输入	字符串	空	当前会话文字	运行时状态，不建议作为页面默认配置；关闭页面后不持久保存。
`input.textSize`	文字大小	正数	`1`	正整数或正小数	输入文字缩放比例。
`input.textX`	文字X	整数	`4`	任意整数	文字相对输入框左上角的 X 偏移。
`input.textY`	文字Y	整数	`5`	任意整数	文字相对输入框左上角的 Y 偏移。
`input.textLineLength`	每行字数	正整数或空	`0`	`0`/空或正整数	按字符数量换行。
`input.textLineWidth`	每行宽度	非负整数或空	`0`	GUI 像素	按应用 `textSize` 后的真实字形宽度换行；`0` 或空表示不限制。

两个限制可以同时使用，任意一项先达到就换行。显式换行与空行会保留；单个字形本身超过像素限制时会单独占一行。

普通背景

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`input.path`	背景路径	字符串	`gui/input_N.png`	ChaUI 相对图片路径，可含 `{表达式}`	未聚焦时的背景图片或 GIF。
`input.gifLoop`	GIF循环	布尔值	`true`	`true`、`false`	控制普通背景 GIF 是否循环。
`input.gifLoopCount`	GIF次数	非负整数	`0`	`0` 或正整数	`0` 表示无限循环。
`input.sourceX`	源X	非负整数或公式	空	像素坐标或数字公式	普通背景选区左上角 X。
`input.sourceY`	源Y	非负整数或公式	空	像素坐标或数字公式	普通背景选区左上角 Y。
`input.sourceWidth`	源宽	非负整数或公式	空	像素尺寸或数字公式	普通背景选区宽度；为 `0` 时普通背景不绘制。
`input.sourceHeight`	源高	非负整数或公式	空	像素尺寸或数字公式	普通背景选区高度；为 `0` 时普通背景不绘制。

聚焦背景

配置项	编辑器名称	类型	默认值	可选值或格式	说明
`input.focusPath`	焦点路径	字符串	`gui/input_N_focus.png`	ChaUI 相对图片路径，可含 `{表达式}`	获得输入焦点时使用；为空时回退普通背景。
`input.focusGifLoop`	焦点GIF循环	布尔值	`true`	`true`、`false`	控制聚焦背景 GIF 是否循环。
`input.focusGifLoopCount`	焦点GIF次数	非负整数	`0`	`0` 或正整数	`0` 表示无限循环。
`input.focusSourceX`	焦点源X	非负整数或公式	空	像素坐标或数字公式	聚焦背景选区左上角 X。
`input.focusSourceY`	焦点源Y	非负整数或公式	空	像素坐标或数字公式	聚焦背景选区左上角 Y。
`input.focusSourceWidth`	焦点源宽	非负整数或公式	空	像素尺寸或数字公式	聚焦背景选区宽度；为 `0` 时聚焦背景不绘制。
`input.focusSourceHeight`	焦点源高	非负整数或公式	空	像素尺寸或数字公式	聚焦背景选区高度；为 `0` 时聚焦背景不绘制。

当图片成功加载时，不会叠加默认描边。没有可用图片时，ChaUI 会绘制默认输入框；聚焦状态使用更亮的高亮边框。

普通与聚焦两组选区都能使用响应式数字公式，计算结果向下取整。负数、非有限值、未知变量或越界只会让对应背景安全回退，不影响输入内容和焦点状态。

普通与聚焦路径都可以读取变量，例如 gui/{vars.theme}/input.png 和 gui/{vars.theme}/input_focus.png。变量变化后会重新加载对应背景，GIF 从第 0 帧开始。表达式求值后的最终路径仍必须是安全的图片相对路径，非法结果只会回退当前背景。

配置示例

先在页面根级 vars 中加入 theme: default，再把下面组件放入 elements。以后修改 vars.theme，普通与聚焦背景会一起切换目录。

yaml

- id: player_name
  type: input
  parent: ""
  visible: true
  enabled: true
  pointerEvents: auto
  scale: 1
  opacity: 1
  z: 10
  layout:
    x: 20
    y: 40
    width: 140
    height: 22
  input:
    placeholder: 请输入名称
    textSize: 1
    textX: 4
    textY: 6
    textLineLength: 16
    textLineWidth: 120
    path: gui/{vars.theme}/input.png
    gifLoop: true
    gifLoopCount: 0
    focusPath: gui/{vars.theme}/input_focus.png
    focusGifLoop: true
    focusGifLoopCount: 0
  tooltip:
    - 点击后输入文字
  events: {}

输入值保存在当前页面会话中，可以通过输入框对象读取：

yaml

events:
  rightClick: |-
    vars.currentName = component("player_name").input.value
    log("当前输入：{vars.currentName}")

常见问题

点击后无法输入

确认组件 enabled=true，enabledWhen 没有返回假，并且当前处于预览或正常运行页面。

聚焦时没有切换图片

检查 focusPath。聚焦图片不可用时会回退普通图片；两者都不可用时才显示默认高亮框。

如何把输入结果提交到业务插件

输入值属于当前页面会话。需要结合页面脚本、自定义发包或其他插件 API 设计提交流程，服务端仍应校验所有业务数据。

创建事件

输入框可通过 events.create 设置初始提示、临时值或显隐状态。每个输入框实例只触发一次；复制出的新输入框会独立触发。预览退出后，输入值和创建脚本造成的修改都会丢弃。

服务端配置文件 ↘

输入框组件 ​

适用场景 ​

通用配置 ​

专属配置 ​

文字与会话值 ​

普通背景 ​

聚焦背景 ​

配置示例 ​

常见问题 ​

点击后无法输入 ​

聚焦时没有切换图片 ​

如何把输入结果提交到业务插件 ​

创建事件 ​