![uni-app官网](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/logo.png)
![uni-app官网](https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/uni-app.png)
简体中文
单行输入框。
html规范中input不仅是输入框,还有radio、checkbox、时间、日期、文件选择功能。在uni-app规范中,input仅仅是输入框。其他功能uni-app有单独的组件或API:radio组件、checkbox组件、时间选择、日期选择、图片选择、视频选择、多媒体文件选择(含图片视频)、通用文件选择。
属性名 | 类型 | 默认值 | 说明 | 平台差异说明 |
---|---|---|---|---|
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、App需要点击按钮获取焦点的,必须使用@touchend.prevent="onTap"阻止键盘收起默认事件才能获取焦点关于软键盘弹出的逻辑说明,小程序、nvue需使用组件的 focus()、blur() 方法控制焦点 |
confirm-type | String | done | 设置键盘右下角按钮的文字,仅在 type="text" 时生效。有效值 | 微信小程序、App、H5、快手小程序、京东小程序 |
confirm-hold | Boolean | false | 点击键盘右下角按钮时是否保持键盘不收起 | App(3.3.7+)、H5 (3.3.7+)、微信小程序、支付宝小程序、百度小程序、QQ小程序、京东小程序 |
cursor | Number | 指定focus时的光标位置 | ||
cursor-color | String | 光标颜色 | 微信小程序 3.1.0+、H5(4.0+)、App-Vue(4.0+) | |
selection-start | Number | -1 | 光标起始位置,自动聚集时有效,需与selection-end搭配使用 | |
selection-end | Number | -1 | 光标结束位置,自动聚集时有效,需与selection-start搭配使用 | |
adjust-position | Boolean | true | 键盘弹起时,是否自动上推页面 | App-Android(vue 页面 softinputMode 为 adjustResize 时无效,使用 x5 内核时无效)、微信小程序、百度小程序、QQ小程序、京东小程序 |
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不支持 |
always-embed | Boolean | false | 强制 input 处于同层状态,默认 focus 时 input 会切到非同层状态 (仅在 iOS 下生效) | 微信小程序 2.10.4+ |
hold-keyboard | Boolean | false | focus时,点击页面的时候不收起键盘 | 微信小程序 2.8.2+ |
safe-password-cert-path | String | 安全键盘加密公钥的路径,只支持包内路径 | 微信小程序 2.18.0+ | |
safe-password-length | Number | 安全键盘输入密码长度 | 微信小程序 2.18.0+ | |
safe-password-time-stamp | Number | 安全键盘加密时间戳 | 微信小程序 2.18.0+ | |
safe-password-nonce | String | 安全键盘加密盐值 | 微信小程序 2.18.0+ | |
safe-password-salt | String | 安全键盘计算 hash 盐值,若指定custom-hash 则无效 | 微信小程序 2.18.0+ | |
safe-password-custom-hash | String | 安全键盘计算 hash 的算法表达式,如 md5(sha1('foo' + sha256(sm3(password + 'bar')))) | 微信小程序 2.18.0+ | |
random-number | Boolean | false | 当 type 为 number, digit, idcard 数字键盘是否随机排列 | 支付宝小程序 1.9.0+ |
controlled | Boolean | false | 是否为受控组件。为 true 时,value 内容会完全受 setData 控制 | 支付宝小程序 1.9.0+ |
always-system | Boolean | false | 是否强制使用系统键盘和 Web-view 创建的 input 元素。为 true 时,confirm-type、confirm-hold 可能失效 | 支付宝小程序 2.7.3+ |
inputmode | String | "text" | 是一个枚举属性,它提供了用户在编辑元素或其内容时可能输入的数据类型的提示。有效值 | H5(3.6.16+)、App-vue(3.6.16+) |
@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 一个字符串,将替换输入框的内容。仅微信小程序支持。input
组件上有默认的 min-height
样式,如果 min-height
的值大于 height
的值那么 height
样式无效。v-if
进行整体切换。cursor-color
属性在iOS下的格式为十六进制颜色值 #000000,安卓下只支持 default 和 green,Skyline 下无限制。 <!-- 错误写法 -->
<input :type="isText?'text':'number'" placeholder="请输入内容" />
<!-- 正确写法 -->
<input v-if="isText" type="text" placeholder="请输入文本" />
<input v-else type="number" placeholder="请输入数字" />
值 | 说明 | 平台差异说明 |
---|---|---|
text | 文本输入键盘 | |
number | 数字输入键盘 | 均支持,App平台、H5平台 3.1.22 以下版本 vue 页面在 iOS 平台显示的键盘包含负数和小数。 |
idcard | 身份证输入键盘 | 微信、支付宝、百度、QQ小程序、快手小程序、京东小程序 |
digit | 带小数点的数字键盘 | 均支持,App平台、H5平台 vue 页面在 iOS 平台显示的键盘包含负数(原生键盘不支持负号)。 |
tel | 电话输入键盘 | |
safe-password | 密码安全输入键盘 | 微信小程序 |
nickname | 昵称输入键盘 | 微信小程序 |
注意事项
number
类型只支持输入整型数字。微信开发者工具上体现不出效果,请使用真机预览。digit
类型。仅 App-nvue-iOS 支持
值 | 说明 |
---|---|
oneTimeCode | 一次性验证码,常用于短信验证码输入 |
弹出软键盘的右下角按钮的文字。
值 | 说明 | 平台差异说明 |
---|---|---|
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+) |
新增于 uni-app 3.6.16+ inputmode是html规范后期更新的内容。各家小程序还未支持此属性。
在符合条件的高版本webview里,uni-app的web和app-vue平台中可使用本属性。
值 | 说明 |
---|---|
none | 无虚拟键盘。在应用程序或者站点需要实现自己的键盘输入控件时很有用。 |
text | 使用用户本地区域设置的标准文本输入键盘。 |
decimal | 小数输入键盘,包含数字和分隔符(通常是“ . ”或者“ , ”),设备可能也可能不显示减号键。 |
numeric | 数字输入键盘,所需要的就是 0 到 9 的数字,设备可能也可能不显示减号键。 |
tel | 电话输入键盘,包含 0 到 9 的数字、星号(*)和井号(#)键。表单输入里面的电话输入通常应该使用 <input type="tel"> 。 |
search | 为搜索输入优化的虚拟键盘,比如,返回键可能被重新标记为“搜索”,也可能还有其他的优化。 |
为邮件地址输入优化的虚拟键盘,通常包含"@"符号和其他优化。表单里面的邮件地址输入应该使用 <input type="email"> 。 | |
url | 为网址输入优化的虚拟键盘,比如,“/”键会更加明显、历史记录访问等。表单里面的网址输入通常应该使用 <input type="url"> 。 |
注意事项
Chrome >= 66
、Edge >= 79
、Firefox >= 95
、Chrome Android >= 66
、Firefox for Android >= 79
、Safari on iOS >= 12.2
、WebView Android >= 66
inputmode
和 type
、comfirm-tye
3个相似的属性,它们的区别详解如下:
app-vue在iOS上,webview中的软键盘弹出时,默认在软键盘上方有一个横条,显示着:上一项、下一项和完成等按钮。 如不想显示这个横条,可以配置softinputNavBar: 'none'
配置方式,在 pages.json 中某个页面或全局配置 style
"app-plus": {
"softinputNavBar": "none"
}
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平台因不同浏览器而异
配置方式,在 pages.json 中配置 style
"app-plus": {
"softinputMode": "adjustResize"
}
注意
touch
事件并使用prevent
修饰符(仅支持App、H5,其他平台可以通过设置focus
来使输入框重新获取焦点),例如在确认按钮上使用:@touchend.prevent="onTap"
以上为默认逻辑,uni-app同时提供了隐藏软键盘的api:uni.hideKeyboard()
在app平台,有titleNView配置的searchinput原生输入框和plus.nativeObj.view的drawinput。这两种方式的输入框都是原生的,不是webview里的。
adjustPan|adjustResize
模式影响input示例 查看演示
以下示例代码,来自于hello uni-app项目,推荐使用HBuilderX,新建uni-app项目,选择hello uni-app模板,可直接体验完整示例。
Template
Script
<!-- 本示例未包含完整css,获取外链css请参考上文,在hello uni-app项目中查看 -->
<template>
<view>
<view class="uni-common-mt">
<view class="uni-form-item uni-column">
<view class="title">可自动聚焦的input</view>
<input class="uni-input" focus placeholder="自动获得焦点" />
</view>
<view class="uni-form-item uni-column">
<view class="title">键盘右下角按钮显示为搜索</view>
<input class="uni-input" confirm-type="search" placeholder="键盘右下角按钮显示为搜索" />
</view>
<view class="uni-form-item uni-column">
<view class="title">控制最大输入长度的input</view>
<input class="uni-input" maxlength="10" placeholder="最大输入长度为10" />
</view>
<view class="uni-form-item uni-column">
<view class="title">实时获取输入值:{{inputValue}}</view>
<input class="uni-input" @input="onKeyInput" placeholder="输入同步到view中" />
</view>
<view class="uni-form-item uni-column">
<view class="title">控制输入的input</view>
<input class="uni-input" @input="replaceInput" v-model="changeValue" placeholder="连续的两个1会变成2" />
</view>
<!-- #ifndef MP-BAIDU -->
<view class="uni-form-item uni-column">
<view class="title">控制键盘的input</view>
<input class="uni-input" ref="input1" @input="hideKeyboard" placeholder="输入123自动收起键盘" />
</view>
<!-- #endif -->
<view class="uni-form-item uni-column">
<view class="title">数字输入的input</view>
<input class="uni-input" type="number" placeholder="这是一个数字输入框" />
</view>
<view class="uni-form-item uni-column">
<view class="title">密码输入的input</view>
<input class="uni-input" password type="text" placeholder="这是一个密码输入框" />
</view>
<view class="uni-form-item uni-column">
<view class="title">带小数点的input</view>
<input class="uni-input" type="digit" placeholder="带小数点的数字键盘" />
</view>
<view class="uni-form-item uni-column">
<view class="title">身份证输入的input</view>
<input class="uni-input" type="idcard" placeholder="身份证输入键盘" />
</view>
<view class="uni-form-item uni-column">
<view class="title">控制占位符颜色的input</view>
<input class="uni-input" placeholder-style="color:#F76260" placeholder="占位符字体是红色的" />
</view>
<view class="uni-form-item uni-column">
<view class="title"><text class="uni-form-item__title">带清除按钮的输入框</text></view>
<view class="uni-input-wrapper">
<input class="uni-input" placeholder="带清除按钮的输入框" :value="inputClearValue" @input="clearInput" />
<text class="uni-icon" v-if="showClearIcon" @click="clearIcon"></text>
</view>
</view>
<view class="uni-form-item uni-column">
<view class="title"><text class="uni-form-item__title">可查看密码的输入框</text></view>
<view class="uni-input-wrapper">
<input class="uni-input" placeholder="请输入密码" :password="showPassword" />
<text class="uni-icon" :class="[!showPassword ? 'uni-eye-active' : '']"
@click="changePassword"></text>
</view>
</view>
</view>
</view>
</template>