input | uni-app-x

展示全部

# input

组件类型：UniInputElement

输入框

# 兼容性

Web	Android	iOS
4.0	3.9	4.11

# 属性

名称类型默认值兼容性描述

name

string

表单的控件名称，作为键值对的一部分与表单(form组件)一同提交

disabled

boolean

false

是否禁用

value

string

输入框的初始内容

type

"text"

input的类型

合法值

兼容性

描述

text

文本输入键盘

number

数字输入键盘

idcard

身份证输入键盘

digit

带小数点数字输入键盘

tel

电话输入键盘

safe-password

密码安全输入键盘

nickname

昵称输入键盘

password

boolean

false

是否是密码类型

placeholder

string

输入框为空时占位符

placeholder-style

string

指定 placeholder 的样式，目前仅支持color,font-size和font-weight

placeholder-class

string(string.ClassString)

指定 placeholder 的样式类，目前仅支持color,font-size和font-weight

maxlength

number

"不限制长度"

最大输入长度，0和正数为合法值，非法值的时候不限制最大长度

cursor-spacing

number

指定光标与键盘的距离，单位 px 。取 input 距离底部的距离和 cursor-spacing 指定的距离的最小值作为光标与键盘的距离

cursor-color

string(string.ColorString)

指定光标颜色

auto-focus

boolean

false

自动获取焦点，与focus属性对比，此属性只会首次生效。

focus

boolean

false

获取焦点

confirm-type

send | search | next | go | done

"done"

设置键盘右下角按钮的文字，仅在 type为text 时生效。

合法值

兼容性

描述

send

发送

搜索

下一个

前往

done

完成

always-embed

boolean

强制 input 处于同层状态，默认 focus 时 input 会切到非同层状态 (仅在 iOS 下生效)

confirm-hold

boolean

false

点击键盘右下角按钮时是否保持键盘不收起

cursor

number

指定focus时的光标位置

selection-start

number

-1

光标起始位置，自动聚集时有效，需与selection-end搭配使用

selection-end

number

-1

光标结束位置，自动聚集时有效，需与selection-satrt搭配使用

adjust-position

boolean

true

键盘弹起时，是否自动上推页面

text-content-type

string

文本区域的语义，根据类型自动填充

合法值

兼容性

描述

oneTimeCode

一次性验证码

hold-keyboard

boolean

false

focus时，点击页面的时候不收起键盘

safe-password-cert-path

string

安全键盘加密公钥的路径，只支持包内路径

safe-password-length

number

安全键盘输入密码长度

safe-password-time-stamp

number

安全键盘加密时间戳

safe-password-nonce

string

安全键盘加密盐值

safe-password-salt

string

安全键盘计算 hash 盐值，若指定custom-hash 则无效

safe-password-custom-hash

string

安全键盘计算 hash 的算法表达式

random-number

boolean

当 type 为 number, digit, idcard 数字键盘是否随机排列

controlled

boolean

是否为受控组件。为 true 时，value 内容会完全受 setData 控制

always-system

boolean

是否强制使用系统键盘和 Web-view 创建的 input 元素。为 true 时，confirm-type、confirm-hold 可能失效

inputmode

"text"

是一个枚举属性，它提供了用户在编辑元素或其内容时可能输入的数据类型的提示。在符合条件的高版本webview里，uni-app的 web 和 app-vue 平台中可使用本属性。

合法值

兼容性

描述

none

无虚拟键盘。在应用程序或者站点需要实现自己的键盘输入控件时很有用。

text

使用用户本地区域设置的标准文本输入键盘。

decimal

小数输入键盘，包含数字和分隔符（通常是“ . ”或者“ , ”），设备可能也可能不显示减号键。

numeric

数字输入键盘，所需要的就是 0 到 9 的数字，设备可能也可能不显示减号键。

tel

电话输入键盘，包含 0 到 9 的数字、星号（*）和井号（#）键。表单输入里面的电话输入通常应该使用 <input type="tel"> 。

为搜索输入优化的虚拟键盘，比如，返回键可能被重新标记为“搜索”，也可能还有其他的优化。

为邮件地址输入优化的虚拟键盘，通常包含""符号和其他优化。表单里面的邮件地址输入应该使用 <input type="email"> 。

url

为网址输入优化的虚拟键盘，比如，“/”键会更加明显、历史记录访问等。表单里面的网址输入通常应该使用 <input type="url"> 。

@input

(event: UniInputEvent) => void

当键盘输入时，触发input事件，event.detail = {value, cursor}，处理函数可以直接 return 一个字符串，将替换输入框的内容。

@focus

(event: UniInputFocusEvent) => void

输入框聚焦时触发，event.detail = { value, height }，height 为键盘高度

@blur

(event: UniInputBlurEvent) => void

输入框失去焦点时触发，event.detail = {value: value}

@keyboardheightchange

(event: UniInputKeyboardHeightChangeEvent) => void

键盘高度发生变化的时候触发此事件，event.detail = {height: height, duration: duration}

@confirm

(event: UniInputConfirmEvent) => void

点击完成按钮时触发，event.detail = {value: value}

# 事件

# UniInputEvent

# UniInputEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniInputEventDetail

是

名称	类型	必备	默认值	兼容性	描述
value	string	是	-	-	输入框内容
cursor	number	是	-	-	光标的位置
keyCode	number	是	-	-	输入字符的Unicode值

# UniInputFocusEvent

# UniInputFocusEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniInputFocusEventDetail

是

名称

类型

必备

默认值

兼容性

描述

height

number

是

键盘高度

value

string

是

输入框内容

# UniInputBlurEvent

# UniInputBlurEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniInputBlurEventDetail

是

名称	类型	必备	默认值	兼容性	描述
value	string	是	-	-	输入框内容
cursor	number	是	-	-	选择区域的起始位置

# UniInputKeyboardHeightChangeEvent

# UniInputKeyboardHeightChangeEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniInputKeyboardHeightChangeEventDetail

是

名称	类型	必备	默认值	兼容性	描述
height	number	是	-	-	键盘高度
duration	number	是	-	-	持续时间

# UniInputConfirmEvent

# UniInputConfirmEvent 的属性值

名称

类型

必填

默认值

兼容性

描述

detail

UniInputConfirmEventDetail

是

名称	类型	必备	默认值	兼容性	描述
value	string	是	-	-	输入框内容

# 获取原生view对象

为增强uni-app x组件的开放性，从 HBuilderX 4.25 起，UniElement对象提供了 getAndroidView 和 getIOSView 方法。

该方法可以获取到 textarea 组件对应的原生对象，即Android的AppCompatEditText对象、iOS的UITextField对象。

进而可以调用原生对象提供的方法，这极大的扩展了组件的能力。

Android 平台：

获取input组件对应的UniElement对象，通过UniElement对象的getAndroidView方法获取组件原生AppCompatEditText对象

//导入安卓原生AppCompatEditText对象
import AppCompatEditText from "androidx.appcompat.widget.AppCompatEditText"

//通过input组件定义的id属性值，获取input标签的UniElement对象
const inputElement = uni.getElementById(id)
//UniElement.getAndroidView设置泛型为安卓底层AppCompatEditText对象，直接获取AppCompatEditText， 如果泛型不匹配会返回null
if(inputElement != null) {
	//editText就是input组件对应的原生view对象
	const editText = inputElement.getAndroidView<AppCompatEditText>()
}

iOS 平台：

获取input组件对应的UniElement对象，通过UniElement对象的getIOSView方法获取组件原生UITextField对象

//通过 input 组件定义的 id 属性值，获取 input 标签的 UniElement 对象
const inputElement = uni.getElementById(id)
//获取原生 view
const view = inputElement?.getIOSView();
//判断 view 是否存在，类型是否为 UITextField
if (view != null && view instanceof UITextField) {
    //将 view 转换为 UITextField 类型 
    const textField = view! as UITextField;
}

iOS平台 uvue 环境使用 js 驱动无法处理原生类型，getIOSView 方法需要在 uts 插件中使用。

更多示例请参考 uts 插件 uts-get-native-view

# 子组件

不可以嵌套组件

# 示例

hello uni-app x

Template

Script

<template>
  <!-- #ifdef APP -->
  <scroll-view style="flex: 1">
  <!-- #endif -->
    <page-head :title="title"></page-head>
    <view class="uni-common-mt uni-padding-wrap">
      <view>
        <view class="uni-title">
          <text class="uni-title-text">设置输入框的初始内容</text>
        </view>
        <view class="input-wrapper">
          <input id="uni-input-default" class="uni-input" value="hello uni-app x" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">type取值（不同输入法表现可能不一致）</text>
        </view>
        <view class="input-wrapper">
          <input id="uni-input-type-text" class="uni-input" type="text" placeholder="文本输入键盘" />
        </view>
        <view class="input-wrapper">
          <input id="uni-input-type-number" class="uni-input" type="number" placeholder="数字输入键盘" />
        </view>
        <view class="input-wrapper">
          <input id="uni-input-type-digit" class="uni-input" type="digit" placeholder="带小数点的数字输入键盘" />
        </view>
        <view class="input-wrapper">
          <input id="uni-input-type-tel" class="uni-input" :type="inputTypeTel" placeholder="电话输入键盘" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">密码输入框</text>
        </view>
        <view class="input-wrapper">
          <input id="uni-input-password" class="uni-input" :password="inputPassword" :value="inputPasswordValue" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">无value设置的密码输入框</text>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" :password="true" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">占位符样式</text>
        </view>
        <view class="input-wrapper">
          <input id="uni-input-placeholder1" class="uni-input" :placeholder-style="inputPlaceHolderStyle"
            placeholder="占位符文字颜色为红色" />
        </view>
        <view class="input-wrapper">
          <input id="uni-input-placeholder2" class="uni-input" :placeholder-class="inputPlaceHolderClass"
            placeholder="占位符字体大小为10px" />
        </view>
        <view class="input-wrapper">
          <input class="uni-input" :placeholder-style="inputPlaceHolderStyle"
            value="不设置placeholder只设置placeholder-style" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">设置禁用输入框</text>
        </view>
        <view class="input-wrapper">
          <input id="uni-input-disable" class="uni-input" :disabled="true" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">设置最大输入长度</text>
        </view>
        <view class="input-wrapper">
          <input id="uni-input-maxlength" class="uni-input" :maxlength="10" placeholder="最大输入长度为10"
            :value="inputMaxLengthValue" @input="onMaxLengthInput" :focus="inputMaxLengthFocus" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">设置光标与键盘的距离</text>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" :cursor-spacing="1000" placeholder="光标与键盘的距离为1000px" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">自动获取焦点</text>
        </view>
        <view class="input-wrapper">
          <input id="uni-input-focus" class="uni-input" :focus="focus"
            @keyboardheightchange="inputFocusKeyBoardChange" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">confirm-type取值（不同输入法表现可能不一致）</text>
        </view>
        <view class="input-wrapper">
          <input id="uni-input-confirm-send" class="uni-input" confirmType="send" placeholder="键盘右下角按钮显示为发送" />
        </view>
        <view class="input-wrapper">
          <input id="uni-input-confirm-search" class="uni-input" confirmType="search" placeholder="键盘右下角按钮显示为搜索" />
        </view>
        <view class="input-wrapper">
          <input id="uni-input-confirm-next" class="uni-input" confirmType="next" placeholder="键盘右下角按钮显示为下一个" />
        </view>
        <view class="input-wrapper">
          <input id="uni-input-confirm-go" class="uni-input" confirmType="go" placeholder="键盘右下角按钮显示为前往" />
        </view>
        <view class="input-wrapper">
          <input id="uni-input-confirm-done" class="uni-input" confirmType="done" placeholder="键盘右下角按钮显示为完成" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">点击键盘右下角按钮时保持键盘不收起</text>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" :confirm-hold="true" />
        </view>
      </view>

      <view>
        <view class="uni-title" @click="setCursor(4)">
          <text class="uni-title-text">设置输入框聚焦时光标的位置（点这里）</text>
        </view>
        <view class="input-wrapper">
          <input ref="input" class="uni-input" value="0123456789" :cursor="cursor" @blur="onCursorBlurChange" />
        </view>
      </view>

      <view>
        <view class="uni-title" @click="setSelection(0, 4)">
          <text class="uni-title-text">设置输入框聚焦时光标的起始位置和结束位置（点这里）</text>
        </view>
        <view class="input-wrapper">
          <input ref="input2" class="uni-input" value="0123456789" :selection-start="selectionStart"
            :selection-end="selectionEnd" @blur="onSelectionBlurChange" />
        </view>
      </view>

      <view>
        <view class="uni-title" style="flex-direction: row; align-items: center">
          <text class="uni-title-text">设置光标颜色为红色</text>
          <switch style="margin-left: 10px" @change="changeCursorColor" :checked="cursor_color == 'red'"></switch>
        </view>
        <view class="input-wrapper">
          <input id="uni-input-cursor-color" class="uni-input" :cursor-color="cursor_color" value="光标颜色" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">键盘弹起时，自动上推页面</text>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" :adjust-position="true" />
        </view>
      </view>

      <view>
        <view class="uni-title" style="flex-direction: row; align-items: center">
          <text class="uni-title-text">设置hold-keyboard</text>
          <switch style="margin-left: 10px" @change="changeHoldKeyboard" :checked="holdKeyboard"></switch>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" :hold-keyboard="holdKeyboard" value="hold keyboard " />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">input事件</text>
          <text class="uni-subtitle-text" v-if="inputEventDetail">{{
            inputEventDetail
          }}</text>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" @input="onInput" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">focus事件和blur事件</text>
          <text class="uni-subtitle-text" v-if="focusAndBlurEventDetail">{{
            focusAndBlurEventDetail
          }}</text>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" @focus="onFocus" @blur="onBlur" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">confirm事件</text>
          <text class="uni-subtitle-text" v-if="confirmEventDetail">{{
            confirmEventDetail
          }}</text>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" @confirm="onConfirm" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">keyboardheightchange事件</text>
          <text class="uni-subtitle-text"
            v-if="keyboardHeightChangeEventDetail">{{ keyboardHeightChangeEventDetail }}</text>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" @keyboardheightchange="onKeyborardHeightChange"
            :focus="focusedForKeyboardHeightChangeTest" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">带清除按钮的输入框</text>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" placeholder="带清除按钮的输入框" :value="inputClearValue" @input="clearInput" />
          <image class="uni-icon" src="/static/icons/clear.png" v-if="showClearIcon" @click="clearIcon">
          </image>
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">可查看密码的输入框</text>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" placeholder="请输入密码" :password="showPassword" />
          <image class="uni-icon" :src="
              !showPassword
                ? '/static/icons/eye-active.png'
                : '/static/icons/eye.png'
            " @click="changePassword"></image>
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">同时存在 v-model 和 value</text>
        </view>
        <view class="input-wrapper">
          <input id="both-model-value" class="uni-input" v-model="demoValue" value="456" />
        </view>
      </view>

      <view>
        <view class="uni-title" style="flex-direction: row; align-items: center">
          <text class="uni-title-text">设置adjust-position</text>
          <switch style="margin-left: 10px" @change="changeAdjustPosition" :checked="adjustPosition"></switch>
        </view>
        <view class="input-wrapper">
          <input class="uni-input" :adjust-position="adjustPosition" />
        </view>
      </view>

      <view>
        <view class="uni-title">
          <text class="uni-title-text">输入内容的同步更新UI</text>
        </view>
        <text>{{syncDisplayValue}}</text>
        <view class="input-wrapper">
          <input class="uni-input" v-model="syncDisplayValue"/>
        </view>
      </view>

    </view>
  <!-- #ifdef APP -->
  </scroll-view>
  <!-- #endif -->
</template>


<style scoped>
  .input-wrapper {
    display: flex;
    padding: 8px 13px;
    margin: 5px 0;
    flex-direction: row;
    flex-wrap: nowrap;
    background-color: #ffffff;
  }

  .uni-input {
    height: 28px;
    font-size: 15px;
    padding: 0px;
    flex: 1;
    background-color: #ffffff;
  }

  .uni-icon {
    width: 24px;
    height: 24px;
  }

  .uni-input-placeholder-class {
    font-size: 10px;
  }
</style>

# 参见

# 键盘上推专题

在App平台，input和textarea组件都一个属性adjust-position，默认为true，即软键盘弹出时，默认上推页面以显示出输入框，避免输入框被软键盘遮挡。

软键盘弹出后会挡住输入框，此时启动上推逻辑。默认的上推策略是：

如果输入框在scroll-view里，会优先滚动scroll-view，以保证显示出输入框。
如果没有可滚动区域，会transform上移页面，以保证显示出输入框。

但是默认的上推策略无法适配所有场景，有些场景需要关闭默认上推策略，即把属性adjust-position设为false，然后在输入框的focus或keyboardheightchange事件中获取键盘高度，手动调整界面。

默认上推策略时，如果页面使用了自定义导航栏，常见注意事项是软键盘弹出后可能把自定义导航栏推出可视范围。
此时注意顶部导航栏不能在滚动视图中，且需要使用css固定在顶部，然后下面放一个scroll-view，输入框放在scroll-view中，就不会把自定义导航栏顶飞。
如果这种方式仍然不能满足需求，那么就需要关闭默认的上推策略，手动控制。

在web端平台，输入框上推逻辑是由浏览器自动完成的，属性adjust-position无效。但iOS safari软键盘弹出时，整个页面会上推而不是挤压，导致pages.json配置的导航栏会上移到屏幕之外。

推荐参考代码：hello uni-app x -> 模板 -> 自定义导航栏。为了避免自定义导航栏被顶飞，有的可以自动上推，有的需手动控制，这里均有示例。

# comfirm-type和inputmode说明

comfirm-type Web平台弹出键盘使用的是浏览器控制的键盘，在Chrome81+、Safari13.7+之前，键盘右下角文字只能设置完成和搜索，从Chrome81+、Safari13.7+起支持设置发送、下一个。
inputmode

web平台的inputmode的浏览器兼容性如下： Chrome >= 66、Edge >= 79、Firefox >= 95、Chrome Android >= 66、Firefox for Android >= 79、Safari on iOS >= 12.2、WebView Android >= 66

input组件有 inputmode 和 type、comfirm-type 3个相似的属性，它们的区别详解如下：

type：在 uni-app 和小程序中仅仅是输入框，定义 input 的工作方式，此值决定可输入什么值。比如 number 只能输入数字。
comfirm-type：定义键盘右下角按键的文字
inputmode：inputmode 属性是当使用某些值时会对键盘所作出的优化。

同时使用 inputmode 和 comfirm-type 时，若设值冲突，键盘右下角按键类型由 comfirm-type 决定。type 属性和 inputmode 属性并不冲突

# Tips

html规范中input不仅是输入框，还有radio、checkbox、时间、日期、文件选择功能。但在uni-app规范中，input仅仅是输入框，其type属性代表不同的输入框。其他功能有单独的组件或API：radio组件、checkbox组件、图片选择等。
从uni-app x 4.0起，App-Android平台 input 点击输入框外的屏幕会自动收起软键盘。
从uni-app x 4.0起，App-Android平台 input 的 font-size 默认值统一为 16px。
Web 平台，iOS 自带键盘的智能标点功能会导致：在 type 为 number、digit 时，连续输入两次 . 后，在第三次输入 . 时，会触发两次 deleteContentBackward（删除）的输入外加一次 insertText 为 …（三个点）的输入。会导致表现异常，关闭智能标点功能后正常。