Input 输入框
通过鼠标或键盘输入字符。
基础用法
禁用状态
使用 disabled 属性禁用输入框。
可清空
使用 clearable 属性使输入框可清空。2.13.4 版本后,文本域(textarea)类型的输入框也支持清空功能。
自定义清除图标 2.11.0
您可以通过设置 `clear-icon` 属性来自定义清除图标。
格式化
使用 formatter 格式化显示值,通常与 parser 配合使用。
密码框
使用 show-password 属性创建可切换显示密码的输入框。自 2.13.6 起,支持使用 password-icon 插槽覆盖默认图标。
带图标的输入框
添加图标以指示输入类型。
要在输入框中添加图标,只需使用 prefix-icon 和 suffix-icon 属性。此外,prefix 和 suffix 命名的插槽也同样适用。
文本域
用于输入多行文本信息,可缩放。添加 type="textarea" 属性将 input 转换为原生的 textarea。
通过设置 rows 属性来控制高度。
自适应高度文本域
为文本域类型的输入框设置 autosize 属性,可以使高度根据内容自动调整。可以向 autosize 提供一个配置对象,以指定文本域自动调整的最小和最大行数。
复合输入框
在输入框前或后添加元素,通常是标签或按钮。
使用 slot 分发在输入框前置或后置的元素。
尺寸
添加 size 属性以更改输入框的大小。除默认大小外,还有两个其他选项:large、small。
输入长度限制
input 的 maxlength 和 minlength 属性,它们声明了用户可以输入的字符数限制。 “字符数” 使用 JavaScript 字符串长度进行测量。为 text 或 textarea 类型的输入框设置 maxlength 属性可以限制输入值的长度,同时通过将 show-word-limit 设置为 true 可以显示字数统计。在 2.11.5 中,你可以将 word-limit-position 设置为 outside 以在输入框外部显示字数统计。
统计字形 2.13.7
设置 count-graphemes 来计算文本长度。如果设置了此属性,将不会使用原生的 maxlength 和 minlength。
提示
浏览器支持和降级策略
使用 count-graphemes 属性时,组件采用以下方法
首选:使用
Intl.SegmenterAPI(Chrome 87+、Firefox 125+、Safari 14.1+)进行正确的字形集群处理。这能正确处理复杂的表情符号(emoji)、组合标记和零宽连结符(ZWJ)序列。降级:旧版浏览器降级到使用
Array.from()进行基于码位的迭代。请注意,这可能会拆分多码位字形序列(例如,带有肤色修饰符的表情符号)。
在实现自己的 count-graphemes 函数时,如果需要对复杂 Unicode 字符的健壮支持,请考虑使用 Intl.Segmenter。
API
属性
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| type | input 的类型,更多详情请参阅 MDN | string | 文本 |
| model-value / v-model | 绑定值 | string / number | — |
| model-modifiers 2.11.5 | v-model 修饰符,参考 Vue 修饰符 | object | — |
| 最大长度 | 与原生输入框的 `maxlength` 相同 | string / number | — |
| 最小长度 | 与原生输入框的 `minlength` 相同 | string / number | — |
| show-word-limit | 是否显示字数统计,仅在 type 为 'text' 或 'textarea' 时生效 | boolean | false |
| word-limit-position 2.11.5 | 字数统计位置,当 show-word-limit 为 true 时有效 | 枚举 | "inside"(内部) |
| 占位符 | 输入框占位文本 | string | — |
| 可清空 | 是否显示清除按钮,仅在 type 不是 'textarea' 时生效 | boolean | false |
| 清除图标 2.11.0 | 自定义清除图标组件 | string / object | CircleClose |
| 格式化程序 | 指定输入框显示值的格式。(仅在 type 为 'text' 时生效) | Function | — |
| parser | 指定从格式化输入中提取值的解析器。(仅在 type 为 'text' 时生效) | Function | — |
| show-password | 是否显示切换密码输入 | boolean | false |
| disabled | 输入框是否禁用 | boolean | false |
| size | 输入框尺寸,在 type 不是 'textarea' 时生效 | 枚举 | — |
| 前缀图标 | 前置图标组件 | string / Component | — |
| 后缀图标 | 后置图标组件 | string / Component | — |
| 行数 | 文本域行数,仅在 type 为 'textarea' 时生效 | number | 2 |
| autosize | 文本域高度是否自适应,仅在 type 为 'textarea' 时生效。可以接受一个对象,例如 { minRows: 2, maxRows: 6 } | boolean / object | false |
| 自动补全 | 与原生输入框的 `autocomplete` 相同 | string | off |
| 名称 | 与原生输入框的 `name` 相同 | string | — |
| 只读 | 与原生输入框的 `readonly` 相同 | boolean | false |
| max | 与原生 input 的 max 相同 | — | — |
| min | 与原生 input 的 min 相同 | — | — |
| 步长 | 与原生 input 的 step 相同 | — | — |
| 调整大小 | 控制是否能缩放 | 枚举 | — |
| 自动聚焦 | 与原生输入框的 `autofocus` 相同 | boolean | false |
| form 表单 | 与原生 input 的 form 相同 | string | — |
| aria-label a11y 2.7.2 | 与原生输入框的 `aria-label` 相同 | string | — |
| tabindex | 输入框的 tabindex | string / number | — |
| validate-event | 是否触发表单验证 | boolean | true |
| input-style | input 元素或 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 |
| input | HTML input 元素 | object |
| ref | HTML 元素,input 或 textarea | object |
| resizeTextarea | 重新调整文本域大小 | Function |
| select | 选中输入框中的文本 | Function |
| textarea | HTML textarea 元素 | object |
| textareaStyle | textarea 的样式 | object |
| isComposing 2.8.0 | 输入法是否正在合成中 | object |
| passwordVisible 2.13.7 | 密码是否可见 | object |
常见问题
为什么 clearable 会撑大 ElInput 组件的宽度?
典型问题: #7287
附注:由于 ElInput 组件没有默认宽度,当显示清除图标时,组件的宽度会被撑开,可以通过设置宽度(width)来解决。
<el-input v-model="input" clearable style="width: 200px" />