Form 表单

介绍

用于数据录入、校验,支持输入框、单选框、复选框、文件上传等类型,2.5 版本开始支持此组件。

引入

  1. import Vue from 'vue';
  2. import { Form } from 'vant';
  3. Vue.use(Form);

代码演示

基础用法

在表单中,每个 Field 组件 代表一个表单项,使用 Field 的 rules 属性定义校验规则。

  1. <van-form @submit="onSubmit">
  2. <van-field
  3. v-model="username"
  4. name="用户名"
  5. label="用户名"
  6. placeholder="用户名"
  7. :rules="[{ required: true, message: '请填写用户名' }]"
  8. />
  9. <van-field
  10. v-model="password"
  11. type="password"
  12. name="密码"
  13. label="密码"
  14. placeholder="密码"
  15. :rules="[{ required: true, message: '请填写密码' }]"
  16. />
  17. <div style="margin: 16px;">
  18. <van-button round block type="info" native-type="submit">
  19. 提交
  20. </van-button>
  21. </div>
  22. </van-form>
  1. export default {
  2. data() {
  3. return {
  4. username: '',
  5. password: '',
  6. };
  7. },
  8. methods: {
  9. onSubmit(values) {
  10. console.log('submit', values);
  11. },
  12. },
  13. };

校验规则

通过 rules 定义表单校验规则,可用字段见下方表格

  1. <van-form validate-first @failed="onFailed">
  2. <!-- 通过 pattern 进行正则校验 -->
  3. <van-field
  4. v-model="value1"
  5. name="pattern"
  6. placeholder="正则校验"
  7. :rules="[{ pattern, message: '请输入正确内容' }]"
  8. />
  9. <!-- 通过 validator 进行函数校验 -->
  10. <van-field
  11. v-model="value2"
  12. name="validator"
  13. placeholder="函数校验"
  14. :rules="[{ validator, message: '请输入正确内容' }]"
  15. />
  16. <!-- 通过 validator 进行异步函数校验 -->
  17. <van-field
  18. v-model="value3"
  19. name="asyncValidator"
  20. placeholder="异步函数校验"
  21. :rules="[{ validator: asyncValidator, message: '请输入正确内容' }]"
  22. />
  23. <div style="margin: 16px;">
  24. <van-button round block type="info" native-type="submit">
  25. 提交
  26. </van-button>
  27. </div>
  28. </van-form>
  1. import { Toast } from 'vant';
  2. export default {
  3. data() {
  4. return {
  5. value1: '',
  6. value2: '',
  7. value3: '',
  8. pattern: /\d{6}/,
  9. };
  10. },
  11. methods: {
  12. // 校验函数返回 true 表示校验通过,false 表示不通过
  13. validator(val) {
  14. return /1\d{10}/.test(val);
  15. },
  16. // 异步校验函数返回 Promise
  17. asyncValidator(val) {
  18. return new Promise((resolve) => {
  19. Toast.loading('验证中...');
  20. setTimeout(() => {
  21. Toast.clear();
  22. resolve(/\d{6}/.test(val));
  23. }, 1000);
  24. });
  25. },
  26. onFailed(errorInfo) {
  27. console.log('failed', errorInfo);
  28. },
  29. },
  30. };

表单项类型 - 开关

在表单中使用 Switch 组件

  1. <van-field name="switch" label="开关">
  2. <template #input>
  3. <van-switch v-model="switchChecked" size="20" />
  4. </template>
  5. </van-field>
  1. export default {
  2. data() {
  3. return {
  4. switchChecked: false,
  5. };
  6. },
  7. };

表单项类型 - 复选框

在表单中使用 Checkbox 组件

  1. <van-field name="checkbox" label="复选框">
  2. <template #input>
  3. <van-checkbox v-model="checkbox" shape="square" />
  4. </template>
  5. </van-field>
  6. <van-field name="checkboxGroup" label="复选框组">
  7. <template #input>
  8. <van-checkbox-group v-model="checkboxGroup" direction="horizontal">
  9. <van-checkbox name="1" shape="square">复选框 1</van-checkbox>
  10. <van-checkbox name="2" shape="square">复选框 2</van-checkbox>
  11. </van-checkbox-group>
  12. </template>
  13. </van-field>
  1. export default {
  2. data() {
  3. return {
  4. checkbox: false,
  5. checkboxGroup: [],
  6. };
  7. },
  8. };

表单项类型 - 单选框

在表单中使用 Radio 组件

  1. <van-field name="radio" label="单选框">
  2. <template #input>
  3. <van-radio-group v-model="radio" direction="horizontal">
  4. <van-radio name="1">单选框 1</van-radio>
  5. <van-radio name="2">单选框 2</van-radio>
  6. </van-radio-group>
  7. </template>
  8. </van-field>
  1. export default {
  2. data() {
  3. return {
  4. radio: '1',
  5. };
  6. },
  7. };

表单项类型 - 步进器

在表单中使用 Stepper 组件

  1. <van-field name="stepper" label="步进器">
  2. <template #input>
  3. <van-stepper v-model="stepper" />
  4. </template>
  5. </van-field>
  1. export default {
  2. data() {
  3. return {
  4. stepper: 1,
  5. };
  6. },
  7. };

表单项类型 - 评分

在表单中使用 Rate 组件

  1. <van-field name="rate" label="评分">
  2. <template #input>
  3. <van-rate v-model="rate" />
  4. </template>
  5. </van-field>
  1. export default {
  2. data() {
  3. return {
  4. rate: 3,
  5. };
  6. },
  7. };

表单项类型 - 滑块

在表单中使用 Slider 组件

  1. <van-field name="slider" label="滑块">
  2. <template #input>
  3. <van-slider v-model="slider" />
  4. </template>
  5. </van-field>
  1. export default {
  2. data() {
  3. return {
  4. slider: 50,
  5. };
  6. },
  7. };

表单项类型 - 文件上传

在表单中使用 Uploader 组件

  1. <van-field name="uploader" label="文件上传">
  2. <template #input>
  3. <van-uploader v-model="uploader" />
  4. </template>
  5. </van-field>
  1. export default {
  2. data() {
  3. return {
  4. uploader: [{ url: 'https://img.yzcdn.cn/vant/leaf.jpg' }],
  5. };
  6. },
  7. };

表单项类型 - 选择器

在表单中使用 Picker 组件

  1. <van-field
  2. readonly
  3. clickable
  4. name="picker"
  5. :value="value"
  6. label="选择器"
  7. placeholder="点击选择城市"
  8. @click="showPicker = true"
  9. />
  10. <van-popup v-model="showPicker" position="bottom">
  11. <van-picker
  12. show-toolbar
  13. :columns="columns"
  14. @confirm="onConfirm"
  15. @cancel="showPicker = false"
  16. />
  17. </van-popup>
  1. export default {
  2. data() {
  3. return {
  4. value: '',
  5. columns: ['杭州', '宁波', '温州', '嘉兴', '湖州'],
  6. showPicker: false,
  7. };
  8. },
  9. methods: {
  10. onConfirm(value) {
  11. this.value = value;
  12. this.showPicker = false;
  13. },
  14. },
  15. };

表单项类型 - 时间选择器

在表单中使用 DatetimePicker 组件

  1. <van-field
  2. readonly
  3. clickable
  4. name="datetimePicker"
  5. :value="value"
  6. label="时间选择"
  7. placeholder="点击选择时间"
  8. @click="showPicker = true"
  9. />
  10. <van-popup v-model="showPicker" position="bottom">
  11. <van-datetime-picker
  12. type="time"
  13. @confirm="onConfirm"
  14. @cancel="showPicker = false"
  15. />
  16. </van-popup>
  1. export default {
  2. data() {
  3. return {
  4. value: '',
  5. showPicker: false,
  6. };
  7. },
  8. methods: {
  9. onConfirm(time) {
  10. this.value = time;
  11. this.showPicker = false;
  12. },
  13. },
  14. };

表单项类型 - 省市区选择器

在表单中使用 Area 组件

  1. <van-field
  2. readonly
  3. clickable
  4. name="area"
  5. :value="value"
  6. label="地区选择"
  7. placeholder="点击选择省市区"
  8. @click="showArea = true"
  9. />
  10. <van-popup v-model="showArea" position="bottom">
  11. <van-area
  12. :area-list="areaList"
  13. @confirm="onConfirm"
  14. @cancel="showArea = false"
  15. />
  16. </van-popup>
  1. export default {
  2. data() {
  3. return {
  4. value: '',
  5. showArea: false,
  6. areaList: {}, // 数据格式见 Area 组件文档
  7. };
  8. },
  9. methods: {
  10. onConfirm(values) {
  11. this.value = values
  12. .filter((item) => !!item)
  13. .map((item) => item.name)
  14. .join('/');
  15. this.showArea = false;
  16. },
  17. },
  18. };

表单项类型 - 日历

在表单中使用 Calendar 组件

  1. <van-field
  2. readonly
  3. clickable
  4. name="calendar"
  5. :value="value"
  6. label="日历"
  7. placeholder="点击选择日期"
  8. @click="showCalendar = true"
  9. />
  10. <van-calendar v-model="showCalendar" @confirm="onConfirm" />
  1. export default {
  2. data() {
  3. return {
  4. value: '',
  5. showCalendar: false,
  6. };
  7. },
  8. methods: {
  9. onConfirm(date) {
  10. this.value = `${date.getMonth() + 1}/${date.getDate()}`;
  11. this.showCalendar = false;
  12. },
  13. },
  14. };

API

Props

参数说明类型默认值
label-width表单项 label 宽度,默认单位为pxnumber | string6.2em
label-align 表单项 label 对齐方式,可选值为 center rightstringleft
input-align输入框对齐方式,可选值为 center rightstringleft
error-message-align错误提示文案对齐方式,可选值为 center rightstringleft
validate-trigger v2.5.2表单校验触发时机,可选值为 onChangeonSubmit,详见下表stringonBlur
colon是否在 label 后面添加冒号booleanfalse
validate-first是否在某一项校验不通过时停止校验booleanfalse
scroll-to-error v2.5.2是否在提交表单且校验不通过时滚动至错误的表单项booleanfalse
show-error v2.6.0是否在校验不通过时标红输入框booleantrue
show-error-message v2.5.8是否在校验不通过时在输入框下方展示错误提示booleantrue
submit-on-enter v2.8.3是否在按下回车键时提交表单booleantrue

表单项的 API 参见:Field 组件

Rule 数据结构

使用 Field 的rules属性可以定义校验规则,可选属性如下:

键名说明类型
required是否为必选字段boolean
message v2.5.3错误提示文案string | (value, rule) => string
validator v2.5.3通过函数进行校验(value, rule) => boolean | Promise
pattern v2.5.3通过正则表达式进行校验RegExp
trigger v2.5.2本项规则的触发时机,可选值为onChangeonBlurstring
formatter v2.5.3格式化函数,将表单项的值转换后进行校验(value, rule) => any

validate-trigger  可选值

通过 validate-trigger 属性可以自定义表单校验的触发时机。

描述
onSubmit仅在提交表单时触发校验
onBlur在提交表单和输入框失焦时触发校验
onChange在提交表单和输入框内容变化时触发校验

Events

事件名说明回调参数
submit提交表单且验证通过后触发values: object
failed提交表单且验证不通过后触发errorInfo: { values: object, errors: object[] }

方法

通过 ref 可以获取到 Form 实例并调用实例方法,详见组件实例方法

方法名说明参数返回值
submit提交表单,与点击提交按钮的效果等价--
validate验证表单,支持传入name来验证单个表单项name?: stringPromise
resetValidation重置表单项的验证提示,支持传入name来重置单个表单项name?: string-
scrollToField v2.8.3滚动到对应表单项的位置,默认滚动到顶部,第二个参数传 false 可滚动至底部name: string, alignToTop: boolean-

Slots

名称说明
default表单内容

常见问题

点击表单中的普通按钮为什么会触发表单提交?

在表单中,除了提交按钮外,可能还有一些其他的功能性按钮,如发送验证码按钮。在使用这些按钮时,要注意将native-type设置为button,否则会触发表单提交。

  1. <van-button native-type="button">
  2. 发送验证码
  3. </van-button>

这个问题的原因是浏览器中 button 标签 type 属性的默认值为submit,导致触发表单提交。我们会在下个大版本中将 type 的默认值调整为button来避免这个问题。

Form 表单 - 图1