CodeBox

Appearance

Input 输入框

浏览量：

Input 输入框组件是基于 Element Plus 的 el-input 组件封装而成，用于通过鼠标或键盘输入字符。

INFO

Input 组件完全继承了 Element Plus Input 组件的所有属性和事件，因此支持所有 Element Plus Input 组件的功能，包括清除按钮、密码显示切换、前后置内容、限制输入等高级特性。

插槽命名规则

Input 组件的插槽使用 input-{slotName} 格式，其中 slotName 对应 Element Plus el-input 组件的插槽名称。例如：

  • input-prepend 对应 el-input 的 prepend 插槽
  • input-append 对应 el-input 的 append 插槽
  • input-prefix 对应 el-input 的 prefix 插槽
  • input-suffix 对应 el-input 的 suffix 插槽

基础用法 ​

Input 通过 v-model 进行双向数据绑定。你可以通过 placeholder 属性设置输入框的占位文本，通过 clearable 属性显示清除按钮。

loading

禁用状态 ​

通过 disabled 属性可以禁用输入框。禁用状态下，输入框不可编辑，且样式会发生变化。

loading

密码输入框 ​

通过设置 type="password" 和 show-password 属性，可以创建一个密码输入框，用户可以通过点击眼睛图标来切换密码的显示和隐藏。

loading

带前后置内容的输入框 ​

通过 input-prepend 和 input-append 插槽可以在输入框前后添加内容，例如添加图标、按钮或选择器。

loading

属性说明 ​

属性名类型默认值说明
modelValue / v-modelString | Number''绑定值，使用 v-model 进行双向绑定
typeString'text'输入框类型，可选值：text、textarea、password、url、email、date 等
placeholderString''输入框占位文本
disabledBooleanfalse是否禁用
clearableBooleanfalse是否显示清除按钮，只有在 type 不为 textarea 时生效
show-passwordBooleanfalse是否显示切换密码图标，只有在 type 为 password 时生效
readonlyBooleanfalse是否只读
maxlengthString | Number''最大输入长度
minlengthString | Number''最小输入长度
show-word-limitBooleanfalse是否显示输入字数统计，只在 type 为 text 或 textarea 时生效
rowsNumber2输入框行数，仅在 type 为 textarea 时生效
autosizeBoolean | Objectfalsetextarea 高度是否自适应，仅在 type 为 textarea 时生效。可以传入对象，如 { minRows: 2, maxRows: 4 }
resizeString''控制是否能被用户缩放，可选值：none、both、horizontal、vertical，仅在 type 为 textarea 时生效
autocompleteString'off'原生 autocomplete 属性
formString''原生 form 属性
labelString''等价于原生 input aria-label 属性
tabindexString | Number''输入框的 tabindex
validate-eventBooleantrue输入时是否触发表单的校验
input-styleString | Object{}input 元素或 textarea 元素的 style
其他属性--支持透传 Element Plus el-input 组件的所有属性

TIP

  • 组件完全兼容 Element Plus Input 的所有属性和功能
  • 可以参考 Element Plus Input 文档 了解更多高级用法
  • v-model 绑定的值可以是字符串或数字类型
  • maxlength 和 minlength 属性可以传入字符串或数字，字符串会被转换为数字
  • autosize 属性在 type 为 textarea 时，可以传入布尔值或对象来控制高度自适应

插槽说明 ​

组件支持通过插槽自定义输入框的各个部分。插槽命名规则为 input-{slotName}，其中 slotName 对应 Element Plus el-input 组件的插槽名称。

插槽名说明
input-prepend输入框前置内容，只对非 textarea 类型的输入框有效
input-append输入框后置内容，只对非 textarea 类型的输入框有效
input-prefix输入框头部内容
input-suffix输入框尾部内容
input-prepend-icon输入框前置图标
input-append-icon输入框后置图标

TIP

  • 插槽名称必须以 input- 开头，后面的部分会作为 el-input 的插槽名
  • prepend 和 append 插槽只对非 textarea 类型的输入框有效
  • prefix 和 suffix 插槽可以用于添加图标或其他内容
  • 可以在前置或后置插槽中放置按钮、选择器等组件，实现复合输入框

事件说明 ​

事件名说明回调参数触发时机
blur输入框失去焦点时触发(event: FocusEvent) - 事件对象输入框失去焦点时触发
focus输入框获得焦点时触发(event: FocusEvent) - 事件对象输入框获得焦点时触发
change仅在输入框失去焦点或用户按下回车时触发(value: string | number) - 输入框的值输入框失去焦点或用户按下回车时触发
input在 Input 值改变时触发(value: string | number) - 输入框的值输入框值改变时触发
clear在点击由 clearable 属性生成的清空按钮时触发-点击清除按钮时触发
update:modelValue绑定值更新时触发（用于 v-model 双向绑定）(value: string | number) - 新的值当 modelValue 值发生变化时触发，用于实现双向绑定

TIP

  • input 事件在每次输入时都会触发，而 change 事件只在失去焦点或按下回车时触发
  • blur 和 focus 事件对应原生的焦点事件
  • clear 事件只在设置了 clearable 属性并点击清除按钮时触发
  • 组件完全兼容 Element Plus Input 的所有事件，可以参考 Element Plus Input 文档 了解更多事件

高级功能 ​

由于组件完全继承了 Element Plus Input 的所有功能，因此支持以下高级特性：

文本域 ​

通过设置 type="textarea" 可以将输入框转换为文本域，支持多行输入。可以通过 rows 属性设置行数，或通过 autosize 属性让高度自适应。

限制输入长度 ​

通过 maxlength 和 minlength 属性可以限制输入的最大和最小长度。结合 show-word-limit 属性可以显示输入字数统计。

密码显示切换 ​

通过设置 type="password" 和 show-password 属性，可以创建一个带显示/隐藏切换功能的密码输入框。

复合输入框 ​

通过 prepend 和 append 插槽，可以在输入框前后添加内容，实现复合输入框，例如带搜索按钮的输入框、带选择器的输入框等。

输入验证 ​

Input 组件可以与 Form 组件配合使用，通过 validate-event 属性控制是否触发表单验证。

注意事项 ​

  1. 双向绑定：

    • 使用 v-model 进行双向绑定，这是推荐的方式
    • v-model 绑定的值可以是字符串或数字类型
    • 如果需要在输入时进行格式化处理，可以使用 @input 事件

  2. 插槽使用：

    • 插槽名称必须以 input- 开头，例如 input-prepend、input-append
    • prepend 和 append 插槽只对非 textarea 类型的输入框有效
    • 可以在前置或后置插槽中放置按钮、选择器等组件

  3. 文本域：

    • 当 type 为 textarea 时，prepend 和 append 插槽无效
    • 可以通过 rows 属性设置文本域的行数
    • 可以通过 autosize 属性让文本域高度自适应内容

  4. 密码输入框：

    • 需要同时设置 type="password" 和 show-password 属性才能显示切换图标
    • 切换图标会显示在输入框的右侧

  5. 清除按钮：

    • 只有在 type 不为 textarea 时，clearable 属性才会生效
    • 清除按钮会在输入框有值且获得焦点时显示

  6. Element Plus 兼容性：

    • 组件完全兼容 Element Plus Input 的所有功能和 API
    • 可以参考 Element Plus Input 文档 了解更多高级用法
    • 支持透传 Element Plus el-input 的所有属性和事件

  7. 样式定制：

    • 可以通过 input-style 属性直接设置输入框的样式
    • 可以通过 class 或 style 属性来定制组件样式

最佳实践 ​

  1. 使用 v-model 进行双向绑定：这是 Vue 3 推荐的方式，代码更简洁，性能更好

  2. 合理使用清除按钮：对于需要频繁清空的输入框，建议设置 clearable 属性，提升用户体验

  3. 密码输入框：在需要输入密码的场景，使用 type="password" 和 show-password 属性，让用户可以切换显示/隐藏密码

  4. 限制输入长度：对于有长度限制的输入（如用户名、手机号等），使用 maxlength 和 minlength 属性，并配合 show-word-limit 显示字数统计

  5. 复合输入框：对于需要前置或后置操作的输入框（如搜索框、带单位的输入框等），使用 prepend 和 append 插槽实现

  6. 文本域自适应：对于多行文本输入，使用 autosize 属性让文本域高度自适应内容，提供更好的输入体验

  7. 表单验证：在表单中使用 Input 组件时，合理使用 validate-event 属性控制验证时机，避免频繁触发验证影响性能

  8. 无障碍访问：使用 label 属性或配合 el-form-item 的 label 属性，为输入框提供合适的标签，提升无障碍访问体验