# input

Single line input box.

The input in the html specification is not only an input box, but also radio, checkbox, time, date, and file selection functions. In the uni-app specification, input is just an input box. Other functions uni-app has a separate component or API: radio component, checkbox component, [time selection](https://uniapp.dcloud.io/component/picker?id=%e6%97%b6%e9%97%b4%e9%80%89%e6%8b%a9%e5% 99%a8), [date picker](https://uniapp.dcloud.io/component/picker?id=%e6%97%a5%e6%9c%9f%e9%80%89%e6%8b%a9 %e5%99%a8), Image Selection, [Video Selection](https://uniapp.dcloud.io/api /media/video?id=choosevideo), multimedia file selection (including picture and video), [general file selection](https: //uniapp.dcloud.io/api/media/file?id=choosefile).

# Attribute description

Property Name Type Default Value Description Platform Difference Description
value String 输入框的初始内容
type String text input 的类型 有效值
text-content-type String Semantics of the text area, automatically filled according to the type valid value Only supported by App-nvue-iOS
password Boolean false Whether it is a password type When H5 and App write this attribute, the type is invalid
placeholder String The placeholder when the input box is empty
placeholder-style String 指定 placeholder 的样式
placeholder-class String "input-placeholder" 指定 placeholder 的样式类,注意页面或组件的style中写了scoped时,需要在类名前写/deep/ 抖音小程序、飞书小程序、快手小程序不支持
disabled Boolean false whether to disable
maxlength Number 140 Maximum input length, when set to -1, there is no limit to the maximum length
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 Set the text of the button in the lower right corner of the keyboard, only valid when type="text". Valid value WeChat MiniApp, App, H5, Kuaishou MiniApp, Jingdong MiniApp
confirm-hold Boolean false Whether to keep the keyboard closed when the button in the lower right corner of the keyboard is clicked App (3.3.7+), H5 (3.3.7+), WeChat MiniApp, Alipay MiniApp, Baidu MiniApp, QQ MiniApp, Jingdong MiniApp
cursor Number 指定focus时的光标位置
cursor-color String 光标颜色 微信小程序 3.1.0+、H5(4.0+)、App-Vue(4.0+)
selection-start Number -1 Cursor starting position, valid when auto-gathering, need to be used together with selection-end
selection-end Number -1 Cursor end position, valid when auto-gathering, must be used together with selection-start
adjust-position Boolean true Whether to automatically push up the page when the keyboard pops up App-Android (invalid when the vue page softinputMode is adjustResize, invalid when using the x5 kernel), WeChat MiniApp, Baidu MiniApp, QQ MiniApp, Jingdong MiniApp
auto-blur Boolean false Whether to automatically lose focus when the keyboard is closed App-Vue 3.0.0+
ignoreCompositionEvent Boolean true Whether to ignore the processing of text composition system events in the component. When it is false, compositionstart, compositionend, compositionupdate events will be triggered, and input events will be triggered during text composition App-vue (3.4.4+), H5 (3.4.4+), App-nvue does not Support
always-embed Boolean false Force the input to be in the same layer state, and the input will switch to a non-same layer state when it is in focus by default (only valid under iOS) WeChat MiniApp 2.10.4+
hold-keyboard Boolean false In focus, the keyboard will not be put away when the page is clicked WeChat MiniApp 2.8.2+
safe-password-cert-path String The path of the safe keyboard encryption public key, only supports the path in the package WeChat MiniApp 2.18.0+
safe-password-length Number Safe keyboard input password length WeChat MiniApp 2.18.0+
safe-password-time-stamp Number Safe keyboard encryption time stamp WeChat MiniApp 2.18.0+
safe-password-nonce String Safe keyboard encryption salt value WeChat MiniApp 2.18.0+
safe-password-salt String Safe keyboard calculates hash salt value, if custom-hash is specified, it will be invalid WeChat MiniApp 2.18.0+
safe-password-custom-hash String Safe keyboard calculation hash algorithm expression, such as md5(sha1('foo' + sha256(sm3(password + 'bar')))) WeChat MiniApp 2.18.0 +
random-number Boolean false When the type is number, digit, idcard, whether the number keyboard is arranged randomly Alipay MiniApp 1.9.0+
controlled Boolean false Whether it is a controlled component. When it is true, the value content will be completely controlled by setData Alipay MiniApp 1.9.0+
always-system Boolean false Whether to force the use of the system keyboard and input elements created by the web-view. When it is true, confirm-type and confirm-hold may be invalid Alipay MiniApp 2.7.3+
inputmode String "text" is an enumerated property that provides hints about the type of data the user may enter when editing the element or its contents. valid value H5 (3.6.16+), App-vue (3.6.16+)
@input EventHandle When the keyboard enters, the input event is triggered, event.detail = {value} For the difference, see Tips below
@focus EventHandle triggered when the input box is focused, event.detail = { value, height }, height is the height of the keyboard Only WeChat MiniApp, Jingdong MiniApp, App (2.2.3+), QQ MiniApp support height
@blur EventHandle triggered when the input box loses focus, event.detail = {value: value} Kuaishou MiniApp does not support
@confirm EventHandle triggered when the Done button is clicked, event.detail = {value: value}   Kuaishou MiniApp does not support
@keyboardheightchange eventhandle This event is triggered when the keyboard height changes, event.detail = {height: height, duration: duration} WeChat MiniApp base library 2.7.0+, App 3.1.0+

Tips

  • input 事件处理函数可以直接 return 一个字符串,将替换输入框的内容。仅微信小程序支持。
  • 如果遇到 value 属性设置不生效的问题参考:组件属性设置不生效解决办法
  • input 组件上有默认的 min-height 样式,如果 min-height 的值大于 height 的值那么 height 样式无效。
  • 微信小程序 cursor-color 属性在iOS下的格式为十六进制颜色值 #000000,安卓下只支持 default 和 green,Skyline 下无限制。
  • Webapp-plus vue 上 iOS 自带键盘的智能标点功能会导致:在 type 为 numberdigit 时,连续输入两次 . 后,在第三次输入 . 时,会触发两次 deleteContentBackward(删除) 的输入外加一次 insertText 为 (三个点) 的输入。会导致表现异常,关闭智能标点功能后正常。

# type valid values

Value Description Platform Difference Description
text text input keyboard
number Number input keyboard All support, App platform, H5 platform version 3.1.22 and below, the keyboard displayed on the iOS platform on the vue page contains negative numbers and decimals.
idcard ID card input keyboard WeChat, Alipay, Baidu, QQ MiniApp, Kuaishou MiniApp, Jingdong MiniApp
digit 带小数点的数字键盘 均支持,App平台、H5平台 vue 页面在 iOS 平台显示的键盘包含负数(原生键盘不支持负号)。
tel 电话输入键盘
safe-password Password safe input keyboard WeChat MiniApp
nickname nickname input keyboard WeChat MiniApp

注意事项

  • 小程序平台,number 类型只支持输入整型数字。微信开发者工具上体现不出效果,请使用真机预览。
  • 如果需要输入浮点型数字,请使用 digit 类型。 -When the input on the MiniApp terminal is focused, it will behave as a native control, and the level will become higher at this time. If you need front-end components to cover the input, you need to make the input out of focus, or use cover-view and other solutions to cover native controls, reference.Specifically, the input of the Ali MiniApp is text and the focus is a native control; all the input focus of WeChat, Toutiao, and QQ are native controls; the focus of the Baidu MiniApp is still non-native. You can also refer to Native Control document
  • input组件若不想弹出软键盘,可设置为disabled
  • placeholder-style指定样式类font-size单位为rpx时,抖音小程序、飞书小程序、快手小程序不支持,可使用uni.upx2px()将rpx单位值转换成px。

# text-content-type valid values

Only supported by App-nvue-iOS

value description
oneTimeCode one-time verification code, often used for SMS verification code input

# confirm-type valid values

The text of the button in the lower right corner of the popup soft keyboard.

Value Description Platform Difference Description
send The button in the lower right corner is "Send" WeChat, Alipay, Baidu MiniApp, Kuaishou MiniApp, Jingdong MiniApp, app-nvue, app-vue and h5 (2.9.9+, and require the device webview kernel Chrome81+, Safari13 .7+)
search The button in the lower right corner is "Search"
next The button in the lower right corner is "Next" WeChat, Alipay, Baidu MiniApp, Kuaishou MiniApp, Jingdong MiniApp, app-nvue, app-vue and h5 (2.9.9+, and requires the device webview kernel Chrome81+, Safari13.7+)
go The button in the lower right corner is "Go"
done The button in the lower right corner is "Done" WeChat, Alipay, Baidu MiniApp, Kuaishou MiniApp, Jingdong MiniApp, app-nvue, app-vue and h5 (2.9.9+, and require the device webview kernel Chrome81+, Safari13 .7+)
  • The vue page of the App platform and the pop-up keyboard of the H5 platform use a browser-controlled keyboard. Before Chrome81+ and Safari13.7+, the text in the lower right corner of the keyboard can only be set and searched. It is supported from Chrome81+ and Safari13.7+ Set send, next.
  • It is recommended to use nvue on the app platform that involves chatting. On the one hand, because app-vue controls the key text in the lower right corner of the keyboard as "send", it requires the webview kernel. There will be performance issues on vue.

# inputmode valid values

Added in uni-app 3.6.16+ inputmode is the content of the later update of the html specification. Various MiniApp not yet supported this attribute.

In the qualified high-version webview, this attribute can be used in the web and app-vue platforms of uni-app.

value description
none No virtual keyboard. Useful when an application or site needs to implement its own keyboard input control.
text Use the standard text input keyboard for the user's locale.
decimal A decimal input keyboard, consisting of digits and a separator (usually " ." or " , "), the device may or may not display a minus key.
numeric A numeric input keypad, all that is required is the digits 0 to 9, the device may or may not display a minus key.
tel Telephone input keypad, consisting of the digits 0 through 9, the asterisk (*) and pound (#) keys. Telephone inputs inside form inputs should generally use <input type="tel"> .
search Virtual keyboard optimized for search input, e.g. the return key may be relabeled as "search", and there may be other optimizations as well.
email Virtual keyboard optimized for email address typing, usually containing "@" symbols and other optimizations. Email address inputs in forms should use <input type="email"> .
url Optimized virtual keyboard for URL input, for example, "/" key will be more visible, history access, etc. URL inputs in forms should generally use <input type="url"> .

注意事项

  • inputmode compatibility: Chrome >= 66, Edge >= 79, Firefox >= 95, Chrome Android >= 66, Firefox for Android >= 79, Safari on iOS >= 12.2, WebView Android >= 66
  • The input component has 3 similar attributes inputmode and type, comfirm-tye, and their differences are explained in detail as follows:
    • type: In uni-app and MiniApp, it is just an input box, which defines how the input works. This value determines what value can be entered. For example, number can only enter numbers.
    • confirm-type: Define the text of the key in the lower right corner of the keyboard
    • inputmode: The inputmode attribute is an optimization for the keyboard when certain values are used.
      • When inputmode and confirm-type are used at the same time, if the settings conflict, the type of the key in the lower right corner of the keyboard is determined by the confirm-type
      • type 属性和 inputmode 属性并不冲突

# App platform iOS side of the top of the horizontal bar to remove the program

When app-vue is on iOS, when the soft keyboard in webview pops up, there is a horizontal bar above the soft keyboard by default, showing: buttons for previous item, next item, and completion. If you don't want to display this horizontal bar, you can configure softinputNavBar: 'none'

Configuration method, configure style on a certain page or globally in pages.json

"app-plus": {
	"softinputNavBar": "none"
}
  • If you need to use js to dynamically set softinputNavBar
this.$scope.$getAppWebview().setStyle({
	softinputNavBar: 'none'
})
//this.$scope.$getAppWebview() is equivalent to plus.webview.currentWebview() in html5plus. Using plus.webview.currentWebview() directly on the vue page in uni-app is invalid

If it is an nvue page, iOS does not have a horizontal bar above the keyboard by default, and no settings are required.

# About the logical description of the soft keyboard pop-up

The App platform soft keyboard pops up with two modes: adjustResize|adjustPan. The default is the adjustPan mode. The MiniApp platform only supports the adjustPan mode. The H5 platform varies with different browsers

  • adjustResize: When the soft keyboard pops up, the height of the webview form is squeezed. Screen height = webview form height + soft keyboard height
  • adjustPan: When the soft keyboard pops up, the height of the webview form remains unchanged, but the form is pushed up to ensure that the input box is not covered by the soft keyboard

Configuration method, configure style in pages.json

"app-plus": {
	"softinputMode": "adjustResize"
}

Notice

  • In adjustResize mode on Android App, when the keyboard is popped up and retracted, because the height of the webview form needs to be reset, a gray screen may flash or the content of the underlying page may be leaked on some Android models. -Avoid using css animations during input focus on the MiniApp side.
  • H5平台只能在用户交互时修改 focus 生效。
  • 如果遇到 focus 属性设置不生效的问题参考:组件属性设置不生效解决办法
  • If you want to prohibit the default behavior of clicking other positions to close the keyboard, you can listen to the touch event and use the prevent modifier (only App, H5 is supported, other platforms can set focus to make the input box regain focus) , such as using on the confirm button: @touchend.prevent="onTap"

# About the logical description of soft keyboard retraction

  • After the soft keyboard pops up on Android, click back or click the non-focused area to close the soft keyboard.
  • On iOS, if there is a horizontal bar with "Done" above the soft keyboard, you need to click Done to close the keyboard; if there is no horizontal bar above the soft keyboard, tap the non-input/textarea area to close the soft keyboard

The above is the default logic. uni-app also provides an API to hide the soft keyboard: uni.hideKeyboard()

# App platform native input box description

On the app platform, there are native input boxes of searchinput configured by titleNView and drawinput of plus.nativeObj.view. The input boxes of these two methods are native, not in the webview.

  • The native input box will not have a horizontal bar above the soft keyboard on iOS
  • The native input box is also affected by the configured adjustPan|adjustResize mode

input example View Demo

The following sample code comes from hello uni-app project. It is recommended to use HBuilderX to create a new uni-app project and select the hello uni-app template to directly experience the complete example.

Template

Script

<!-- This example does not contain the complete css, please refer to the above to get the external link css, check it in the hello uni-app project -->
<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">&#xe434;</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">&#xe568;</text>
				</view>
			</view>
		</view>
	</view>
</template>

# Extensions

  • uni ui provides the easyinput component, which provides commonly used packages, can be used with uni-forms components, supports form validation, and supports various common settings. See details
  • uni ui provides a combox component, which is optional and can be input, and common words are free of input. See details
  • uni ui provides search box ui components, and the plug-in market also has packaged page templates. See for details. The cloud-integrated search template has complete functions, and it is recommended to use: https://ext.dcloud.net.cn/plugin?id=3851
  • The uni-app plug-in market has a component that automatically prompts candidates after inputting text, you can search for autocomplete to view.
  • There are various types of simulated keyboards in the plug-in market, such as license plate keyboards and ID card keyboards, you can go to the plug-in market to search [Keyboard](https://ext.dcloud.net.cn/search?q=%E9%94%AE %E7%9B%98).