Input 输入框

输入框是表单数据录入的基础组件，覆盖从单行短文本到多行长文本的全场景输入需求。通过尺寸梯度、状态反馈与辅助元素的组合，降低用户输入门槛，提升填写效率与准确性。

import { createApp } from 'vue'
import { ElInput } from '@szhn/dh-design-pc'

const app = createApp()
app.use(ElInput)

基础用法 / 类型

分为文本与文本域两种。文本适用于单行短文本输入，内容超出时自动截断，用于用户名、手机号、邮箱等场景；文本域适用于多行长文本输入，支持自适应高度扩展，用于备注、描述、评论等场景。

尺寸

提供大、中、小三种高度，分别对应 40px、32px、24px。大尺寸用于页面核心表单与独立搜索框；中尺寸为默认规格，适配常规表单与数据筛选；小尺寸用于表格行内编辑与紧凑信息区。

搜索框

搜索框支持线性与面性两种外观，可将搜索图标放在左侧或右侧。右侧搜索图标在输入状态下会与清除按钮分隔，方便用户区分清空和搜索动作。

交互状态

涵盖默认、输入中、悬停、提示、禁用五种状态。默认态展示占位提示；输入态展示当前内容；悬停态强化边框反馈；提示态在输入框下方展示辅助文案；禁用态用于条件未满足或权限不足的场景。

辅助元素

包括前/后缀图标、辅助文字、密码与字数限制。前后缀图标用于标记输入类型或提示输入意图；密码输入用于敏感信息；字数限制用于控制输入长度并给出即时反馈。

使用规则

同表单内尺寸保持一致，禁止混排；占位文字仅作提示，不可包含完成任务所需的关键信息；文本域默认按组件尺寸显示稳定高度，需要随内容增长时使用自适应高度；禁用状态用于条件未满足或权限不足，避免用户无效尝试。

Element Plus 示例补充

保留 Element Plus 输入框的其他常用示例，重复场景已统一到上方设计规范示例。

禁用状态

一键清空

自定义清除图标

密码输入框

文本域

可调整尺寸

字数限制

扩展能力

格式化

在 formatter 的情况下显示值，通常同时使用 parser 还原输入值。

自适应文本域

设置 autosize 后，文本域可根据内容自动调整高度。也可以给 autosize 提供最小和最大行数范围。

复合型输入框

可以在输入框中前置或后置一个元素，通常是标签或按钮。

计数图形

:::小技巧

浏览器支持 & 回退策略

当使用 count-graphemes prop 时，组件使用以下方法：

在实现自己的 count-graphemes 函数时，如果需要对复杂的 unicode 字符提供强大的支持，请考虑使用 Intl.Segmenter。

:::

常见问题

典型问题： #7287

PS: 由于 ElInput 组件没有默认宽度，当显示 clearable 图标时，组件的宽度将被撑开，可以通过设置固定宽度属性来解决。

API

Attributes

属性名	说明	类型	默认值
type	输入类型，更多信息请参见 MDN	string	text
model-value / v-model	绑定值	string / number	—
model-modifiers	v-model 修饰符，参考 Vue 修饰符	object	—
maxlength	同原生 maxlength 属性	string / number	—
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	textarea 高度是否自适应，仅 type 为 'textarea' 时生效。 可以接受一个对象，比如: { minRows: 2, maxRows: 6 }	boolean / object	false
autocomplete	原生 autocomplete 属性	string	off
name	等价于原生 input name 属性	string	—
readonly	原生 readonly 属性，是否只读	boolean	false
max	原生 max 属性，设置最大值	—	:::
min	原生属性，设置最小值	—	—
step	原生属性，设置输入字段的合法数字间隔	:::	—
resize	控制是否能被用户缩放	enum	—
autofocus	原生属性，自动获取焦点	boolean	false
form	原生属性	string	—
aria-label a11y	等价于原生 input aria-label 属性	string	—
tabindex	输入框的 tabindex	string / number	—
validate-event	输入时是否触发表单的校验	boolean	true
input-style	input 元素或 textarea 元素的 style	string / object	{}
label a11y deprecated	等价于原生 input aria-label 属性	string	—
inputmode	等价于原生 input inputmode 属性	string	—
count-graphemes	自定义函数用于计算字形；设置后，将绕过原生的 maxlength/minlength 约束。 组件使用 Intl.Segmenter（Chrome 87+、Firefox 125+、Safari 14.1+）进行正确的字素聚类；旧版浏览器回退到使用 Array.from() 进行代码点迭代。	Function	:::

Events

事件名	说明	类型
blur	当选择器的输入框失去焦点时触发	Function
focus	当选择器的输入框获得焦点时触发	Function
change	仅当 modelValue 改变时，当输入框失去焦点或用户按Enter时触发	Function
input	在 Input 值改变时触发	Function
clear	在点击由 clearable 属性生成的清空按钮时触发	Function
keydown	按下键时触发	Function
mouseleave	当鼠标离开输入元素时触发	Function
mouseenter	当鼠标进入输入元素时触发	Function
compositionstart	输入法输入开始时触发	Function
compositionupdate	输入法输入改变时触发	Function
compositionend	输入法输入完成时触发	Function

Slots

插槽名	说明
prefix	输入框头部内容，只对非 type="textarea" 有效
suffix	输入框尾部内容，只对非 type="textarea" 有效
prepend	输入框前置内容，只对非 type="textarea" 有效
append	输入框后置内容，只对非 type="textarea" 有效
password-icon	作为输入密码图标的内容，仅在 show-password 为 true 时生效。 作用域变量为 { visible: boolean }

Exposes

名称	说明	类型
blur	使 input 失去焦点	Function
clear	清除 input 值	Function
focus	使 input 获取焦点	Function
input	Input HTML 元素	object
ref	HTML元素 input 或 textarea	object
resizeTextarea	改变 textarea 大小	Function
select	选中 input 中的文字	Function
textarea	HTML textarea 元素	object
textareaStyle	textarea 的样式	object
isComposing	是否是输入 composing 状态	object
passwordVisible	密码是否可见	object