Input 输入框

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

基础用法

禁用状态

使用 disabled 属性禁用输入框。

可清空

使用 clearable 属性使输入框可清空。2.13.4 版本后,文本域(textarea)类型的输入框也支持清空功能。

自定义清除图标 2.11.0

您可以通过设置 `clear-icon` 属性来自定义清除图标。

格式化

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

密码框

使用 show-password 属性创建可切换显示密码的输入框。自 2.13.6 起,支持使用 password-icon 插槽覆盖默认图标。

带图标的输入框

添加图标以指示输入类型。

要在输入框中添加图标,只需使用 prefix-iconsuffix-icon 属性。此外,prefixsuffix 命名的插槽也同样适用。

使用属性
使用插槽

文本域

用于输入多行文本信息,可缩放。添加 type="textarea" 属性将 input 转换为原生的 textarea

通过设置 rows 属性来控制高度。

自适应高度文本域

为文本域类型的输入框设置 autosize 属性,可以使高度根据内容自动调整。可以向 autosize 提供一个配置对象,以指定文本域自动调整的最小和最大行数。

复合输入框

在输入框前或后添加元素,通常是标签或按钮。

使用 slot 分发在输入框前置或后置的元素。

Http://
.com
选择器
选择器

尺寸

添加 size 属性以更改输入框的大小。除默认大小外,还有两个其他选项:largesmall

输入长度限制

inputmaxlengthminlength 属性,它们声明了用户可以输入的字符数限制。 “字符数” 使用 JavaScript 字符串长度进行测量。为 text 或 textarea 类型的输入框设置 maxlength 属性可以限制输入值的长度,同时通过将 show-word-limit 设置为 true 可以显示字数统计。在 2.11.5 中,你可以将 word-limit-position 设置为 outside 以在输入框外部显示字数统计。

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

统计字形 2.13.7

设置 count-graphemes 来计算文本长度。如果设置了此属性,将不会使用原生的 maxlengthminlength

2 / 10
2 / 20

提示

浏览器支持和降级策略

使用 count-graphemes 属性时,组件采用以下方法

  • 首选:使用 Intl.Segmenter API(Chrome 87+、Firefox 125+、Safari 14.1+)进行正确的字形集群处理。这能正确处理复杂的表情符号(emoji)、组合标记和零宽连结符(ZWJ)序列。

  • 降级:旧版浏览器降级到使用 Array.from() 进行基于码位的迭代。请注意,这可能会拆分多码位字形序列(例如,带有肤色修饰符的表情符号)。

在实现自己的 count-graphemes 函数时,如果需要对复杂 Unicode 字符的健壮支持,请考虑使用 Intl.Segmenter

API

属性

名称描述类型默认值
typeinput 的类型,更多详情请参阅 MDNstring文本
model-value / v-model绑定值string / number
model-modifiers 2.11.5v-model 修饰符,参考 Vue 修饰符object
最大长度与原生输入框的 `maxlength` 相同string / number
最小长度与原生输入框的 `minlength` 相同string / number
show-word-limit是否显示字数统计,仅在 type 为 'text' 或 'textarea' 时生效booleanfalse
word-limit-position 2.11.5字数统计位置,当 show-word-limit 为 true 时有效枚举"inside"(内部)
占位符输入框占位文本string
可清空是否显示清除按钮,仅在 type 不是 'textarea' 时生效booleanfalse
清除图标 2.11.0自定义清除图标组件string / objectCircleClose
格式化程序指定输入框显示值的格式。(仅在 type 为 'text' 时生效)Function
parser指定从格式化输入中提取值的解析器。(仅在 type 为 'text' 时生效)Function
show-password是否显示切换密码输入booleanfalse
disabled输入框是否禁用booleanfalse
size输入框尺寸,在 type 不是 'textarea' 时生效枚举
前缀图标前置图标组件string / Component
后缀图标后置图标组件string / Component
行数文本域行数,仅在 type 为 'textarea' 时生效number2
autosize文本域高度是否自适应,仅在 type 为 'textarea' 时生效。可以接受一个对象,例如 { minRows: 2, maxRows: 6 }boolean / objectfalse
自动补全与原生输入框的 `autocomplete` 相同stringoff
名称与原生输入框的 `name` 相同string
只读与原生输入框的 `readonly` 相同booleanfalse
max与原生 input 的 max 相同
min与原生 input 的 min 相同
步长与原生 input 的 step 相同
调整大小控制是否能缩放枚举
自动聚焦与原生输入框的 `autofocus` 相同booleanfalse
form 表单与原生 input 的 form 相同string
aria-label a11y 2.7.2与原生输入框的 `aria-label` 相同string
tabindex输入框的 tabindexstring / number
validate-event是否触发表单验证booleantrue
input-styleinput 元素或 textarea 元素的样式string / object{}
label a11y 已废弃与原生输入框的 `aria-label` 相同string
输入模式 2.10.3与原生输入框的 `inputmode` 相同string
count-graphemes 2.13.7用于统计字形的自定义函数;设置后将绕过原生的 maxlength/minlength 限制。组件使用 Intl.Segmenter(Chrome 87+、Firefox 125+、Safari 14.1+)进行正确的字形集群;旧版浏览器降级为 Array.from() 进行码位迭代。Function

事件

名称描述类型
blur在 Input 失去焦点时触发Function
focus在 Input 获得焦点时触发Function
change仅当 modelValue 改变时,在输入框失去焦点或用户按回车键时触发Function
input在 Input 值改变时触发Function
clear在点击清除按钮清空 Input 时触发Function
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 2.13.6输入框密码图标内容,仅在 show-password 为 true 时生效。作用域变量为 { visible: boolean }

暴露

名称描述类型
blur使输入框元素失焦Function
clear清除输入值Function
focus使输入框元素聚焦Function
inputHTML input 元素object
refHTML 元素,input 或 textareaobject
resizeTextarea重新调整文本域大小Function
select选中输入框中的文本Function
textareaHTML textarea 元素object
textareaStyletextarea 的样式object
isComposing 2.8.0输入法是否正在合成中object
passwordVisible 2.13.7密码是否可见object

常见问题

为什么 clearable 会撑大 ElInput 组件的宽度?

典型问题: #7287

附注:由于 ElInput 组件没有默认宽度,当显示清除图标时,组件的宽度会被撑开,可以通过设置宽度(width)来解决。

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

来源

组件样式文档

贡献者