Form 表单

介绍

用于数据录入、校验,支持输入框、单选框、复选框、文件上传等类型,需要与 Field 输入框 组件搭配使用。

引入

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

  1. import { createApp } from 'vue';
  2. import { Form, Field, CellGroup } from 'vant';
  3. const app = createApp();
  4. app.use(Form);
  5. app.use(Field);
  6. app.use(CellGroup);

代码演示

基础用法

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

  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';
  2. export default {
  3. setup() {
  4. const username = ref('');
  5. const password = ref('');
  6. const onSubmit = (values) => {
  7. console.log('submit', values);
  8. };
  9. return {
  10. username,
  11. password,
  12. onSubmit,
  13. };
  14. },
  15. };

校验规则

通过 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 { Toast } from 'vant';
  3. export default {
  4. setup() {
  5. const value1 = ref('');
  6. const value2 = ref('');
  7. const value3 = ref('abc');
  8. const value4 = ref('');
  9. const pattern = /\d{6}/;
  10. // 校验函数返回 true 表示校验通过,false 表示不通过
  11. const validator = (val) => /1\d{10}/.test(val);
  12. // 校验函数可以直接返回一段错误提示
  13. const validatorMessage = (val) => `${val} 不合法,请重新输入`;
  14. // 校验函数可以返回 Promise,实现异步校验
  15. const asyncValidator = (val) =>
  16. new Promise((resolve) => {
  17. Toast.loading('验证中...');
  18. setTimeout(() => {
  19. Toast.clear();
  20. resolve(val === '1234');
  21. }, 1000);
  22. });
  23. const onFailed = (errorInfo) => {
  24. console.log('failed', errorInfo);
  25. };
  26. return {
  27. value1,
  28. value2,
  29. value3,
  30. value4,
  31. pattern,
  32. onFailed,
  33. validator,
  34. asyncValidator,
  35. };
  36. },
  37. };

表单项类型 - 开关

在表单中使用 Switch 组件

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

表单项类型 - 复选框

在表单中使用 Checkbox 组件

  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';
  2. export default {
  3. setup() {
  4. const checked = ref(false);
  5. const groupChecked = ref([]);
  6. return {
  7. checked,
  8. groupChecked,
  9. };
  10. },
  11. };

表单项类型 - 单选框

在表单中使用 Radio 组件

  1. <van-field name="radio" label="单选框">
  2. <template #input>
  3. <van-radio-group v-model="checked" 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. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const checked = ref('1');
  5. return { checked };
  6. },
  7. };

表单项类型 - 步进器

在表单中使用 Stepper 组件

  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';
  2. export default {
  3. setup() {
  4. const value = ref(1);
  5. return { value };
  6. },
  7. };

表单项类型 - 评分

在表单中使用 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';
  2. export default {
  3. setup() {
  4. const value = ref(3);
  5. return { value };
  6. },
  7. };

表单项类型 - 滑块

在表单中使用 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';
  2. export default {
  3. setup() {
  4. const value = ref(50);
  5. return { value };
  6. },
  7. };

表单项类型 - 文件上传

在表单中使用 Uploader 组件

  1. <van-field name="uploader" label="文件上传">
  2. <template #input>
  3. <van-uploader v-model="value" />
  4. </template>
  5. </van-field>
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const value = ref([
  5. { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' },
  6. ]);
  7. return { value };
  8. },
  9. };

表单项类型 - 选择器

在表单中使用 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. />
  16. </van-popup>
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const result = ref('');
  5. const showPicker = ref(false);
  6. const columns = ['杭州', '宁波', '温州', '嘉兴', '湖州'];
  7. const onConfirm = (value) => {
  8. result.value = value;
  9. showPicker.value = false;
  10. };
  11. return {
  12. result,
  13. columns,
  14. onConfirm,
  15. showPicker,
  16. };
  17. },
  18. };

表单项类型 - 时间选择器

在表单中使用 DatetimePicker 组件

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

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

在表单中使用 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';
  3. export default {
  4. setup() {
  5. const result = ref('');
  6. const showArea = ref(false);
  7. const onConfirm = (areaValues) => {
  8. showArea.value = false;
  9. result.value = areaValues
  10. .filter((item) => !!item)
  11. .map((item) => item.name)
  12. .join('/');
  13. };
  14. return {
  15. result,
  16. areaList,
  17. showArea,
  18. onConfirm,
  19. };
  20. },
  21. };

表单项类型 - 日历

在表单中使用 Calendar 组件

  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';
  2. export default {
  3. setup() {
  4. const result = ref('');
  5. const showCalendar = ref(false);
  6. const onConfirm = (date) => {
  7. result.value = `${date.getMonth() + 1}/${date.getDate()}`;
  8. showCalendar.value = false;
  9. };
  10. return {
  11. result,
  12. onConfirm,
  13. showCalendar,
  14. };
  15. },
  16. };

API

Props

参数说明类型默认值
label-width表单项 label 宽度,默认单位为pxnumber | string6.2em
label-align表单项 label 对齐方式,可选值为 center rightstringleft
input-align输入框对齐方式,可选值为 center rightstringleft
error-message-align错误提示文案对齐方式,可选值为 center rightstringleft
validate-trigger表单校验触发时机,可选值为 onChangeonSubmit,支持通过数组同时设置多个值,具体用法见下方表格string | string[]onBlur
colon是否在 label 后面添加冒号booleanfalse
disabled是否禁用表单中的所有输入框booleanfalse
readonly是否将表单中的所有输入框设置为只读状态booleanfalse
validate-first是否在某一项校验不通过时停止校验booleanfalse
scroll-to-error是否在提交表单且校验不通过时滚动至错误的表单项booleanfalse
show-error是否在校验不通过时标红输入框booleanfalse
show-error-message是否在校验不通过时在输入框下方展示错误提示booleantrue
submit-on-enter是否在按下回车键时提交表单booleantrue

表单项的 API 参见:Field 组件

Rule 数据结构

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

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

validate-trigger 可选值

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

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

Events

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

方法

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

方法名说明参数返回值
submit提交表单,与点击提交按钮的效果等价--
getValues v3.4.8获取所有表单项当前的值-Record<string, unknown>
validate验证表单,支持传入一个或多个 name 来验证单个或部分表单项,不传入 name 时,会验证所有表单项name?: string | string[]Promise<void>
resetValidation重置表单项的验证提示,支持传入一个或多个 name 来重置单个或部分表单项,不传入 name 时,会重置所有表单项name?: string | string[]-
getValidationStatus v3.5.0获取所有表单项的校验状态,状态包括 passedfailedunvalidated-Record<string, FieldValidationStatus>
scrollToField滚动到对应表单项的位置,默认滚动到顶部,第二个参数传 false 可滚动至底部name: string, alignToTop: boolean-

类型定义

组件导出以下类型定义:

  1. import type { FormProps, FormInstance } from 'vant';

FormInstance 是组件实例的类型,用法如下:

  1. import { ref } from 'vue';
  2. import type { FormInstance } from 'vant';
  3. const formRef = ref<FormInstance>();
  4. formRef.value?.submit();

Slots

名称说明
default表单内容

常见问题

如何自定义表单项?

Vant 支持在 Form 组件中插入自定义的表单项,具体用法参见 useCustomFieldValue

Form 表单 - 图1