输入框
概述
用于输入文本的基础输入框组件，支持标准 input 属性、前后缀插槽与可清除功能。适用于任意短文本录入场景——表单字段、搜索框、过滤器。多行文本请使用 STextarea，敏感值请使用 SPassword，数值请使用 SInputNumber。
用法
特性
- 📏 6 种尺寸：xs、sm、md、lg、xl、2xl
- 🧹 可清除模式，悬停/聚焦时显示清除按钮（i18n
aria-label） - 🔤
leading/trailing插槽，用于前缀与后缀内容 - 🔒
disabled/readonly状态，交互守卫完整 - 📋 设置
name时通过代理隐藏输入框支持原生表单提交 - ♿ 完整无障碍支持——
aria-roledescription、清除按钮命名、axe 零违规 - 🎯 TypeScript 类型安全，
type属性严格类型化
输入框组件系列
- SInput - 基础文本输入组件
- SInputClear - 清除按钮，
clearable时悬停/聚焦显示
演示
基础
100%
modelValue:
插槽
100%
API
Aria 层
5Input
22 属性1 事件3 插槽
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
class | ClassValue | — | 根类 |
size | ThemeSize | — | 组件的视觉尺寸。 |
ui | Partial<InputUi> | — | 该组件的按槽类重写。 |
inputRef | ((el: HTMLInputElement) => void) | — | 用于设置输入元素的函数。 |
clearable | boolean | false | 是否显示“清除”按钮。 |
controlProps | InputControlProps | — | 转发给控件的属性。 |
clearProps | InputClearProps | — | 转发给 `clear` 元素的属性。 |
defaultValue | string | — | 输入的默认值 |
modelValue | string | — | 输入的受控值 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与输入内容进行交互。 |
readonly | boolean | — | 当值为 `true` 时，输入内容为只读。 |
rootProps | BaseProps | — | 转发至根元素的属性 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
id | string | — | 输入元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，系统会自动聚焦于输入内容。 |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | 输入字段的 autocomplete 属性。
除 `on` / `off` 开关外，还支持 HTML 自动填充标记（包括密码管理器的值，例如
`current-password` / `new-password`）。 |
maxlength | number | — | 输入内容允许的最大字符数 |
minlength | number | — | 输入内容允许的最小字符数 |
pattern | string | — | 输入的 pattern 属性 |
placeholder | string | — | 输入的占位符 |
type | InputTypeHTMLAttribute | — | 输入元素的类型。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
leading | InputCompactSlotProps | 为首行位置提供自定义内容。 |
trailing | InputCompactSlotProps | 尾部槽位的自定义内容。 |
clear | InputCompactSlotProps | 为“clear”槽位定制内容。 |
InputClear
4 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
type | ButtonType | 'button' | 按钮元素的类型。可以是 'button'、'submit' 或 'reset' 之一。 |
disabled | boolean | — | 该组件是否已禁用。 |
asChild | boolean | — | 将默认渲染元素替换为作为子元素传递的元素，并合并两者的属性及行为。 |
as | AsTag | Component | 'div' | 该组件应渲染为的元素或组件。可通过 `asChild` 进行覆盖。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
clear | PointerEvent | 点击“清除”按钮时触发。 |
InputCompact
19 属性2 事件3 插槽
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
inputRef | ((el: HTMLInputElement) => void) | — | 用于设置输入元素的函数。 |
clearable | boolean | false | 是否显示“清除”按钮。 |
controlProps | InputControlProps | — | 转发给控件的属性。 |
clearProps | InputClearProps | — | 转发给 `clear` 元素的属性。 |
defaultValue | string | — | 输入的默认值 |
modelValue | string | — | 输入的受控值 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与输入内容进行交互。 |
readonly | boolean | — | 当值为 `true` 时，输入内容为只读。 |
rootProps | BaseProps | — | 转发至根元素的属性 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
id | string | — | 输入元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，系统会自动聚焦于输入内容。 |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | 输入字段的 autocomplete 属性。
除 `on` / `off` 开关外，还支持 HTML 自动填充标记（包括密码管理器的值，例如
`current-password` / `new-password`）。 |
maxlength | number | — | 输入内容允许的最大字符数 |
minlength | number | — | 输入内容允许的最小字符数 |
pattern | string | — | 输入的 pattern 属性 |
placeholder | string | — | 输入的占位符 |
type | InputTypeHTMLAttribute | — | 输入元素的类型。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
clear | PointerEvent | 点击“清除”按钮时触发。 |
插槽
| 插槽名 | 参数 | 描述 |
|---|---|---|
leading | InputCompactSlotProps | 为首行位置提供自定义内容。 |
trailing | InputCompactSlotProps | 尾部槽位的自定义内容。 |
clear | InputCompactSlotProps | 为“clear”槽位定制内容。 |
InputControl
InputRoot
15 属性1 事件
属性
| 属性名 | 类型 | 默认值 | 描述 |
|---|---|---|---|
defaultValue | string | — | 输入的默认值 |
modelValue | string | — | 输入的受控值 |
disabled | boolean | — | 当值为 `true` 时，禁止用户与输入内容进行交互。 |
readonly | boolean | — | 当值为 `true` 时，输入内容为只读。 |
rootProps | BaseProps | — | 转发至根元素的属性 |
name | string | — | 字段的名称。作为名称/值对的一部分，与其所属表单一同提交。 |
required | boolean | — | 当值为 `true` 时，表示用户必须先设置该值，所属表单才能提交。 |
id | string | — | 输入元素的 ID |
autofocus | boolean | — | 当值为 `true` 时，系统会自动聚焦于输入内容。 |
autocomplete | 'search' | 'name' | 'email' | 'tel' | 'url' | 'on' | 'off' | 'username' | 'current-password' | 'new-password' | 'one-time-code' | 'given-name' | 'family-name' | 'organization' | 'street-address' | 'address-level2' | 'postal-code' | 'country' | 'cc-name' | 'cc-number' | 'cc-exp' | 'cc-csc' | 'transaction-amount' | — | 输入字段的 autocomplete 属性。
除 `on` / `off` 开关外，还支持 HTML 自动填充标记（包括密码管理器的值，例如
`current-password` / `new-password`）。 |
maxlength | number | — | 输入内容允许的最大字符数 |
minlength | number | — | 输入内容允许的最小字符数 |
pattern | string | — | 输入的 pattern 属性 |
placeholder | string | — | 输入的占位符 |
type | InputTypeHTMLAttribute | — | 输入元素的类型。 |
事件
| 事件名 | 参数 | 描述 |
|---|---|---|
update:modelValue | string | 当模型值发生变化时触发。 |
注意事项
架构与对标差异
VeanUI 将输入框拆分为负责状态、表单代理与清除按钮语义的 Aria 层（@vean/aria/input），以及负责变体与 UnoCSS 样式的 styled 层（@vean/ui）。Aria InputCompact 组合 InputRoot / InputControl / InputClear 并暴露 leading / clear / trailing 插槽，与 Radix 的 headless/styled 分离一致，区别于 Ant Design、Element Plus 等单包方案。
| 能力 | VeanUI | Ant Design Input | Element Plus Input | Radix TextField |
|---|---|---|---|---|
| Aria/styled 分离 | ✅ | — | — | ✅ |
| 受控/非受控 | ✅ | ✅ | ✅ | ✅ |
| 清除按钮（悬停显示） | ✅ | ✅ | ✅ | — |
| 清除按钮 i18n 标签 | ✅ | ✅ | — | — |
| 前缀/后缀插槽 | ✅ | ✅ | ✅ | ✅ |
| 原生表单代理 | ✅ | — | — | — |
| 尺寸变体 | ✅ | ✅ | ✅ | — |
showCount 计数器 | — | ✅ | ✅ | — |
error / loading | — | ✅ | ✅ | — |
注意事项
showCount计数器、error态与loading态未实现，列为增强待办。- 清除按钮仅在悬停或聚焦时出现（桌面惯例）；触屏场景如需清除入口，可借助
leading/trailing插槽自行提供。 - 根节点默认渲染
role="group"、aria-roledescription="Input"与spellcheck="false"，属设计意图。
常见问题
如何添加前缀图标或后缀文本？
使用 leading 和 trailing 插槽，它们接收根节点上下文并渲染在输入框内部。
为什么清除按钮只在悬停时显示？
清除按钮可见性遵循桌面悬停/聚焦惯例（group-hover / group-focus-within），有意不常驻显示，以保持输入框紧凑并避免误清除。
输入框如何参与原生表单提交？
传入 name 即可——组件会渲染一个携带当前值的视觉隐藏代理输入框，原生表单提交与校验无需额外接线。
如何限制输入长度？
传入 maxlength / minlength，会透传到原生 input。可见计数器暂未提供（列为增强待办）。