Input
输入单行文本。中文惯用名：输入框。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.input |
| 名称 | Input |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 输入单行文本 |
| 描述 | 中文惯用名：输入框。 |
预览
静态结构：Input 为单行文本控件（vendored shadcn Input，data-slot="input"，高 h-9）；allowClear 且值非空且未禁用时，控件外再包一层 flex 行容器承载右侧 × 清除按钮（点击清空并触发 onChange("")），此时独立渲染的 className / style 挂包裹节点；未开启 allowClear 时保持裸控件，className / style 直接挂 input 本身。Form 内声明非空 name 时外层为 data-slot="form-item" 容器（label 经 htmlFor 关联控件 useId + data-slot="form-error" 校验错误行），不走 FieldShell。
DSL 结构
{
"type": "Input",
"props": {
"name": "keyword",
"label": "关键词",
"placeholder": "请输入关键词",
"allowClear": true
}
}何时用
何时使用
- 采集单行短文本：姓名、标题、编号、关键词、搜索词。
- 需要掩码输入：type="password" 走原生 password 输入。
- 高频重填的检索类输入：allowClear 在值非空时提供一键清空。
何时不用
- 多行文本 / 备注说明：使用 Textarea，Input 是单行控件。
- 数值录入（需步进、范围与精度约束）：使用 NumberInput；日期 / 时间：使用 DatePicker / TimePicker。
- 从候选中选值而非自由输入：候选少且固定用 Select，候选多且可搜索用 Combobox。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认 text | 单行描边输入框，聚焦 ring 高亮 | 常规短文本录入 |
| type="password" | 原生掩码输入 | 密码、密钥等敏感短文本 |
| allowClear 可清空 | 值非空时右侧出现 × 按钮 | 搜索框、筛选条件等高频重填输入 |
| Form 表单项 | form-item 容器：label + 控件 + 校验错误行 | 表单内字段（声明 name 自动注册） |
| disabled 禁用 | 半透明不可输入，清除按钮不渲染 | 只读回显、流程未就绪 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（Form 内由 label 标签呈现） |
rules | FieldRule[] | — | 校验规则（注册字段时携带，当前支持 required + message） |
value | string | — | 受控值（独立渲染时生效）；Form 内作为字段初始值（优先于 Form initialValues） |
type | `'text' | 'password'` | 'text' |
placeholder | string | — | 空态提示文案 |
disabled | boolean | false | 禁用输入；同时使 allowClear 的清除按钮不渲染 |
allowClear | boolean | false | 值为非空且未禁用时显示清除按钮；开启后独立渲染的 className / style 挂控件包裹节点（含清除按钮） |
onChange | (value: string) => void | — | 输入事件，传出 string（Renderer 绑定 events.onChange；非原生 event） |
controlClassName | string | — | 控件本体 class（无论是否在 Form 内都挂 input 节点；Form 内精确设置控件样式如宽度时使用） |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式（Form 内为 form-item 容器，独立渲染时为控件本身） |
使用规范
- 单行短文本专用：长文本、备注、富文本一律换 Textarea 或对应组件，不靠 Input 拉伸。
- Form 内必须声明非空 name 才会注册为表单项并参与校验；rules 随字段注册，value 作字段初始值且优先于 Form initialValues。
- placeholder 写「请输入…」并给格式示例（如「请输入订单号，如 PO20260922001」），不用 placeholder 代替 label。
- allowClear 适合高频重填场景；开启后独立渲染的 className / style 挂在包裹节点而非 input 本身，设置宽度等样式时注意作用对象。
- password 仅做输入掩码，不提供强度校验与加密传输，敏感字段需配合服务端安全策略。
正例
- ✓ 搜索框：allowClear + placeholder「请输入关键词」，onChange 直接驱动列表过滤。
- ✓ Form 内「项目名称」：name="title" + label + rules 必填，校验失败自动在字段下方展示错误。
- ✓ 密码字段：type="password" 掩码输入，取值时随表单 values 一并提交。
反例
- ✕ 用 Input 录入备注、摘要等多行长文本（应使用 Textarea）。
- ✕ 用 Input 采集金额 / 数量再自行解析字符串（应使用 NumberInput 获得范围与精度约束）。
- ✕ Form 内忘记声明 name，字段值不进表单 values，提交时取不到。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。