Vant4 Field 输入框

介绍

用户可以在文本框内输入或编辑文字。

引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from 'vue';
import { Field, CellGroup } from 'vant';

const app = createApp();
app.use(Field);
app.use(CellGroup);

代码演示

基础用法

可以通过 ​v-model​ 双向绑定输入框的值，通过 ​placeholder​ 设置占位提示文字。

<!-- 可以使用 CellGroup 作为容器 -->
<van-cell-group inset>
  <van-field v-model="value" label="文本" placeholder="请输入用户名" />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const value = ref('');
    return { value };
  },
};

自定义类型

根据 ​type​ 属性定义不同类型的输入框，默认值为 ​text​。

<van-cell-group inset>
  <!-- 输入任意文本 -->
  <van-field v-model="text" label="文本" />
  <!-- 输入手机号，调起手机号键盘 -->
  <van-field v-model="tel" type="tel" label="手机号" />
  <!-- 允许输入正整数，调起纯数字键盘 -->
  <van-field v-model="digit" type="digit" label="整数" />
  <!-- 允许输入数字，调起带符号的纯数字键盘 -->
  <van-field v-model="number" type="number" label="数字" />
  <!-- 输入密码 -->
  <van-field v-model="password" type="password" label="密码" />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const tel = ref('');
    const text = ref('');
    const digit = ref('');
    const number = ref('');
    const password = ref('');

    return { tel, text, digit, number, password };
  },
};

禁用输入框

通过 ​readonly​ 将输入框设置为只读状态，通过 ​disabled​ 将输入框设置为禁用状态。

<van-cell-group inset>
  <van-field label="文本" model-value="输入框只读" readonly />
  <van-field label="文本" model-value="输入框已禁用" disabled />
</van-cell-group>

显示图标

通过 ​left-icon​ 和 ​right-icon​ 配置输入框两侧的图标，通过设置 ​clearable​ 在输入过程中展示清除图标。

<van-cell-group inset>
  <van-field
    v-model="value1"
    label="文本"
    left-icon="smile-o"
    right-icon="warning-o"
    placeholder="显示图标"
  />
  <van-field
    v-model="value2"
    clearable
    label="文本"
    left-icon="music-o"
    placeholder="显示清除图标"
  />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const value1 = ref('');
    const value2 = ref('123');
    return {
      value1,
      value2,
    };
  },
};

错误提示

设置 ​required​ 属性表示这是一个必填项，可以配合 ​error​ 或 ​error-message​ 属性显示对应的错误提示。

<van-cell-group inset>
  <van-field
    v-model="username"
    error
    required
    label="用户名"
    placeholder="请输入用户名"
  />
  <van-field
    v-model="phone"
    required
    label="手机号"
    placeholder="请输入手机号"
    error-message="手机号格式错误"
  />
</van-cell-group>

插入按钮

通过 button 插槽可以在输入框尾部插入按钮。

<van-cell-group inset>
  <van-field
    v-model="sms"
    center
    clearable
    label="短信验证码"
    placeholder="请输入短信验证码"
  >
    <template #button>
      <van-button size="small" type="primary">发送验证码</van-button>
    </template>
  </van-field>
</van-cell-group>

格式化输入内容

通过 ​formatter​ 属性可以对输入的内容进行格式化，通过 ​format-trigger​ 属性可以指定执行格式化的时机，默认在输入时进行格式化。

<van-cell-group inset>
  <van-field
    v-model="value1"
    label="文本"
    :formatter="formatter"
    placeholder="在输入时执行格式化"
  />
  <van-field
    v-model="value2"
    label="文本"
    :formatter="formatter"
    format-trigger="onBlur"
    placeholder="在失焦时执行格式化"
  />
</van-cell-group>

import { ref } from 'vue';

export default {
  setup() {
    const value1 = ref('');
    const value2 = ref('');
    // 过滤输入的数字
    const formatter = (value) => value.replace(/\d/g, '');

    return {
      value1,
      value2,
      formatter,
    };
  },
};

高度自适应

对于 textarea，可以通过 ​autosize​ 属性设置高度自适应。

<van-cell-group inset>
  <van-field
    v-model="message"
    rows="1"
    autosize
    label="留言"
    type="textarea"
    placeholder="请输入留言"
  />
</van-cell-group>

显示字数统计

设置 ​maxlength​ 和 ​show-word-limit​ 属性后会在底部显示字数统计。

<van-cell-group inset>
  <van-field
    v-model="message"
    rows="2"
    autosize
    label="留言"
    type="textarea"
    maxlength="50"
    placeholder="请输入留言"
    show-word-limit
  />
</van-cell-group>

输入框内容对齐

通过 ​input-align​ 属性可以设置输入框内容的对齐方式，可选值为 ​center​、​right​。

<van-cell-group inset>
  <van-field
    v-model="value"
    label="文本"
    placeholder="输入框内容右对齐"
    input-align="right"
  />
</van-cell-group>

输入框文本位置

通过 ​label-align​ 属性可以设置输入框文本的位置，可选值为 ​center​、​right​、​top​。

<van-cell-group inset>
  <van-field
    v-model="value"
    label="手机号"
    placeholder="请输入手机号"
    label-align="top"
  />
</van-cell-group>

API

Props

参数	说明	类型	默认值
v-model	当前输入的值	number | string	-
label	输入框左侧文本	string	-
name	名称，作为提交表单时的标识符	string	-
id v3.2.2	输入框 id，同时会设置 label 的 for 属性	string	van-field-n-input
type	输入框类型, 支持原生 input 标签的所有 type 属性，额外支持了 digit 类型	FieldType	text
size	大小，可选值为 large	string	-
maxlength	输入的最大字符数	number | string	-
placeholder	输入框占位提示文字	string	-
border	是否显示内边框	boolean	true
disabled	是否禁用输入框	boolean	false
readonly	是否为只读状态，只读状态下无法输入内容	boolean	false
colon	是否在 label 后面添加冒号	boolean	false
required	是否显示表单必填星号	boolean	false
center	是否使内容垂直居中	boolean	false
clearable	是否启用清除图标，点击清除图标后会清空输入框	boolean	false
clear-icon v3.0.12	清除图标名称或图片链接，等同于 Icon 组件的 name 属性	string	clear
clear-trigger	显示清除图标的时机，always 表示输入框不为空时展示， focus 表示输入框聚焦且不为空时展示	FieldClearTrigger	focus
clickable	是否开启点击反馈	boolean	false
is-link	是否展示右侧箭头并开启点击反馈	boolean	false
autofocus	是否自动聚焦，iOS 系统不支持该属性	boolean	false
show-word-limit	是否显示字数统计，需要设置 maxlength 属性	boolean	false
error	是否将输入内容标红	boolean	false
error-message	底部错误提示文案，为空时不展示	string	-
error-message-align	错误提示文案对齐方式，可选值为 center right	FieldTextAlign	left
formatter	输入内容格式化函数	(val: string) => string	-
format-trigger	格式化函数触发的时机，可选值为 onBlur	FieldFormatTrigger	onChange
arrow-direction	箭头方向，可选值为 left up down	string	right
label-class	左侧文本额外类名	string | Array | object	-
label-width	左侧文本宽度，默认单位为 px	number | string	6.2em
label-align	左侧文本对齐方式，可选值为 center right top	FieldTextAlign	left
input-align	输入框对齐方式，可选值为 center right	FieldTextAlign	left
autosize	是否自适应内容高度，只对 textarea 有效， 可传入对象,如 { maxHeight: 100, minHeight: 50 }， 单位为px	boolean | FieldAutosizeConfig	false
left-icon	左侧图标名称或图片链接，等同于 Icon 组件的 name 属性	string	-
right-icon	右侧图标名称或图片链接，等同于 Icon 组件的 name 属性	string	-
icon-prefix	图标类名前缀，等同于 Icon 组件的 class-prefix 属性	string	van-icon
rules	表单校验规则，详见 Form 组件	FieldRule[]	-
autocomplete v3.0.3	HTML 原生属性，用于控制自动完成功能，详见 MDN - autocomplete	string	-
enterkeyhint v3.4.8	HTML 原生属性，用于控制回车键样式，此 API 仅在部分浏览器支持，详见 MDN - enterkeyhint	string	-

Events

事件	说明	回调参数
update:model-value	输入框内容变化时触发	value: string (当前输入的值)
focus	输入框获得焦点时触发	event: Event
blur	输入框失去焦点时触发	event: Event
clear	点击清除按钮时触发	event: MouseEvent
click	点击组件时触发	event: MouseEvent
click-input	点击输入区域时触发	event: MouseEvent
click-left-icon	点击左侧图标时触发	event: MouseEvent
click-right-icon	点击右侧图标时触发	event: MouseEvent
start-validate v3.5.1	开始表单校验时触发	-
end-validate v3.5.1	结束表单校验时触发	{ status: string, message: string }

方法

通过 ref 可以获取到 Field 实例并调用实例方法，详见组件实例方法。

方法名	说明	参数	返回值
focus	获取输入框焦点	-	-
blur	取消输入框焦点	-	-

类型定义

组件导出以下类型定义：

import type {
  FieldType,
  FieldRule,
  FieldProps,
  FieldInstance,
  FieldTextAlign,
  FieldRuleMessage,
  FieldClearTrigger,
  FieldFormatTrigger,
  FieldRuleValidator,
  FiledRuleFormatter,
  FieldValidateError,
  FieldAutosizeConfig,
  FieldValidateTrigger,
  FieldValidationStatus,
} from 'vant';

​FieldInstance​ 是组件实例的类型，用法如下：

import { ref } from 'vue';
import type { FieldInstance } from 'vant';

const fieldRef = ref<FieldInstance>();

fieldRef.value?.focus();

Slots

名称	说明	参数
label	自定义输入框左侧文本	-
input	自定义输入框，使用此插槽后，与输入框相关的属性和事件将失效	-
left-icon	自定义输入框头部图标	-
right-icon	自定义输入框尾部图标	-
button	自定义输入框尾部按钮	-
error-message v3.2.5	自定义底部错误提示文案	{ message: string }
extra	自定义输入框最右侧的额外内容	-

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-field-label-width	6.2em	-
--van-field-label-color	var(--van-text-color)	-
--van-field-label-margin-right	var(--van-padding-sm)	-
--van-field-input-text-color	var(--van-text-color)	-
--van-field-input-error-text-color	var(--van-danger-color)	-
--van-field-input-disabled-text-color	var(--van-text-color-3)	-
--van-field-placeholder-text-color	var(--van-text-color-3)	-
--van-field-icon-size	16px	-
--van-field-clear-icon-size	16px	-
--van-field-clear-icon-color	var(--van-gray-5)	-
--van-field-right-icon-color	var(--van-gray-6)	-
--van-field-error-message-color	var(--van-danger-color)	-
--van-field-error-message-font-size	12px	-
--van-field-text-area-min-height	60px	-
--van-field-word-limit-color	var(--van-gray-7)	-
--van-field-word-limit-font-size	var(--van-font-size-sm)	-
--van-field-word-limit-line-height	16px	-
--van-field-disabled-text-color	var(--van-text-color-3)	-
--van-field-required-mark-color	var(--van-red)	-

常见问题

设置 type 为 number 后，为什么 input 标签的类型仍为 text?

HTML 原生的 ​type="number"​ 属性在 iOS 和 Android 系统上都存在一定问题，比如 maxlength 属性不生效、无法获取到完整的输入内容等。因此设置 type 为 ​number​ 时，Field 不会使用原生的 ​type="number"​ 属性，而是用现代浏览器支持的 inputmode 属性来控制输入键盘的类型。

为什么 v-model 绑定的值被更新为 string 类型？

Field 组件内部会将传入的 v-model 格式化为 string 类型，便于组件内部进行处理。

如果你希望在 v-model 上绑定 number 类型，可以使用 Vue 提供的 .number 修饰符。

<van-field v-model.number="value" type="tel" />

在桌面端点击清除按钮无效？

清除按钮监听是的移动端 Touch 事件，参见桌面端适配。