输入框组件

input 组件是 Uniapp 中用于单行文本输入的核心控件，允许用户在界面上输入和编辑数据。该组件支持多种输入类型（如文本、数字、密码等），同时可以灵活地控制输入框的样式、行为以及与软键盘的交互，是表单、搜索框等功能实现中的基础组件之一。

1. 什么是 input 组件？

input 组件是用于接收单行用户输入的基本表单控件。它可以接收用户的文本输入，支持多种输入类型（如文本、数字、密码等），并提供了丰富的属性来控制其行为和显示方式。开发者可以通过它轻松实现登录表单、搜索框、消息输入等场景。

常见使用场景

• 登录/注册表单：用于输入用户名、密码等信息。
• 搜索框：用户可以通过 input 组件输入查询内容进行搜索。
• 表单提交：在表单中使用 input 组件获取用户的输入值，如姓名、电子邮箱等。
• 聊天消息输入：输入消息并点击发送。
• 验证码输入：用于输入短信验证码、邮箱验证码等。

2. input 组件的常用属性

input 组件提供了多种属性，用于控制输入框的显示、输入类型、样式、交互事件等。以下是常用属性的详细说明及使用示例：

属性名	类型	默认值	说明	平台差异说明
value	String		输入框的初始内容。
type	String	text	输入框的类型，详见类型说明。
password	Boolean	false	是否为密码类型，开启时输入内容会以星号形式显示。	H5 和 App 写此属性时，type 属性将失效。
placeholder	String		输入框为空时显示的提示内容（占位符）。
placeholder-style	String		自定义占位符的样式，比如字体大小、颜色等。
placeholder-class	String	"input-placeholder"	自定义占位符的样式类。	抖音小程序、飞书小程序、快手小程序不支持。
disabled	Boolean	false	是否禁用输入框，禁用时用户无法输入。
maxlength	Number	140	限制输入的最大字符数，设置为 -1 时表示不限制。
focus	Boolean	false	是否自动获取焦点。	H5、App需要通过事件阻止默认键盘关闭行为来手动控制焦点。
confirm-type	String	done	设置键盘右下角按钮的文字，详见确认按钮类型。
cursor	Number		指定 focus 时光标的位置。
cursor-color	String		设置光标的颜色。	微信小程序 3.1.0+，H5(4.0+)，App-Vue(4.0+) 支持。
selection-start	Number	-1	光标选中范围的起始位置，自动聚焦时有效。
selection-end	Number	-1	光标选中范围的结束位置，自动聚焦时有效。
adjust-position	Boolean	true	键盘弹起时，是否自动上推页面。	微信小程序、百度小程序、App等平台支持。
@input	EventHandle		键盘输入时触发，返回输入的内容。
@focus	EventHandle		输入框聚焦时触发，返回键盘高度等信息。	微信小程序、App等平台支持返回键盘高度。
@blur	EventHandle		输入框失去焦点时触发。
@confirm	EventHandle		用户点击键盘右下角完成按钮时触发，返回输入的值。

2.1 设置输入框类型 type

• 说明：通过 type 属性可以设置输入框的输入内容类型，例如文本、数字、密码、电话等。不同的输入类型会影响显示的键盘样式和用户的输入限制。
• 类型：String

值	说明
text	普通文本输入键盘
number	数字输入键盘
digit	带小数点的数字键盘
idcard	身份证输入键盘
tel	电话号码输入键盘
password	密码输入，隐藏输入内容

示例：

<template>
  <view>
    <!-- 普通文本输入 -->
    <input type="text" placeholder="请输入文本" />
    
    <!-- 数字输入框 -->
    <input type="number" placeholder="请输入数字" />
    
    <!-- 密码输入框 -->
    <input type="password" placeholder="请输入密码" />
  </view>
</template>

2.2 设置占位符样式 placeholder-style

• 说明：通过 placeholder-style 属性可以自定义占位符的样式，例如字体颜色、字体大小等。
• 类型：String

示例：

<template>
  <!-- 自定义占位符样式：灰色文字，字体大小为16px -->
  <input placeholder="请输入内容" placeholder-style="color: gray; font-size: 16px;" />
</template>

2.3 设置最大输入长度 maxlength

• 说明：使用 maxlength 属性可以限制输入的最大字符数。用户输入的字符数量超过此限制时，将无法继续输入。设置为 -1 时表示不限制字符长度。
• 类型：Number

示例：

<template>
  <!-- 限制输入最多 10 个字符 -->
  <input maxlength="10" placeholder="最多输入 10 个字符" />
</template>

2.4 设置键盘按钮文字 confirm-type

• 说明：通过 confirm-type 属性可以设置键盘右下角按钮的文字内容，例如 done（完成）、send（发送）、search（搜索）等。适用于用户输入完成后需要触发某些操作的场景。
• 类型：String

值	说明
done	完成
send	发送
search	搜索
next	下一个
go	前往

示例：

<template>
  <!-- 设置键盘右下角按钮为“搜索” -->
  <input confirm-type="search" placeholder="键盘右下角显示为搜索" />
</template>

2.5 自动聚焦 focus

• 说明：focus 属性用于控制输入框是否在页面加载时自动获得焦点。启用该属性时，输入框会在页面加载时自动聚焦，用户可以立即开始输入内容。
• 类型：Boolean

示例：

<template>
  <!-- 自动获得焦点的输入框 -->
  <input focus placeholder="自动获得焦点的输入框" />
</template>

2.6 控制光标位置 cursor 和 selection-start / selection-end

• 说明：通过 cursor 属性可以设置输入框聚焦时光标的位置。使用 selection-start 和 selection-end 可以控制选中文本的起止位置。
• 类型：Number

示例：

<template>
  <!-- 设置光标初始位置为第 3 个字符 -->
  <input cursor="3" placeholder="设置光标位置" />
  
  <!-- 选中第 1 到第 3 个字符 -->
  <input selection-start="1" selection-end="3" placeholder="设置选中范围" />
</template>

3. 输入框使用案例

3.1 实时获取输入值

开发者通常需要在用户输入时立即获取并处理输入的内容。通过 @input 事件可以实现实时获取用户输入的值。

<template>
  <view>
    <!-- 实时获取输入内容，并显示在页面上 -->
    <input @input="onInput" placeholder="输入内容" />
    <text>当前输入内容：{{ inputValue }}</text>
  </view>
</template>

<script setup>
import { ref } from 'vue';

const inputValue = ref('');  // 绑定的输入值

// 处理输入事件
const onInput = (e) => {
  inputValue.value = e.detail.value;  // 获取输入的值
};
</script>

3.2 带有清除按钮的输入框

在某些场景下，用户希望能够快速清空输入框中的内容。我们可以通过添加一个清除按钮来实现该功能。

<template>
  <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>
</template>

<script setup>
import { ref } from 'vue';

const inputClearValue = ref('');  // 输入框的值
const showClearIcon = ref(false); // 是否显示清除按钮

// 监听输入事件
const clearInput = (event) => {
  inputClearValue.value = event.detail.value;
  showClearIcon.value = event.detail.value.length > 0;  // 当有输入内容时显示清除按钮
};

// 点击清除按钮
const clearIcon = () => {
  inputClearValue.value = '';
  showClearIcon.value = false;
};
</script>

3.3 控制密码显示与隐藏

有时需要用户输入密码，并提供查看密码的功能。可以通过绑定属性 password 来控制输入框的密码显示与隐藏。

<template>
  <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>
</template>

<script setup>
import { ref } from 'vue';

const showPassword = ref(true);  // 是否隐藏密码

// 切换密码显示状态
const changePassword = () => {
  showPassword.value = !showPassword.value;
};
</script>

4. Uni-UI 组件库的 easyinput 组件

uni-ui 组件库提供了增强版的 easyinput 组件，封装了更多常用功能，如表单验证、清除按钮、字数限制等。开发者可以使用 easyinput 提供更简洁的代码和更强大的功能。

• uni-ui easyinput 组件：组件详细说明 (opens new window)