input | uni-app

input

Attribute description

type valid values

text-content-type valid values

confirm-type valid values

inputmode valid values

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

About the logical description of the soft keyboard pop-up

About the logical description of soft keyboard retraction

App platform native input box description

Expand All

# 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 下无限制。
在 Web 和 app-plus vue 上 iOS 自带键盘的智能标点功能会导致：在 type 为 number、digit 时，连续输入两次 . 后，在第三次输入 . 时，会触发两次 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).