Input 输入框

通过鼠标或键盘输入字符。

基础用法

禁用状态

使用 disabled 属性禁用输入框。

可清空

使用 clearable 让输入框可一键清空。文本域类型的输入框同样支持可清空。

自定义清空图标

通过 clear-icon 自定义清空图标。

格式化

使用 formatter 展示格式化后的值,通常与 parser 配合使用。

密码框

使用 show-password 可切换密码显隐。支持 password-icon 插槽覆盖默认图标。

带图标输入框

通过图标提示输入类型。

可使用 prefix-iconsuffix-icon 属性添加图标,也可使用 prefixsuffix 具名插槽。

Using attributes
Using slots
Icon with prefix and suffix
¥RMB

文本域

用于输入多行文本信息,可调整高度。将 type 设为 textarea 即可使用原生 textarea

通过 rows 控制高度。

自适应文本域高度

文本域类型下设置 autosize 可使高度随内容变化。也可传入对象 { minRows, maxRows } 限制最小与最大行数。

复合型输入框

可在输入框前后添加元素,一般为标签或按钮。

使用插槽在输入框前后插入内容。

Http://
.com
Select
Select

尺寸

使用 size 调整尺寸;除默认外可选 largesmall

输入长度限制

使用 maxlengthminlength 限制字符数(以 JavaScript 字符串长度计量)。文本或文本域类型可同时设置 show-word-limit 显示字数统计。可用 word-limit-position 设为 outside 将字数统计放在输入框外侧。

0 / 10
0 / 10
0 / 30
0 / 30

按字素计数

设置 count-graphemes 按字素统计长度;启用后不再使用原生 maxlength / minlength

2 / 10
2 / 20

TIP

浏览器支持与回退策略

使用 count-graphemes 时,组件采用如下策略:

  • 优先:使用 Intl.Segmenter(Chrome 87+、Firefox 125+、Safari 14.1+)正确处理字素簇,包括复杂表情、组合字符与 ZWJ 序列。

  • 回退:旧浏览器使用 Array.from() 按码点迭代,可能拆分多码点字素(如带肤色修饰的表情)。

若自行实现计数函数且需稳健支持复杂 Unicode,建议优先使用 Intl.Segmenter

输入框 API

输入框 属性

名称说明类型默认值
type输入框类型,详见 MDNstringtext
model-value / v-model绑定值string / number
model-modifiersv-model 修饰符,参考 Vue 修饰符object
maxlength同原生 maxlengthstring / number
minlength同原生 minlengthstring / number
show-word-limit是否显示字数统计,仅在 typetexttextarea 时生效booleanfalse
word-limit-position字数统计位置,在 show-word-limittrue 时生效enum"inside"
placeholder占位文本string
clearable是否显示清空按钮,typetextarea 时不生效booleanfalse
clear-icon自定义清空图标组件string / objectCircleClose
formatter展示值的格式化函数(仅 typetext 时生效)Function
parser从格式化文本解析值的函数(仅 typetext 时生效)Function
show-password是否显示密码切换按钮booleanfalse
disabled是否禁用booleanfalse
size输入框尺寸,typetextarea 时生效enum
prefix-icon前缀图标string / Component
suffix-icon后缀图标string / Component
rows文本域行数,仅 typetextarea 时生效number2
autosize文本域是否自适应高度,仅 typetextarea 时生效;可传入 { minRows, maxRows }boolean / objectfalse
autocomplete同原生 autocompletestringoff
name同原生 namestring
readonly同原生 readonlybooleanfalse
max同原生 max
min同原生 min
step同原生 step
resize控制是否可调整大小enum
autofocus同原生 autofocusbooleanfalse
form同原生 formstring
aria-label a11y同原生 aria-labelstring
tabindex输入框 tabindexstring / number
validate-event是否触发表单校验booleantrue
input-style输入框或文本域元素样式string / object{}
inputmode同原生 inputmodestring
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输入框前缀内容,typetextarea 时生效
suffix输入框后缀内容,typetextarea 时生效
prepend输入框前置内容,typetextarea 时生效
append输入框后置内容,typetextarea 时生效
password-icon密码图标内容,show-passwordtrue 时生效;作用域参数为 { 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 默认无固定宽度,显示清空图标后布局可能外扩,可通过设置宽度解决。

vue
<u-input v-model="input" clearable style="width: 200px" />