shadcn-vue 与 VeeValidate 表单开发实战：Zod 校验、错误处理与动态数组字段

UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载本指南基于 shadcn-vue 官方文档 VeeValidate 表单指南 展开系统讲解如何在 shadcn-vue 项目中用 VeeValidate 与 Zod 构建高性能、可访问的表单。你将掌握useForm组合式 API、Field /作用域插槽绑定、toTypedSchema客户端校验、多类型控件输入框、选择框、复选框、单选组、开关的接入以及用FieldArray/useFieldArray管理动态数组字段的完整方案。技术选型为什么用 VeeValidate ZodVeeValidate 是 Vue 生态中成熟且性能优异的表单校验库它的核心理念是无头headless不强制你使用它的标记而是通过组合式函数与作用域插槽把状态、校验逻辑交给开发者自由编排。这正是 shadcn-vue 这类以样式与结构分离为设计哲学的组件库的理想搭档。官方文档在 Approach 一节 明确了本方案的四层组成使用 VeeValidate 的useForm组合式函数管理表单状态使用 VeeValidate 的Field /组件 作用域插槽实现受控输入与校验使用 shadcn-vue 的Field /系列组件构建可访问的表单布局使用 Zod 配合toTypedSchema完成客户端校验。简单说VeeValidate 负责状态与逻辑shadcn-vue 的 Field 系列负责结构与语义Zod 负责数据规则。Anatomy 组合模式VeeValidate 的Field /组件通过作用域插槽暴露字段状态再将其绑定到 shadcn-vue 控件上。文档特别强调了一个关键区分当控件是带v-model的 Vue 组件如 shadcn-vue 的Input /时绑定componentField当控件是原生元素时绑定field。field绑定的是value而v-model组件会忽略value属性导致initialValues永远无法渲染。以 Bug Report 表单的标题字段为例组件模式绑定componentFieldtemplate VeeField v-slot{ componentField, errors } nametitle Field :data-invalid!!errors.length FieldLabel fortitle Bug Title /FieldLabel Input idtitle v-bindcomponentField placeholderLogin button not working on mobile autocompleteoff :aria-invalid!!errors.length / FieldDescription Provide a concise title for your bug report. /FieldDescription FieldError v-iferrors.length :errorserrors / /Field /VeeField /template原生元素模式绑定fieldtemplate VeeField v-slot{ field, errors } nametitle Field :data-invalid!!errors.length FieldLabel fortitle Bug Title /FieldLabel input idtitle v-bindfield placeholderLogin button not working on mobile autocompleteoff :aria-invalid!!errors.length FieldDescription Provide a concise title for your bug report. /FieldDescription FieldError v-iferrors.length :errorserrors / /Field /VeeField /template两者的模板结构完全一致唯一差别是绑定对象componentField面向组件提供modelValue、update:modelValue等field面向原生元素提供value、onInput等。这也是官方推荐用componentField搭配 shadcn-vue 组件、用field搭配原生标签的原因。shadcn-vue 侧Field系列组件位于 apps/v4/registry/new-york-v4/ui/field包含Field、FieldContent、FieldDescription、FieldError、FieldGroup、FieldLabel、FieldLegend、FieldSeparator、FieldSet、FieldTitle十个成员覆盖从单字段到字段集FieldSet Legend的完整语义化布局。从零构建一个 Bug Report 表单第一步定义 Zod 校验 Schema先用 Zod 定义表单数据的形状与规则。官方文档在此处特别提示示例使用zod v3但你可以替换为 VeeValidate 支持的任何 Standard Schema 校验库如 valibot、yup 等。script setup langts import * as z from zod const formSchema z.object({ title: z .string() .min(5, Bug title must be at least 5 characters.) .max(32, Bug title must be at most 32 characters.), description: z .string() .min(20, Description must be at least 20 characters.) .max(100, Description must be at most 100 characters.), }) /script第二步用 useForm 初始化表单通过useForm创建表单实例并把 Zod schema 经toTypedSchema转为 VeeValidate 可识别的校验配置同时声明initialValuesscript setup langts import { toTypedSchema } from vee-validate/zod import { useForm, Field as VeeField } from vee-validate import * as z from zod const formSchema z.object({ title: z .string() .min(5, Bug title must be at least 5 characters.) .max(32, Bug title must be at most 32 characters.), description: z .string() .min(20, Description must be at least 20 characters.) .max(100, Description must be at most 100 characters.), }) const { handleSubmit } useForm({ validationSchema: toTypedSchema(formSchema), initialValues: { title: , description: , }, }) const onSubmit handleSubmit((values) { // Do something with the form values. console.log(values) }) /script template form submitonSubmit !-- Build the form here -- /form /template这里有几个要点toTypedSchema负责把 Zod schema 转换为 VeeValidate 的validationSchema格式并保留完整的 TypeScript 类型推导handleSubmit返回一个事件处理器直接绑定到form submit上。只有校验通过时回调才会被调用并拿到经过校验与类型转换后的valuesinitialValues会在表单创建时填充各字段的初始值。第三步组装完整的 Bug Report 表单完整的成品可直接参考仓库中的 VeeValidateDemo.vue。该示例是一个 Bug Report 卡片表单标题输入框、带字数统计的描述文本框以及 Reset / Submit 两个按钮。值得关注的实现细节描述字段使用InputGroupInputGroupTextareaInputGroupAddon组合底部用{{ value?.length || 0 }}/100 characters实时显示字符数value同样来自VeeField的作用域插槽Submit 按钮通过formform-vee-demo属性指向form的id从而可以在卡片底部表单外部触发提交Reset 按钮调用useForm返回的resetForm点击后恢复初始值。文档中这个 Demo 特意关闭了浏览器原生校验未使用required、minlength等 HTML 属性以便展示 schema 校验与表单错误在 VeeValidate 中的工作方式。官方提示生产环境建议保留基础的原生校验作为兜底。客户端校验与校验模式VeeValidate 通过validationSchema选项消费 Zod schema从而在客户端完成全部校验无需与服务端往返。简化版示例script setup langts import { toTypedSchema } from vee-validate/zod import { useForm, Field as VeeField } from vee-validate import * as z from zod const formSchema z.object({ title: z.string(), description: z.string().optional(), }) const { handleSubmit } useForm({ validationSchema: toTypedSchema(formSchema), initialValues: { title: , description: , }, }) /script校验触发时机不同场景对校验时机的需求不同有的希望输入即校验有的希望失焦后再提示。VeeValidate 通过Field /的 props 提供四种校验策略VeeField v-slot{ componentField, errors } nametitle :validate-on-inputtrue !-- field content -- /VeeFieldProp说明validateOnInput在 input 事件触发时校验validateOnChange在 change 事件触发时校验validateOnBlur在 blur失焦事件触发时校验validateOnMount在组件挂载时触发校验可以在单个Field /上组合使用例如失焦 输入时都校验。错误展示与无障碍错误展示遵循两层分工:data-invalid加在 shadcn-vue 的Field /上用于驱动样式如红色边框、错误态配色:aria-invalid加在具体控件Input /、SelectTrigger /、Checkbox /等上用于驱动无障碍语义让屏幕阅读器感知字段状态FieldError /负责把错误列表渲染为可访问的提示文本。template VeeField v-slot{ componentField, errors } nameemail Field :data-invalid!!errors.length FieldLabel foremail Email /FieldLabel Input idemail v-bindcomponentField typeemail :aria-invalid!!errors.length / FieldError v-iferrors.length :errorserrors / /Field /VeeField /template从源码看FieldError.vue 的实现颇具巧思通过computed对传入的errors数组做去重用Map以错误消息为 key 合并重复项错误来源支持两种形态纯字符串或{ message: string | undefined }对象兼容不同校验库的返回结构单个错误渲染为一行文本多个错误渲染为带list-disc项目符号的ul列表根元素带有rolealert与data-slotfield-error错误出现时通知辅助技术。覆盖不同控件类型Input 输入框v-bindcomponentField绑定、aria-invaliddata-invalid标注错误态即可。完整示例见 VeeValidateInputDemo.vue其 schema 演示了regex校验用户名只能包含字母、数字与下划线template VeeField v-slot{ componentField, errors } namename Field :data-invalid!!errors.length FieldLabel forname Name /FieldLabel Input idname v-bindcomponentField placeholderEnter your name :aria-invalid!!errors.length / FieldError v-iferrors.length :errorserrors / /Field /VeeField /templateTextarea 文本域用法与 Input 相同可叠加自定义类调整尺寸。参考 VeeValidateTextareaDemo.vuetemplate VeeField v-slot{ componentField, errors } nameabout Field :data-invalid!!errors.length FieldLabel forabout More about you /FieldLabel Textarea idabout v-bindcomponentField placeholderIm a software engineer... classmin-h-[120px] :aria-invalid!!errors.length / FieldDescription Tell us more about yourself. This will be used to help us personalize your experience. /FieldDescription FieldError v-iferrors.length :errorserrors / /Field /VeeField /templateSelect 下拉选择与 Input 不同Select 把v-bindcomponentField加在Select /根组件上——它会一次性绑定modelValue、update:modelValue和name。错误态标注在SelectTrigger /上。参考 VeeValidateSelectDemo.vuetemplate VeeField v-slot{ componentField, errors } namelanguage Field orientationresponsive :data-invalid!!errors.length FieldContent FieldLabel forlanguage Spoken Language /FieldLabel FieldDescriptionFor best results, select the language you speak./FieldDescription FieldError v-iferrors.length :errorserrors / /FieldContent Select v-bindcomponentField SelectTrigger idlanguage classmin-w-[120px] :aria-invalid!!errors.length SelectValue placeholderSelect / /SelectTrigger SelectContent positionitem-aligned SelectItem valueauto Auto /SelectItem SelectItem valueen English /SelectItem /SelectContent /Select /Field /VeeField /template这里用到了Field orientationresponsive与FieldContent组合实现标签、描述与控件在窄屏垂直堆叠、宽屏水平排列的响应式布局。Checkbox 复选框复选框分两种形态规则差异明显单个布尔复选框v-bindcomponentField同时在 VeeValidate 的Field /上设置typecheckbox让值按布尔处理template VeeField v-slot{ componentField, errors } nameresponses typecheckbox FieldSet :data-invalid!!errors.length FieldLegend variantlabel Responses /FieldLegend FieldDescriptionGet notified for requests that take time./FieldDescription FieldGroup>template VeeField v-slot{ value, handleChange, errors } nametasks FieldSet :data-invalid!!errors.length FieldLegend variantlabel Tasks /FieldLegend FieldDescriptionGet notified when tasks youve created have updates./FieldDescription FieldGroup>template VeeField v-slot{ componentField, errors } nameplan FieldSet :data-invalid!!errors.length FieldLegendPlan/FieldLegend FieldDescription You can upgrade or downgrade your plan at any time. /FieldDescription RadioGroup v-bindcomponentField :aria-invalid!!errors.length FieldLabel v-forplanOption in plans :keyplanOption.id :forplan-${planOption.id} Field orientationhorizontal :data-invalid!!errors.length FieldContent FieldTitle{{ planOption.title }}/FieldTitle FieldDescription{{ planOption.description }}/FieldDescription /FieldContent RadioGroupItem :idplan-${planOption.id} :valueplanOption.id / /Field /FieldLabel /RadioGroup FieldError v-iferrors.length :errorserrors / /FieldSet /VeeField /template这里用FieldLabel包裹整行标题 描述 单选圆点使整行可点击选中是典型的卡片式单选布局。Switch 开关与布尔复选框一致v-bindcomponentFieldtypecheckbox让值按布尔处理template VeeField v-slot{ componentField, errors } nametwoFactor typecheckbox Field orientationhorizontal :data-invalid!!errors.length FieldContent FieldLabel fortwo-factor Multi-factor authentication /FieldLabel FieldDescription Enable multi-factor authentication to secure your account. /FieldDescription FieldError v-iferrors.length :errorserrors / /FieldContent Switch idtwo-factor v-bindcomponentField :aria-invalid!!errors.length / /Field /VeeField /template参考 VeeValidateSwitchDemo.vue其 schema 用z.boolean().refine(val val true, {...})实现必须开启双因素认证的强制校验。复杂表单示例将上述控件组合进一个表单即构成 VeeValidateComplexDemo.vue 演示的订阅偏好设置表单单选组选择套餐、Select 选择计费周期、复选框数组选择附加服务、Switch 开关邮件通知字段之间用FieldSeparator分隔。其 schema 展示了更丰富的 Zod 用法可作为复杂校验的模板const formSchema toTypedSchema( z.object({ plan: z .string({ required_error: Please select a subscription plan }) .min(1, Please select a subscription plan) .refine(value value basic || value pro, { message: Invalid plan selection. Please choose Basic or Pro, }), billingPeriod: z .string({ required_error: Please select a billing period }) .min(1, Please select a billing period), addons: z .array(z.string()) .min(1, Please select at least one add-on) .max(3, You can select up to 3 add-ons) .refine( value value.every(addon addons.some(a a.id addon)), { message: You selected an invalid add-on }, ), emailNotifications: z.boolean(), }), )要点required_error用于未填写时的错误消息refine用于自定义业务规则如套餐必须为 Basic/Pro、附加服务必须来自预定义列表数组字段用min/max约束数量。重置表单useForm返回的resetForm函数可以把表单恢复到initialValues。配合Button typebutton使用避免误触表单提交script setup langts const { handleSubmit, resetForm } useForm({ validationSchema: formSchema, // ... }) /script template Button typebutton variantoutline clickresetForm Reset /Button /template动态数组字段动态增删字段如添加/删除多个邮箱地址是 VeeValidate 的强项核心是FieldArray组件与useFieldArray组合式函数。使用 FieldArrayFieldArray通过作用域插槽暴露fields、push、remove三个核心成员script setup langts import { FieldArray as VeeFieldArray } from vee-validate /script template VeeFieldArray v-slot{ fields, push, remove } nameemails !-- Array items go here -- /VeeFieldArray /template数组字段结构用FieldSet /FieldLegend /FieldDescription /包裹数组区域形成语义完整的字段组template FieldSet classgap-4 FieldLegend variantlabel Email Addresses /FieldLegend FieldDescription Add up to 5 email addresses where we can contact you. /FieldDescription FieldGroup classgap-4 !-- Array items go here -- /FieldGroup /FieldSet /template数组项字段模式遍历fields为每项渲染字段。必须使用field.key作为v-for的 key否则增删项时会出现状态错乱。字段名使用索引路径emails[${index}].addresstemplate VeeFieldArray v-slot{ fields, push, remove } nameemails VeeField v-for(field, index) in fields :keyfield.key v-slot{ componentField: controllerField, errors } :nameemails[${index}].address Field orientationhorizontal :data-invalid!!errors.length FieldContent classflex-1 InputGroup InputGroupInput :idemail-${index} v-bindcontrollerField typeemail placeholdernameexample.com autocompleteemail :aria-invalid!!errors.length / !-- Remove button -- /InputGroup FieldError v-iferrors.length :errorserrors / /FieldContent /Field /VeeField /VeeFieldArray /template添加与移除数组项添加用push可同时限制最大数量这里限制 5 条template Button typebutton variantoutline sizesm :disabledfields.length 5 clickpush({ address: }) Add Email Address /Button /template移除用remove(index)通常放在输入框右侧的图标按钮上并配合v-if保证至少保留一项template InputGroupAddon v-iffields.length 1 aligninline-end InputGroupButton typebutton variantghost sizeicon-xs :aria-labelRemove email ${index 1} clickremove(index) XIcon / /InputGroupButton /InputGroupAddon /template数组校验Zod 侧用array方法定义数组规则min/max控制数量内层object定义每项的字段校验const formSchema z.object({ emails: z .array( z.object({ address: z.string().email(Enter a valid email address.), }), ) .min(1, Add at least one email address.) .max(5, You can add up to 5 email addresses.), })组合式写法useFieldArray官方文档以FieldArray组件为主线但仓库中的完整示例 VeeValidateArrayDemo.vue 展示了更贴合 Composition API 风格的等价写法——通过useFieldArray在script setup中直接获取控制器const { handleSubmit, resetForm, errors } useForm({ validationSchema: formSchema, initialValues: { emails: [{ address: }, { address: }], }, }) const { remove, push, fields } useFieldArray(emails) function addEmail() { push({ address: }) }模板中fields、push、remove直接可用行为与FieldArray插槽完全一致另外示例还在表单底部通过errors.emails展示了数组级非单项级错误的展示方式FieldError v-iferrors.emails :errors[errors.emails] /源码验证错误渲染与字段组件若要深入理解 shadcn-vue 侧的错误展示机制可直接阅读 FieldError.vueerrorsprop 接受Arraystring | { message: string | undefined } | undefined兼容 VeeValidate 直接输出的错误数组内部用Map以消息文本为键去重过滤空值避免同一规则触发多次产生重复提示渲染时单条错误输出为文本多条错误输出为ul classml-4 flex list-disc flex-col gap-1列表每行一条根节点带rolealert错误出现时屏幕阅读器会立即播报。小结至此你已掌握在 shadcn-vue 中构建完整表单的全部关键路径Zod 定义规则→z.object描述结构min/max/email/refine描述约束useForm 初始化→validationSchema: toTypedSchema(formSchema)initialValuesField 组合→ VeeValidateField /作用域插槽取状态shadcn-vue Field 系列搭布局componentField组件/field原生元素二选一绑定错误态→:data-invalid驱动样式、:aria-invalid驱动无障碍、FieldError /渲染消息动态数组→FieldArray/useFieldArraypush/remove/fields配合field.key与索引路径字段名提交与重置→handleSubmit只在校验通过后触发resetForm一键恢复初始值。文中所有示例组件均可在此仓库中直接查看与运行apps/v4/components/demo 目录下的VeeValidate*.vue系列文件它们与本指南一一对应可作为你落地生产代码的起点。赞分享UI组件前端【免费下载链接】shadcn-vueVue port of shadcn-ui项目地址https://gitcode.com/gh_mirrors/sh/shadcn-vue点击查看免费下载相关推荐Vue表单三大难题一解vee-validate跨字段校验、异步校验与动态触发器Vue表单三大难题一解vee validate跨字段校验、异步校验与动态触发器 在做 Vue 表单时 跨字段校验、异步校验、动态触发时机 是最让人头疼的三个前端UI组件React Hook Form 动态表单开发实战条件字段与表单数组性能优化指南React Hook Form 动态表单开发实战条件字段与表单数组性能优化指南 在现代前端开发中表单处理往往是项目复杂度的重要来源。传统的受控组件方案虽然直前端Vue-Multiselect 表单验证与错误处理最佳实践Vue Multiselect 表单验证与错误处理最佳实践 Vue Multiselect 是一个功能强大的 Vue.js 选择组件提供了丰富的表单验证和错误前端UI组件上一篇从单条视频到批量归档BilibiliDown B站视频下载器上手指南下一篇Instatic 社交分享实战5 步做出一张带图带字的预览卡片创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考