#### input
输入框。
**属性说明**
|属性名|类型|默认值|说明|平台差异说明|
|:-|:-|:-|:-|:-|
|value|String||输入框的初始内容||
|type|String|text|input 的类型|H5 暂未支持动态切换,详见下方 Tips,请使用 v-if 进行整体切换|
|text-content-type|String| |文本区域的语义,根据类型自动填充|仅 App-nvue-iOS 支持|
|password|Boolean|false|是否是密码类型|H5和App写此属性时,type失效|
|placeholder|String||输入框为空时占位符||
|placeholder-style|String||指定 placeholder 的样式||
|placeholder-class|String|"input-placeholder"|指定 placeholder 的样式类,注意页面或组件的style中写了scoped时,需要在类名前写/deep/||
|disabled|Boolean|false|是否禁用||
|maxlength|Number|140|最大输入长度,设置为 -1 的时候不限制最大长度||
|cursor-spacing|Number|0|指定光标与键盘的距离,单位 px 。取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离|App、微信小程序、百度小程序、QQ小程序、京东小程序|
|focus|Boolean|false|获取焦点。|在 H5 平台能否聚焦以及软键盘是否跟随弹出,取决于当前浏览器本身的实现。nvue 页面不支持,需使用组件的 focus()、blur() 方法控制焦点|
|confirm-type|String|done|设置键盘右下角按钮的文字,仅在 type="text" 时生效。|微信小程序、App、H5、快手小程序、京东小程序|
|confirm-hold|Boolean|false|点击键盘右下角按钮时是否保持键盘不收起|App-Vue (3.3.7+)、H5 (3.3.7+)、微信小程序、支付宝小程序、百度小程序、QQ小程序、京东小程序|
|cursor|Number||指定focus时的光标位置||
|selection-start|Number|-1|光标起始位置,自动聚集时有效,需与selection-end搭配使用||
|selection-end|Number|-1|光标结束位置,自动聚集时有效,需与selection-start搭配使用||
|adjust-position|Boolean|true|键盘弹起时,是否自动上推页面|App-Android(vue 页面 softinputMode 为 adjustResize 时无效,使用 x5 内核时无效)、微信小程序、百度小程序、QQ小程序、京东小程序|
|hold-keyboard|boolean|false|focus时,点击页面的时候不收起键盘|微信小程序2.8.2|
|auto-blur|boolean|false|键盘收起时,是否自动失去焦点|App-Vue 3.0.0+|
|ignoreCompositionEvent|boolean|true|是否忽略组件内对文本合成系统事件的处。为 `false` 时将触发 `compositionstart、compositionend、compositionupdate` 事件,且在文本合成期间会触发 `input` 事件|App-vue (3.4.4+)、H5 (3.4.4+)、App-nvue不支持|
|@input|EventHandle||当键盘输入时,触发input事件,event.detail = {value}|差异见下方 Tips|
|@focus|EventHandle||输入框聚焦时触发,event.detail = { value, height },height 为键盘高度|仅微信小程序、京东小程序、App(2.2.3+) 、QQ小程序支持 height|
|@blur|EventHandle||输入框失去焦点时触发,event.detail = {value: value}|快手小程序不支持|
|@confirm|EventHandle||点击完成按钮时触发,event.detail = {value: value}| 快手小程序不支持|
|@keyboardheightchange|eventhandle||键盘高度发生变化的时候触发此事件,event.detail = {height: height, duration: duration}|微信小程序基础库2.7.0+、App 3.1.0+|
**Tips**
- `input` 事件处理函数可以直接 return 一个字符串,将替换输入框的内容。仅微信小程序支持。
- 如果遇到 value 属性设置不生效的问题参考:[组件属性设置不生效解决办法](/vue-api?id=_4-组件属性设置不生效解决办法)
- `input` 组件上有默认的 `min-height` 样式,如果 `min-height` 的值大于 `height` 的值那么 `height` 样式无效。
- H5 暂未支持动态切换,请使用 `v-if`进行整体切换。
```html
```
**type 有效值**
|值|说明|平台差异说明|
|:-|:-|:-|
|text|文本输入键盘||
|number|数字输入键盘|均支持,App平台、H5平台 3.1.22 以下版本 vue 页面在 iOS 平台显示的键盘包含负数和小数。|
|idcard|身份证输入键盘|微信、支付宝、百度、QQ小程序、快手小程序、京东小程序|
|digit|带小数点的数字键盘|均支持,App平台、H5平台 vue 页面在 iOS 平台显示的键盘包含负数。|
|tel|电话输入键盘|仅App的nvue页面支持|
**注意事项**
- 原html规范中input不仅是输入框,还有radio、checkbox、时间、日期、文件选择功能。在uni-app和小程序规范中,input仅仅是输入框。其他功能uni-app有单独的组件或API:[radio组件](https://uniapp.dcloud.io/component/radio)、[checkbox组件](https://uniapp.dcloud.io/component/checkbox)、[时间选择](https://uniapp.dcloud.io/component/picker?id=%e6%97%b6%e9%97%b4%e9%80%89%e6%8b%a9%e5%99%a8)、[日期选择](https://uniapp.dcloud.io/component/picker?id=%e6%97%a5%e6%9c%9f%e9%80%89%e6%8b%a9%e5%99%a8)、[图片选择](https://uniapp.dcloud.io/api/media/image?id=chooseimage)、[视频选择](https://uniapp.dcloud.io/api/media/video?id=choosevideo)、[多媒体文件选择(含图片视频)](https://uniapp.dcloud.io/api/media/video?id=choosemedia)、[通用文件选择](https://uniapp.dcloud.io/api/media/file?id=choosefile)。
- 小程序平台,`number` 类型只支持输入整型数字。微信开发者工具上体现不出效果,请使用真机预览。
- 如果需要在小程序平台输入浮点型数字,请使用 `digit` 类型。
- 小程序端input在置焦时,会表现为原生控件,此时会层级变高。如需前端组件遮盖input,需让input失焦,或使用cover-view等覆盖原生控件的方案,[参考](https://uniapp.dcloud.io/component/native-component)。具体来讲,阿里小程序的input为text且置焦为原生控件;微信、头条、QQ所有input置焦均为原生控件;百度小程序置焦时仍然是非原生的。也可以参考[原生控件](https://uniapp.dcloud.io/component/native-component)文档
- input组件若不想弹出软键盘,可设置为disabled
**text-content-type 有效值**
|值|说明|
|:-|:-|
|oneTimeCode|一次性验证码|
**confirm-type 有效值**
|值|说明|平台差异说明|
|:-|:-|:-|
|send|右下角按钮为“发送”|微信、支付宝、百度小程序、快手小程序、京东小程序、app-nvue、app-vue和h5(2.9.9+,且要求设备webview内核Chrome81+、Safari13.7+)|
|search|右下角按钮为“搜索”||
|next|右下角按钮为“下一个”|微信、支付宝、百度小程序、快手小程序、京东小程序、app-nvue、app-vue和h5(2.9.9+,且要求设备webview内核Chrome81+、Safari13.7+)|
|go|右下角按钮为“前往”||
|done|右下角按钮为“完成”|微信、支付宝、百度小程序、快手小程序、京东小程序、app-nvue、app-vue和h5(2.9.9+,且要求设备webview内核Chrome81+、Safari13.7+)|
- App平台的nvue页面,如果是weex编译模式,需通过weex的api设置(weex模式已被淘汰)
- App平台的vue页面及 H5平台 的弹出键盘使用的是浏览器控制的键盘,在Chrome81+、Safari13.7+之前,键盘右下角文字只能设置完成和搜索,从Chrome81+、Safari13.7+起支持设置发送、下一个。
- App平台涉及聊天的建议使用nvue,一方面因为app-vue控制键盘右下角按键文字为“发送”对webview内核有要求,另一方面聊天记录如使用sroll-view,过长的内容在app-vue上会有性能问题。
#### App平台iOS端软键盘上方横条去除方案
App平台在iOS上,webview中的软键盘弹出时,默认在软键盘上方有一个横条,显示着:上一项、下一项和完成等按钮。如不想显示这个横条,可以配置softinputNavBar: 'none'
配置方式,在 pages.json 中配置 style
```json
"app-plus": {
"softinputNavBar": "none"
}
```
- 如需使用js动态设置softinputNavBar
```javascript
this.$scope.$getAppWebview().setStyle({
softinputNavBar: 'none'
})
//this.$scope.$getAppWebview()相当于html5plus里的plus.webview.currentWebview()。在uni-app里vue页面直接使用plus.webview.currentWebview()无效
```
如果是nvue页面,iOS默认就没有键盘上方的横条,无需任何设置。
#### 关于软键盘弹出的逻辑说明
App平台软键盘弹出有 adjustResize|adjustPan 两种模式,默认为 adjustPan 模式,小程序平台只支持 adjustPan 模式,H5平台因不同浏览器而异
- adjustResize:软键盘弹出时,webview窗体高度挤压。屏幕高度=webview窗体高度+软键盘高度
- adjustPan:软键盘弹出时,webview窗体高度不变,但窗体上推,以保证输入框不被软键盘盖住
配置方式,在 pages.json 中配置 style
```json
"app-plus": {
"softinputMode": "adjustResize"
}
```
**注意**
- adjustResize模式在Android App上,弹起键盘和收回键盘时,因为要重设webview窗体高度,可能会在个别安卓机型闪现灰屏或漏出下层页面内容。
- 小程序端在 input 聚焦期间,避免使用 css 动画。
- H5平台只能在用户交互时修改 focus 生效。
- 如果遇到 focus 属性设置不生效的问题参考:[组件属性设置不生效解决办法](/vue-api?id=_4-组件属性设置不生效解决办法)
- 如需禁止点击其他位置收起键盘的默认行为,可以监听`touch`事件并使用`prevent`修饰符(仅支持App、H5,其他平台可以通过设置`focus`来使输入框重新获取焦点),例如在确认按钮上使用:```@touchend.prevent="onTap"```
#### 关于软键盘收起的逻辑说明
- Android上在软键盘弹出后,点击back或点击非置焦区域可收起软键盘。
- iOS上如果软键盘上方有带有“完成”的横条,则需要点完成才能收起键盘;如果没有软键盘上方横条,则点击非input/textarea区域即可收起软键盘
以上为默认逻辑,uni-app同时提供了隐藏软键盘的api:[uni.hideKeyboard()](https://uniapp.dcloud.io/api/key?id=hidekeyboard)
#### App平台原生输入框的说明
在app平台,有titleNView配置的[searchinput](/collocation/pages?id=app-titlenview)原生输入框和plus.nativeObj.view的drawinput。这两种方式的输入框都是原生的,不是webview里的。
- 原生输入框在iOS上不会有软键盘上方的横条
- 原生输入框一样受配置的`adjustPan|adjustResize`模式影响
**input示例** [查看演示](https://hellouniapp.dcloud.net.cn/pages/component/input/input)
以下示例代码,来自于[hello uni-app项目](https://github.com/dcloudio/hello-uniapp),推荐使用HBuilderX,新建uni-app项目,选择hello uni-app模板,可直接体验完整示例。
```html
可自动聚焦的input
键盘右下角按钮显示为搜索
控制最大输入长度的input
实时获取输入值:{{inputValue}}
控制输入的input
控制键盘的input
数字输入的input
密码输入的input
带小数点的input
身份证输入的input
控制占位符颜色的input
```
```javascript
export default {
data() {
return {
title: 'input',
focus: false,
inputValue: '',
changeValue: ''
}
},
methods: {
onKeyInput: function(event) {
this.inputValue = event.target.value
},
replaceInput: function(event) {
var value = event.target.value;
if (value === '11') {
this.changeValue = '2';
}
},
hideKeyboard: function(event) {
if (event.target.value === '123') {
uni.hideKeyboard();
}
}
}
}
```
![uniapp](https://bjetxgzv.cdn.bspapp.com/VKCEYUGU-uni-app-doc/f713b320-4f30-11eb-b680-7980c8a877b8.png)
**扩展**
- uni ui提供了easyinput组件,提供了常用的封装,可搭配uni-forms组件,支持表单验证、支持各种常用设置。[详见](https://ext.dcloud.net.cn/plugin?id=3455)
- uni ui提供了combox组件,可选可输入,常用词免输入。[详见](https://ext.dcloud.net.cn/plugin?id=1261)
- uni ui提供了搜索框ui组件,插件市场还有封装好的页面模板。[详见](https://ext.dcloud.net.cn/search?q=search)。云端一体搜索模板功能完善,推荐使用:[https://ext.dcloud.net.cn/plugin?id=3851](https://ext.dcloud.net.cn/plugin?id=3851)
- uni-app插件市场有输入文字后自动提示候选的组件,可搜索 [autocomplete](https://ext.dcloud.net.cn/search?q=autocomplete) 查看。
- 插件市场有各种类型的模拟键盘,比如车牌键盘、身份证键盘,可去插件市场搜索 [键盘](https://ext.dcloud.net.cn/search?q=%E9%94%AE%E7%9B%98)。