Form 表单 - Vant 4

📋 Form 表单

📝 介绍

想象一下，Form 表单就像一个贴心的数据管家，专门负责收集和整理用户的各种信息！🏠 它不仅能优雅地展示各种输入控件，还拥有火眼金睛般的实时校验能力，确保每一份数据都符合要求。

从简单的文本输入到复杂的文件上传，从单选多选到日期选择，Form 表单都能游刃有余地处理。它就像一个万能的收纳盒，把输入框、单选框、复选框、滑块、评分等各种组件完美地组织在一起！✨

最棒的是，它与 Field 输入框组件是最佳拍档，两者配合默契，让数据收集变得既简单又高效。无论是用户注册、信息填写，还是复杂的业务表单，Form 都能让一切井井有条！

💡 小贴士：Form 表单就像一个指挥家，协调着各种表单组件的和谐演奏！

📦 引入

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

import { createApp } from'vue'; 
import { Form, Field, CellGroup } from'vant'; 
const app = createApp(); 
app.use(Form); 
app.use(Field); 
app.use(CellGroup);

🎯 代码演示

🚀 基础用法

让我们从最简单的开始！🌟 在 Form 表单的世界里，每个 Field 组件就像一个勤劳的小工人，负责收集特定的数据。通过 Field 的 rules 属性，你可以为每个小工人制定工作规范（校验规则）。

几行简洁的代码，就能搭建出一个功能完整、颜值在线的表单！就像搭积木一样简单有趣！🧱

html

import { ref } from'vue'; 
export default { 
    setup() { 
        const username = ref(''); 
        const password = ref(''); 
        const onSubmit = (values) => { 
            console.log('submit', values); 
        }; 
        return { username, password, onSubmit, 
            rules: {
                username: [{ required: true, message: '请输入用户名' }],
                password: [{ required: true, message: '请输入密码' }],
            },
        }; 
    }, 
};

🔍 校验规则

Form 表单的校验系统就像一个严格但公正的老师！👩‍🏫 通过 rules 属性，你可以为每个表单项设置各种校验规则，从必填检查到格式验证，从同步校验到异步验证，应有尽有。

无论是简单的非空检查，还是复杂的正则匹配，甚至是需要服务器验证的异步校验，Form 都能轻松应对。让数据验证变得既严谨又优雅！✨

html

import { ref } from'vue'; 
import { closeToast, showLoadingToast } from'vant'; 
export default { 
    setup() { 
        const value1 = ref(''); 
        const value2 = ref(''); 
        const value3 = ref('abc'); 
        const value4 = ref(''); 
        const pattern = /\d{6}/; 
        // 校验函数返回 true 表示校验通过，false 表示不通过
        const validator = (val) => /1\d{10}/.test(val); // 校验函数可以直接返回一段错误提示
        const validatorMessage = (val) => `${val} 不合法，请重新输入`; 
        // 校验函数可以返回 Promise，实现异步校验
        const asyncValidator = (val) => newPromise((resolve) => { showLoadingToast('验证中...'); setTimeout(() => { 
            closeToast(); 
            resolve(val === '1234'); 
        }, 1000); }); 
        const onFailed = (errorInfo) => { 
            console.log('failed', errorInfo); 
        }; 
        return { value1, value2, value3, value4, pattern, onFailed, validator, asyncValidator, }; 
    }, 
};

🎛️ 表单项类型 - 开关

想要一个简洁优雅的开关控制？Switch 组件就像一个精致的电灯开关，轻轻一拨就能切换状态！完美适用于各种开关设置场景。

html

import { ref } from'vue'; export default { setup() { const checked = ref(false); return { checked }; }, };

☑️ 表单项类型 - 复选框

多选题的最佳伙伴！Checkbox 组件就像一个贴心的购物清单，用户可以自由勾选多个选项。无论是兴趣爱好选择还是功能权限配置，都能轻松胜任！

html

import { ref } from'vue'; export default { setup() { const checked = ref(false); const groupChecked = ref([]); return { checked, groupChecked, }; }, };

🔘 表单项类型 - 单选框

选择困难症的救星！Radio 组件就像一个温柔的引导者，帮助用户在多个选项中做出唯一选择。简洁明了，一目了然！

html

import { ref } from'vue'; export default { setup() { const checked = ref('1'); return { checked }; }, };

🔢 表单项类型 - 步进器

数字输入的精确控制器！Stepper 组件就像一个贴心的计数器，让用户通过点击按钮轻松调整数值。购物车数量、年龄选择，都能精准掌控！

html

import { ref } from'vue'; export default { setup() { const value = ref(1); return { value }; }, };

⭐ 表单项类型 - 评分

让用户的满意度闪闪发光！Rate 组件就像一个星光评价师，用户可以通过点击星星来表达自己的评价。直观生动，一目了然！

html

import { ref } from'vue'; export default { setup() { const value = ref(3); return { value }; }, };

🎚️ 表单项类型 - 滑块

流畅的数值调节体验！Slider 组件就像一个优雅的调音台，用户可以通过拖拽滑块来精确调节数值。音量控制、价格筛选，都能丝滑操作！

html

import { ref } from'vue'; export default { setup() { const value = ref(50); return { value }; }, };

📁 表单项类型 - 文件上传

让文件上传变得简单有趣！Uploader 组件就像一个贴心的文件管家，支持图片预览、进度显示、多文件上传。拖拽上传，一键搞定！

html

import { ref } from'vue'; export default { setup() { const value = ref([ { url: 'https://fastly.jsdelivr.net/npm/@vant/assets/leaf.jpeg' }, ]); return { value }; }, };

🎯 表单项类型 - 选择器

海量选项的智能管理器！Picker 组件就像一个旋转的万花筒，让用户在众多选项中轻松找到心仪的那一个。城市选择、职业选择，转一转就搞定！

html

import { ref } from'vue'; export default { setup() { const result = ref(''); const pickerValue = ref([]); const showPicker = ref(false); const columns = [ { text: '杭州', value: 'Hangzhou' }, { text: '宁波', value: 'Ningbo' }, { text: '温州', value: 'Wenzhou' }, { text: '绍兴', value: 'Shaoxing' }, { text: '湖州', value: 'Huzhou' }, ]; constonConfirm = ({ selectedValues, selectedOptions }) => { result.value = selectedOptions[0]?.text; pickerValue.value = selectedValues; showPicker.value = false; }; return { result, pickerValue, columns, onConfirm, showPicker, }; }, };

📅 表单项类型 - 日期选择器

时间旅行的精准导航！DatePicker 组件就像一个时光机器，让用户轻松穿梭在年月日之间。生日选择、预约时间，一滚一选就搞定！

html

import { ref } from'vue'; export default { setup() { const result = ref(''); const showPicker = ref(false); const pickerValue = ref([]); const onConfirm = ({ selectedValues }) => { result.value = selectedValues.join('/'); pickerValue.value = selectedValues; showPicker.value = false; }; return { result, pickerValue, onConfirm, showPicker, }; }, };

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

地理位置的智能向导！Area 组件就像一个贴心的地图助手，帮助用户快速定位到具体的省市区。地址填写、配送范围，层层递进，精准定位！

html

import { ref } from'vue'; import { areaList } from'@vant/area-data'; export default { setup() { const result = ref(''); const showArea = ref(false); const pickerValue = ref(''); const onConfirm = ({ selectedValues, selectedOptions }) => { pickerValue.value = selectedValues.length ? selectedValues[selectedValues.length - 1] : ''; showArea.value = false; result.value = selectedOptions.map((item) => item.text).join('/'); }; return { result, areaList, pickerValue, showArea, onConfirm, }; }, };

📆 表单项类型 - 日历

直观的日期选择体验！Calendar 组件就像一个精美的桌面日历，用户可以直观地浏览和选择日期。节假日安排、活动预约，一目了然！

html

import { ref } from'vue'; export default { setup() { const result = ref(''); const showCalendar = ref(false); const onConfirm = (date) => { result.value = `${date.getMonth() + 1}/${date.getDate()}`; showCalendar.value = false; }; return { result, onConfirm, showCalendar, }; }, };

API

Props

参数	说明	类型	默认值
label-width	表单项 label 宽度，默认单位为`px`	*number	string*
label-align	表单项 label 对齐方式，可选值为 center``right``top	string	`left`
input-align	输入框对齐方式，可选值为 center``right	string	`left`
error-message-align	错误提示文案对齐方式，可选值为 center``right	string	`left`
validate-trigger	表单校验触发时机，可选值为 `onChange`、`onSubmit`，支持通过数组同时设置多个值，具体用法见下方表格	*string	string[]*
colon	是否在 label 后面添加冒号	boolean	`false`
disabled	是否禁用表单中的所有输入框	boolean	`false`
readonly	是否将表单中的所有输入框设置为只读状态	boolean	`false`
required `v4.7.3`	是否显示表单必填星号	*boolean	'auto'*
validate-first	是否在某一项校验不通过时停止校验	boolean	`false`
scroll-to-error	是否在提交表单且校验不通过时滚动至错误的表单项	boolean	`false`
scroll-to-error-position `v4.9.2`	滚动至错误的表单项时的位置，可选值为 `center`	`end`	`nearest`
show-error	是否在校验不通过时标红输入框	boolean	`false`
show-error-message	是否在校验不通过时在输入框下方展示错误提示	boolean	`true`
submit-on-enter	是否在按下回车键时提交表单	boolean	`true`

表单项的 API 参见：Field 组件

Rule 数据结构

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

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

validate-trigger 可选值

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

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

Events

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

方法

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

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

类型定义

组件导出以下类型定义：

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

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

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

Slots

名称	说明
default	表单内容

❓ 常见问题

🎨 如何自定义表单项？

想要创建独一无二的表单项？没问题！🌟 Vant 就像一个开放的创作平台，完全支持在 Form 组件中插入你的自定义表单项。

通过 useCustomFieldValue 这个神奇的工具，你可以让任何自定义组件都能完美融入 Form 表单的校验体系中。就像给你的创意插上翅膀，让它在表单的世界里自由翱翔！✨

📚 相关文档

Form 表单与这些组件搭配使用，能创造出更丰富的数据收集体验：

Field 输入框 - Form 表单的最佳拍档，各种输入场景的万能选手 📝
Button 按钮 - 表单提交的触发器，让操作更加明确 🔘
Cell 单元格 - 表单项的优雅容器，让布局更加整齐 📋
CellGroup 单元格组 - 表单项的分组管理，让结构更加清晰 📦
Switch 开关 - 简洁的开关控制组件 🎛️
Checkbox 复选框 - 多选场景的完美解决方案 ☑️
Radio 单选框 - 单选场景的优雅选择 🔘
Stepper 步进器 - 数值输入的精确控制 🔢
Rate 评分 - 用户评价的星级展示 ⭐
Slider 滑块 - 数值调节的流畅体验 🎚️
Uploader 文件上传 - 文件上传的贴心管家 📁
Picker 选择器 - 海量选项的智能管理 🎯
DatePicker 日期选择器 - 时间选择的精准导航 📅
Area 省市区选择器 - 地理位置的智能向导 🗺️
Calendar 日历 - 直观的日期选择体验 📆
Highlight 文本高亮 - 关键词标注的专业工具 🔍

📋 Form 表单 ​

📝 介绍 ​

📦 引入 ​

🎯 代码演示 ​

🚀 基础用法 ​

🔍 校验规则 ​

🎛️ 表单项类型 - 开关 ​

☑️ 表单项类型 - 复选框 ​

🔘 表单项类型 - 单选框 ​

🔢 表单项类型 - 步进器 ​

⭐ 表单项类型 - 评分 ​

🎚️ 表单项类型 - 滑块 ​

📁 表单项类型 - 文件上传 ​

🎯 表单项类型 - 选择器 ​

📅 表单项类型 - 日期选择器 ​

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

📆 表单项类型 - 日历 ​

API ​

Props ​

Rule 数据结构 ​

validate-trigger 可选值 ​

Events ​

方法 ​

类型定义 ​

Slots ​

❓ 常见问题 ​

🎨 如何自定义表单项？ ​

📚 相关文档 ​

📋 Form 表单

📝 介绍

📦 引入

🎯 代码演示

🚀 基础用法

🔍 校验规则

🎛️ 表单项类型 - 开关

☑️ 表单项类型 - 复选框

🔘 表单项类型 - 单选框

🔢 表单项类型 - 步进器

⭐ 表单项类型 - 评分

🎚️ 表单项类型 - 滑块

📁 表单项类型 - 文件上传

🎯 表单项类型 - 选择器

📅 表单项类型 - 日期选择器

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

📆 表单项类型 - 日历

API

Props

Rule 数据结构

validate-trigger 可选值

Events

方法

类型定义

Slots

❓ 常见问题

🎨 如何自定义表单项？

📚 相关文档