Form 表单

引入

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

基础用法

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

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

校验规则

通过 rules 定义表单校验规则，所有可用字段见。

  1. <van-form @failed="onFailed">
  2.   <van-cell-group inset>
  3.     <!-- 通过 pattern 进行正则校验 -->
  4.     <van-field
  5.       v-model="value1"
  6.       name="pattern"
  7.       placeholder="正则校验"
  8.       :rules="[{ pattern, message: '请输入正确内容' }]"
  9.     />
  10.     <!-- 通过 validator 进行函数校验 -->
  11.     <van-field
  12.       v-model="value2"
  13.       name="validator"
  14.       placeholder="函数校验"
  15.       :rules="[{ validator, message: '请输入正确内容' }]"
  16.     />
  17.     <!-- 通过 validator 返回错误提示 -->
  18.     <van-field
  19.       v-model="value3"
  20.       name="validatorMessage"
  21.       placeholder="校验函数返回错误提示"
  22.       :rules="[{ validator: validatorMessage }]"
  23.     />
  24.     <!-- 通过 validator 进行异步函数校验 -->
  25.     <van-field
  26.       v-model="value4"
  27.       name="asyncValidator"
  28.       placeholder="异步函数校验"
  29.       :rules="[{ validator: asyncValidator, message: '请输入正确内容' }]"
  30.     />
  31.   </van-cell-group>
  32.   <div style="margin: 16px;">
  33.     <van-button round block type="primary" native-type="submit">
  34.       提交
  35.     </van-button>
  36.   </div>
  37. </van-form>
  1. import { ref } from 'vue';
  2. import { closeToast, showLoadingToast } from 'vant';
  4. export default {
  5.   setup() {
  6.     const value1 = ref('');
  7.     const value2 = ref('');
  8.     const value3 = ref('abc');
  9.     const value4 = ref('');
  10.     const pattern = /\d{6}/;
  12.     // 校验函数返回 true 表示校验通过，false 表示不通过
  13.     const validator = (val) => /1\d{10}/.test(val);
  15.     // 校验函数可以直接返回一段错误提示
  16.     const validatorMessage = (val) => `${val} 不合法，请重新输入`;
  18.     // 校验函数可以返回 Promise，实现异步校验
  19.     const asyncValidator = (val) =>
  20.       new Promise((resolve) => {
  21.         showLoadingToast('验证中...');
  23.           closeToast();
  24.           resolve(val === '1234');
  25.         }, 1000);
  26.       });
  28.     const onFailed = (errorInfo) => {
  29.       console.log('failed', errorInfo);
  30.     };
  32.     return {
  33.       value1,
  34.       value2,
  35.       value3,
  36.       value4,
  37.       pattern,
  38.       onFailed,
  39.       validator,
  40.       asyncValidator,
  41.     };
  42.   },
  43. };

表单项类型 - 开关

在表单中使用 。

  1. <van-field name="switch" label="开关">
  2.   <template #input>
  3.     <van-switch v-model="checked" />
  4.   </template>
  5. </van-field>
  1. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const checked = ref(false);
  7.   },
  8. };

表单项类型 - 复选框

在表单中使用 。

  1. <van-field name="checkbox" label="复选框">
  2.   <template #input>
  3.     <van-checkbox v-model="checked" shape="square" />
  4.   </template>
  5. </van-field>
  6. <van-field name="checkboxGroup" label="复选框组">
  7.   <template #input>
  8.     <van-checkbox-group v-model="groupChecked" 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. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const checked = ref(false);
  6.     const groupChecked = ref([]);
  7.     return {
  8.       checked,
  9.       groupChecked,
  10.     };
  11.   },
  12. };

表单项类型 - 单选框

在表单中使用 。

  1. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const checked = ref('1');
  6.     return { checked };
  7.   },
  8. };
  1. <van-field name="stepper" label="步进器">
  2.   <template #input>
  3.     <van-stepper v-model="value" />
  4.   </template>
  5. </van-field>
  1. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const value = ref(1);
  6.     return { value };
  7.   },
  8. };

表单项类型 - 评分

在表单中使用 Rate 组件。

  1. <van-field name="rate" label="评分">
  2.   <template #input>
  3.     <van-rate v-model="value" />
  4.   </template>
  5. </van-field>
  1. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const value = ref(3);
  6.     return { value };
  7.   },
  8. };

表单项类型 - 滑块

在表单中使用 Slider 组件。

  1. <van-field name="slider" label="滑块">
  2.   <template #input>
  3.     <van-slider v-model="value" />
  4.   </template>
  5. </van-field>
  1. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const value = ref(50);
  6.     return { value };
  7.   },
  8. };

表单项类型 - 文件上传

在表单中使用 Uploader 组件。

  1. <van-field name="uploader" label="文件上传">
  2.   <template #input>
  3.     <van-uploader v-model="value" />
  4.   </template>
  5. </van-field>

表单项类型 - 选择器

在表单中使用 Picker 组件。

  1. <van-field
  2.   v-model="result"
  3.   is-link
  4.   readonly
  5.   name="picker"
  6.   label="选择器"
  7.   placeholder="点击选择城市"
  8.   @click="showPicker = true"
  9. />
  10. <van-popup v-model:show="showPicker" position="bottom">
  11.   <van-picker
  12.     :columns="columns"
  13.     @confirm="onConfirm"
  14.     @cancel="showPicker = false"
  15.   />
  1. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const result = ref('');
  6.     const showPicker = ref(false);
  7.     const columns = [
  8.       { text: '杭州', value: 'Hangzhou' },
  9.       { text: '宁波', value: 'Ningbo' },
  10.       { text: '温州', value: 'Wenzhou' },
  11.       { text: '绍兴', value: 'Shaoxing' },
  12.       { text: '湖州', value: 'Huzhou' },
  13.     ];
  15.     const onConfirm = ({ selectedOptions }) => {
  16.       result.value = selectedOptions[0]?.text;
  17.       showPicker.value = false;
  18.     };
  20.     return {
  21.       result,
  22.       columns,
  23.       onConfirm,
  24.       showPicker,
  25.     };
  26.   },
  27. };

表单项类型 - 日期选择器

在表单中使用 DatePicker 组件。

  1. <van-field
  2.   v-model="result"
  3.   is-link
  4.   readonly
  5.   name="datePicker"
  6.   label="时间选择"
  7.   placeholder="点击选择时间"
  8.   @click="showPicker = true"
  9. />
  10. <van-popup v-model:show="showPicker" position="bottom">
  11.   <van-date-picker @confirm="onConfirm" @cancel="showPicker = false" />
  1. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const result = ref('');
  6.     const showPicker = ref(false);
  7.     const onConfirm = ({ selectedValues }) => {
  8.       result.value = selectedValues.join('/');
  9.       showPicker.value = false;
  10.     };
  12.     return {
  13.       result,
  14.       onConfirm,
  15.       showPicker,
  16.     };
  17.   },
  18. };

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

在表单中使用 Area 组件。

  1. <van-field
  2.   v-model="result"
  3.   is-link
  4.   readonly
  5.   name="area"
  6.   label="地区选择"
  7.   placeholder="点击选择省市区"
  8.   @click="showArea = true"
  9. />
  10. <van-popup v-model:show="showArea" position="bottom">
  11.   <van-area
  12.     :area-list="areaList"
  13.     @confirm="onConfirm"
  14.     @cancel="showArea = false"
  15.   />
  16. </van-popup>
  1. import { ref } from 'vue';
  2. import { areaList } from '@vant/area-data';
  4. export default {
  5.   setup() {
  6.     const result = ref('');
  7.     const showArea = ref(false);
  8.     const onConfirm = ({ selectedOptions }) => {
  9.       showArea.value = false;
  10.       areaCode.value = selectedOptions.map((item) => item.text).join('/');
  11.     };
  13.     return {
  14.       result,
  15.       areaList,
  16.       showArea,
  17.       onConfirm,
  18.     };
  19.   },
  20. };
  1. <van-field
  2.   v-model="value"
  3.   is-link
  4.   readonly
  5.   name="calendar"
  6.   label="日历"
  7.   placeholder="点击选择日期"
  8.   @click="showCalendar = true"
  9. />
  10. <van-calendar v-model:show="showCalendar" @confirm="onConfirm" />
  1. import { ref } from 'vue';
  3. export default {
  4.   setup() {
  5.     const result = ref('');
  6.     const showCalendar = ref(false);
  7.     const onConfirm = (date) => {
  8.       result.value = `${date.getMonth() + 1}/${date.getDate()}`;
  9.       showCalendar.value = false;
  10.     };
  12.     return {
  13.       result,
  14.       onConfirm,
  15.       showCalendar,
  16.     };
  17.   },
  18. };

Props

Rule 数据结构

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

键名说明类型
required是否为必选字段，当值为空值时（空字符串、空数组、false、undefined、null ），校验不通过boolean
message错误提示文案，可以设置为一个函数来返回动态的文案内容string | (value, rule) => string
validator通过函数进行校验，可以返回一个 Promise 来进行异步校验(value, rule) => boolean | string | Promise
pattern通过正则表达式进行校验，正则无法匹配表示校验不通过RegExp
trigger设置本项规则的触发时机，优先级高于 Form 组件设置的 validate-trigger 属性，可选值为 onChange、onBlur、onSubmitstring | string[]
formatter格式化函数，将表单项的值转换后进行校验(value, rule) => any
validateEmpty v3.6.0设置 validator 和 pattern 是否要对空值进行校验，默认值为 true，可以设置为 false 来禁用该行为boolean

validate-trigger 可选值

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

Events

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

方法

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

类型定义

组件导出以下类型定义：

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

  1. import { ref } from 'vue';
  2. import type { FormInstance } from 'vant';
  4. const formRef = ref<FormInstance>();
名称说明
default表单内容

如何自定义表单项？