外观
Input 输入框
约 1730 字大约 6 分钟
2025-10-31
输入框组件是用于用户输入信息的表单控件,支持多种输入类型、样式和交互方式。该组件具有高度的可定制性,可以满足各种输入场景的需求,包括文本输入、密码输入、数字输入等。通过丰富的属性配置和插槽支持,可以轻松实现美观且功能完善的输入界面。
基础使用
通过placeholder设置输入框为空时的占位符,通过border配置是否显示输入框的边框
<template>
<un-input placeholder="请输入内容" v-model="value"></un-input>
</template>
<script setup lang="uts">
import { ref } from 'vue'
const value = ref('')
</script>可清空内容
将clearable设置为true,会在输入框后方增加一个清空按钮。
<un-input v-model="value" placeholder="请输入内容" clearable></un-input>数字键盘
通过设置type为number,可以显示数字输入键盘。 web端需要配合inputmode属性才有效
<un-input v-model="value" placeholder="请输入内容" type="number" clearable></un-input>密码类型
通过设置password为true,可以将输入框设置为密码类型,输入的内容会显示为星号。
<un-input v-model="value" placeholder="请输入内容" password clearable></un-input>自定义样式
通过设置backgroundColor和border属性,可以自定义输入框的样式。
<un-input v-model="value" placeholder="请输入内容" backgroundColor="#f5f5f5" border="none" clearable></un-input>显示下划线
通过设置属性border为bottom即可变成一个下划线。
<un-input v-model="value" placeholder="请输入内容" border="bottom" clearable></un-input>禁用状态
通过设置disabled为true,可以禁用输入框,禁用状态下输入框不可编辑。
<un-input v-model="value" placeholder="禁用状态" disabled></un-input>圆形
通过设置shape为circle,可以将输入框设置为圆形。
<un-input v-model="value" placeholder="请输入内容" shape="circle"></un-input>前置图标
通过设置prefixIcon和prefixIconStyle属性,可以添加前置图标并自定义样式。
<un-input v-model="value" placeholder="前置图标" prefixIcon="search"></un-input>后置图标
通过设置suffixIcon和suffixIconStyle属性,可以添加后置图标并自定义样式。
<un-input v-model="value" placeholder="后置图标" suffixIcon="map-fill"></un-input>前置插槽
通过设置slot为prefix来指定前置插槽,可以自定义前置内容。
<un-input v-model="value" placeholder="前置插槽">
<template #prefix>
<un-icon name="user"></un-icon>
</template>
</un-input>后置插槽
通过设置slot为suffix来指定后置插槽,可以自定义后置内容,如验证码按钮。
<un-input v-model="value" placeholder="后置插槽">
<template #suffix>
<un-button text="后置插槽" type="success" size="mini"></un-button>
</template>
</un-input>change事件
通过绑定@change事件,可以在输入内容变化时触发相应的处理函数。
<template>
<un-input v-model="value" placeholder="请输入内容" @change="handleChange"></un-input>
<text>输入内容: {{ value }}</text>
</template>
<script setup lang="uts">
import { ref } from 'vue'
const value = ref('')
const handleChange = (val: string) => {
console.log('输入内容变化:', val)
}
</script>API
Props 属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| v-model / modelValue | 输入的值 | string | number | - |
| type | 输入框类型,见上方说明 | string | text |
| height | 输入框高度 | string | number | 40px |
| disabled | 是否禁用输入框 | boolean | false |
| disabledColor | 禁用状态时的背景色 | string | #f5f7fa |
| clearable | 是否显示清除控件 | boolean | false |
| password | 是否密码类型 | boolean | false |
| showPasswordToggle | 是否显示密码切换的眼睛图标 | boolean | true |
| maxlength | 最大输入长度,设置为 -1 的时候不限制最大长度 | string | number | -1 |
| placeholder | 输入框为空时的占位符 | string | - |
| placeholderClass | 指定placeholder的样式类,注意页面或组件的style中写了scoped时,需要在类名前写/deep/ | string | input-placeholder |
| placeholderStyle | 指定placeholder的样式,字符串/对象形式,如"color: red;" | string | object | color: #c0c4cc |
| showWordLimit | 是否显示输入字数统计,只在 type ="text"或type ="textarea"时有效 | boolean | false |
| confirmType | 设置右下角按钮的文字,兼容性详见uni-app文档 | string | done |
| confirmHold | 点击键盘右下角按钮时是否保持键盘不收起,H5无效 | boolean | false |
| holdKeyboard | focus时,点击页面的时候不收起键盘,微信小程序有效 | boolean | false |
| focus | 自动获取焦点,在 H5 平台能否聚焦以及软键盘是否跟随弹出,取决于当前浏览器本身的实现 | boolean | false |
| autoFocus | 自动获取焦点,与focus属性对比,此属性只会首次生效。仅uniapp-x平台有效 | boolean | false |
| autoBlur | 键盘收起时,是否自动失去焦点。仅uniapp平台有效 | boolean | false |
| ignoreCompositionEvent | 是否忽略组件内对文本合成系统事件的处理。为 false 时将触发 compositionstart、compositionend、compositionupdate 事件,且在文本合成期间会触发 input 事件 | boolean | true |
| disableDefaultPadding | 是否去掉 iOS 下的默认内边距,仅微信小程序,且type=textarea时有效 | boolean | false |
| alwaysEmbed | 强制 input 处于同层状态,默认 focus 时 input 会切到非同层状态 | boolean | false |
| cursor | 指定focus时光标的位置 | string | number | -1 |
| cursorSpacing | 输入框聚焦时底部与键盘的距离 | string | number | 30 |
| selectionStart | 光标起始位置,自动聚集时有效,需与selection-end搭配使用 | string | number | -1 |
| selectionEnd | 光标结束位置,自动聚集时有效,需与selection-start搭配使用 | string | number | -1 |
| adjustPosition | 键盘弹起时,是否自动上推页面 | boolean | true |
| inputAlign | 输入框内容对齐方式 | Enum | left |
| fontSize | 输入框字体的大小 | string | number | 15px |
| color | 输入框字体颜色 | string | #303133 |
| prefixIcon | 输入框前置图标 | string | - |
| prefixIconStyle | 前置图标样式,对象或字符串 | string | object | - |
| suffixIcon | 输入框后置图标 | string | - |
| suffixIconStyle | 后置图标样式,对象或字符串 | string | object | - |
| border | 边框类型,surround-四周边框,bottom-底部边框,none-无边框 | Enum | surround |
| readonly | 是否只读,与disabled不同之处在于disabled会置灰组件,而readonly则不会 | boolean | false |
| shape | 输入框形状,circle-圆形,square-方形 | Enum | square |
| formatter | 输入过滤或格式化函数 | function | null |
| customStyle | 自定义输入框样式,对象或字符串 | string | object | - |
| round | 设置圆角值 | string | 4px |
| borderColor | 边框颜色 | string | #e5e5e5 |
| backgroundColor | 背景颜色 | string | #ffffff |
| inputmode | 输入框类型 | Enum | text |
Events 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| blur | 输入框失去焦点时触发 | Function |
| focus | 输入框聚焦时触发 | Function |
| confirm | 点击完成按钮时触发 | Function |
| keyboardheightchange | 键盘高度发生变化的时候触发此事件 | Function |
| input | 内容发生变化触发此事件 | Function |
| change | 内容发生变化触发此事件 | Function |
| clear | 点击清空内容 | Function |
Slots 插槽
| 名称 | 说明 |
|---|---|
| prefix | 输入框前置内容 |
| suffix | 输入框后置内容 |
