Input 输入框
通过鼠标或键盘输入字符。
基础用法
禁用状态
使用 disabled 属性禁用输入框。
可清空
使用 clearable 让输入框可一键清空。文本域类型的输入框同样支持可清空。
自定义清空图标
通过 clear-icon 自定义清空图标。
格式化
使用 formatter 展示格式化后的值,通常与 parser 配合使用。
密码框
使用 show-password 可切换密码显隐。支持 password-icon 插槽覆盖默认图标。
带图标输入框
通过图标提示输入类型。
可使用 prefix-icon、suffix-icon 属性添加图标,也可使用 prefix、suffix 具名插槽。
文本域
用于输入多行文本信息,可调整高度。将 type 设为 textarea 即可使用原生 textarea。
通过 rows 控制高度。
自适应文本域高度
文本域类型下设置 autosize 可使高度随内容变化。也可传入对象 { minRows, maxRows } 限制最小与最大行数。
复合型输入框
可在输入框前后添加元素,一般为标签或按钮。
使用插槽在输入框前后插入内容。
尺寸
使用 size 调整尺寸;除默认外可选 large、small。
输入长度限制
使用 maxlength、minlength 限制字符数(以 JavaScript 字符串长度计量)。文本或文本域类型可同时设置 show-word-limit 显示字数统计。可用 word-limit-position 设为 outside 将字数统计放在输入框外侧。
按字素计数
设置 count-graphemes 按字素统计长度;启用后不再使用原生 maxlength / minlength。
TIP
浏览器支持与回退策略
使用 count-graphemes 时,组件采用如下策略:
优先:使用
Intl.Segmenter(Chrome 87+、Firefox 125+、Safari 14.1+)正确处理字素簇,包括复杂表情、组合字符与 ZWJ 序列。回退:旧浏览器使用
Array.from()按码点迭代,可能拆分多码点字素(如带肤色修饰的表情)。
若自行实现计数函数且需稳健支持复杂 Unicode,建议优先使用 Intl.Segmenter。
输入框 API
输入框 属性
| 名称 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| type | 输入框类型,详见 MDN | string | text |
| model-value / v-model | 绑定值 | string / number | — |
| model-modifiers | v-model 修饰符,参考 Vue 修饰符 | object | — |
| maxlength | 同原生 maxlength | string / number | — |
| minlength | 同原生 minlength | string / number | — |
| show-word-limit | 是否显示字数统计,仅在 type 为 text 或 textarea 时生效 | boolean | false |
| word-limit-position | 字数统计位置,在 show-word-limit 为 true 时生效 | enum | "inside" |
| placeholder | 占位文本 | string | — |
| clearable | 是否显示清空按钮,type 为 textarea 时不生效 | boolean | false |
| clear-icon | 自定义清空图标组件 | string / object | CircleClose |
| formatter | 展示值的格式化函数(仅 type 为 text 时生效) | Function | — |
| parser | 从格式化文本解析值的函数(仅 type 为 text 时生效) | Function | — |
| show-password | 是否显示密码切换按钮 | boolean | false |
| disabled | 是否禁用 | boolean | false |
| size | 输入框尺寸,type 非 textarea 时生效 | enum | — |
| prefix-icon | 前缀图标 | string / Component | — |
| suffix-icon | 后缀图标 | string / Component | — |
| rows | 文本域行数,仅 type 为 textarea 时生效 | number | 2 |
| autosize | 文本域是否自适应高度,仅 type 为 textarea 时生效;可传入 { minRows, maxRows } | boolean / object | false |
| autocomplete | 同原生 autocomplete | string | off |
| name | 同原生 name | string | — |
| readonly | 同原生 readonly | boolean | false |
| max | 同原生 max | — | — |
| min | 同原生 min | — | — |
| step | 同原生 step | — | — |
| resize | 控制是否可调整大小 | enum | — |
| autofocus | 同原生 autofocus | boolean | false |
| form | 同原生 form | string | — |
| aria-label a11y | 同原生 aria-label | string | — |
| tabindex | 输入框 tabindex | string / number | — |
| validate-event | 是否触发表单校验 | boolean | true |
| input-style | 输入框或文本域元素样式 | string / object | {} |
| inputmode | 同原生 inputmode | string | — |
| count-graphemes | 自定义字素计数函数;设置后将绕过原生 maxlength/minlength。组件优先使用 Intl.Segmenter(Chrome 87+、Firefox 125+、Safari 14.1+)进行字素聚类;旧浏览器回退为 Array.from() 按码点迭代 | Function | — |
输入框 事件
| 名称 | 说明 | 类型 |
|---|---|---|
| blur | 失去焦点时触发 | Function |
| focus | 获得焦点时触发 | Function |
| change | 失焦或按下回车且 modelValue 已变化时触发 | Function |
| input | 值变化时触发 | Function |
| clear | 点击清空按钮时触发 | Function(自 2.13.4 起可接收 evt) |
| keydown | 按键按下时触发 | Function |
| mouseleave | 鼠标离开输入框时触发 | Function |
| mouseenter | 鼠标进入输入框时触发 | Function |
| compositionstart | 输入法组合开始时触发 | Function |
| compositionupdate | 输入法组合更新时触发 | Function |
| compositionend | 输入法组合结束时触发 | Function |
输入框 插槽
| 名称 | 说明 |
|---|---|
| prefix | 输入框前缀内容,type 非 textarea 时生效 |
| suffix | 输入框后缀内容,type 非 textarea 时生效 |
| prepend | 输入框前置内容,type 非 textarea 时生效 |
| append | 输入框后置内容,type 非 textarea 时生效 |
| password-icon | 密码图标内容,show-password 为 true 时生效;作用域参数为 { visible: boolean } |
输入框 暴露
| 名称 | 说明 | 类型 |
|---|---|---|
| blur | 使输入框失焦 | Function |
| clear | 清空输入值 | Function |
| focus | 使输入框聚焦 | Function |
| input | 原生 input 元素引用 | object |
| ref | 输入框或文本域元素引用 | object |
| resizeTextarea | 重新计算文本域高度 | Function |
| select | 选中输入框中的文本 | Function |
| textarea | 原生 textarea 元素引用 | object |
| textareaStyle | 文本域样式引用 | object |
| isComposing | 是否处于输入法组合状态 | object |
| passwordVisible | 密码是否可见 | object |
常见问题
为什么开启 clearable 后 UInput 宽度会变宽?
常见问题:#7287
说明:UInput 默认无固定宽度,显示清空图标后布局可能外扩,可通过设置宽度解决。
<u-input v-model="input" clearable style="width: 200px" />