最新版本v1.0.60
Input 输入框
通过鼠标或键盘输入内容，是最基础的表单域包装。
基础用法
基础用法
禁用状态
禁用状态
可清空
可清空
密码框
密码框
带图标的输入框
带图标
文本域
文本域
可自适应文本高度的文本域
自动高度
复合型输入框
可以在输入框前后添加一个元素，通常是标签或按钮。
复合输入框
输入长度限制
字数限制
不同尺寸
不同尺寸
格式化输入
格式化
视觉变体
通过 variant 属性可以切换四种视觉风格：default（带边框）、filled（填充色）、borderless（无边框）、underlined（下划线）。
视觉变体
加载状态
设置 loading 属性为 true 时，在输入框尾部显示旋转加载图标，常用于异步校验用户名、实时搜索等场景。
加载状态
独立状态色
通过 status 属性可以在不依赖 Form 表单的情况下，直接给输入框赋予 success、warning、error 三种状态反馈色。
独立状态色
聚焦自选
设置 select-on-focus 后，用户鼠标点击或 Tab 键切入输入框时会自动全选内部文字，非常适合数值编辑、表格单元格编辑等场景。
聚焦自选
Esc 键清空
设置 clear-on-escape 后，用户按 Esc 键时会立即清空输入框内容，配合 clearable 使用体验更佳。
Esc 键清空
前后缀字符串 / 原生 Datalist
prefix/suffix 属性支持直接传入字符串（如货币符号、单位），无需写插槽。list 属性绑定原生 <datalist> 的 id，实现本地联想筛选。
前后缀字符串与 Datalist
自定义字数计算
通过 count-config 的 calculate 函数可以自定义字数统计逻辑，例如让汉字计 2 字节、英文计 1 字节。
自定义字数计算
在 Nuxt 中使用
YhInput 可直接用于 Nuxt 3/4 项目。服务端会先输出稳定的输入框结构，客户端激活后继续接管聚焦、清空、计数和其它交互逻辑。
Nuxt 中使用
SSR 注意事项：
- ✅ 基础输入、文本域模式完全支持
- ✅ 样式及布局在服务器和浏览器保持一致
- ✅ 动态 ID 生成在 SSR 中是安全的（基于
useId） - ⚠️
autofocus属性仅在客户端激活后生效
SSR 安全性
Input 组件针对 SSR 进行了优化，特别是 ID 生成机制确保了服务端渲染和客户端激活的一致性，有效避免了属性不匹配错误。
API
Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | string | number | — |
| type | 类型 | 'text' | 'password' | 'textarea' | 'number' | 'email' | 'url' | 'tel' | 'search' | 'text' |
| size | 输入框尺寸 | 'large' | 'default' | 'small' | 'default' |
| placeholder | 占位文本 | string | — |
| variant | 视觉变体 | 'default' | 'filled' | 'borderless' | 'underlined' | 'default' |
| status | 独立状态反馈色，不依赖 FormItem | '' | 'success' | 'warning' | 'error' | '' |
| loading | 是否显示加载状态 | boolean | false |
| disabled | 是否禁用 | boolean | false |
| readonly | 是否只读 | boolean | false |
| clearable | 是否可清空 | boolean | false |
| clear-on-escape | 按 Esc 键时是否清空内容 | boolean | false |
| select-on-focus | 获取焦点时是否自动全选文字 | boolean | false |
| show-password | 是否显示切换密码图标 | boolean | false |
| show-word-limit | 是否显示字数统计 | boolean | false |
| count-config | 自定义字数统计配置 | { calculate?: (value: string) => number } | — |
| maxlength | 最大输入长度 | number | string | — |
| minlength | 最小输入长度 | number | string | — |
| prefix-icon | 前置图标 | string | Component | — |
| suffix-icon | 后置图标 | string | Component | — |
| clear-icon | 清除图标 | string | Component | — |
| prefix | 前置文本（字符串快捷方式，与 #prefix 插槽等效） | string | — |
| suffix | 后置文本（字符串快捷方式，与 #suffix 插槽等效） | string | — |
| list | 原生 list 属性，绑定 datalist 的 id | string | — |
| autofocus | 自动获取焦点 | boolean | false |
| autocomplete | 原生 autocomplete 属性 | string | 'off' |
| name | 原生 name 属性 | string | — |
| form | 原生 form 属性 | string | — |
| id | 输入框 id | string | — |
| aria-label | 等价于原生 input aria-label 属性 | string | — |
| tabindex | 输入框的 tabindex | string | number | — |
| validate-event | 输入时是否触发表单的校验 | boolean | true |
| input-style | input 元素或 textarea 元素的 style | string | object | — |
| label | (已过时) 等价于原生 input aria-label 属性，建议使用 aria-label | string | — |
| inputmode | 等价于原生 input inputmode 属性 | string | — |
| model-modifiers | v-model 修饰符 | object | — |
| formatter | 格式化函数（用于显示） | (value: string | number) => string | — |
| parser | 解析函数（用于更新值） | (value: string) => string | — |
| rows | 文本域行数 (type="textarea" 时有效) | number | 2 |
| autosize | 自适应文本高度 (type="textarea" 时有效) | boolean | { minRows?: number; maxRows?: number } | false |
| resize | 是否允许调整大小 (type="textarea" 时有效) | 'none' | 'both' | 'horizontal' | 'vertical' | — |
| theme-overrides | 组件级主题覆盖 | ComponentThemeVars | undefined |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| update:modelValue | 绑定值更新时触发 | (value: string | number) => void |
| input | 在 Input 值改变时触发 | (value: string | number) => void |
| change | 在 Input 失去焦点或用户按下回车时触发 | (value: string | number) => void |
| focus | 在 Input 获得焦点时触发 | (event: FocusEvent) => void |
| blur | 在 Input 失去焦点时触发 | (event: FocusEvent) => void |
| clear | 在点击清空按钮时触发 | () => void |
| keydown | 按下键盘时触发 | (event: KeyboardEvent) => void |
| keyup | 释放键盘时触发 | (event: KeyboardEvent) => void |
| compositionstart | 输入法开始输入时触发 | (event: CompositionEvent) => void |
| compositionupdate | 输入法输入过程中触发 | (event: CompositionEvent) => void |
| compositionend | 输入法输入结束时触发 | (event: CompositionEvent) => void |
Slots
| 插槽名 | 说明 |
|---|---|
| prefix | 输入框头部内容 |
| suffix | 输入框尾部内容 |
| prepend | 输入框前置内容（复合输入框） |
| append | 输入框后置内容（复合输入框） |
| clearIcon | 自定义清除图标 |
| loadingIcon | 自定义加载图标 |
Expose
| 属性/方法名 | 说明 | 类型 |
|---|---|---|
| ref | 输入框 DOM 元素 | HTMLInputElement | HTMLTextAreaElement | undefined |
| wrapperRef | 包裹元素 DOM | HTMLElement | undefined |
| focus | 使 input 获取焦点 | () => void |
| blur | 使 input 失去焦点 | () => void |
| select | 选中 input 中的文字 | () => void |
| clear | 清空 input 内容 | () => void |
| textLength | 当前输入值的显示字数（应用 countConfig 后的结果） | number |
主题变量
YhInput 支持 themeOverrides。组件本身消费以下输入框相关 CSS 变量：
| 变量名 | 说明 | 默认值 |
|---|---|---|
--yh-input-height | 输入框高度 | var(--yh-component-size-default) |
--yh-input-font-size | 字体大小 | var(--yh-font-size-base) |
--yh-input-padding | 输入框内边距 | 0 var(--yh-spacing-md) |
--yh-input-border-color | 边框颜色 | var(--yh-border-color) |
--yh-input-hover-border-color | 悬停边框色 | var(--yh-border-color-hover) |
--yh-input-focus-border-color | 聚焦边框色 | var(--yh-color-primary) |
--yh-input-bg-color | 背景颜色 | var(--yh-fill-color-blank) |
类型导出
| 名称 | 说明 |
|---|---|
YhInputProps | YhInput 的 props 类型 |
YhInputEmits | YhInput 的 emits 类型 |
YhInputSlots | YhInput 的 slots 类型 |
YhInputExpose | YhInput 的 expose 类型 |
YhInputType | 输入类型联合类型 |
YhInputSize | 输入尺寸联合类型 |
YhInputVariant | 视觉变体联合类型 |
YhInputStatus | 状态色联合类型 |
YhInputCountConfig | 字数统计配置类型 |
YhInputInstance | YhInput 的实例类型 |