表单处理很棘手。它们是 Web 应用中最常构建的功能之一，同时也是最复杂的部分之一。

设计良好的 HTML 表单应具备：

• 结构良好且语义正确
• 易于使用和导航（支持键盘操作）
• 通过 ARIA 属性和适当标签实现无障碍访问
• 支持客户端和服务器端验证
• 样式美观且与应用程序其他部分保持一致

本指南将介绍如何使用 vee-validate 和 zod 构建表单。我们将使用 <FormField> 组件，通过 Reka UI 组件组合出可访问的表单。

功能特性

<Form /> 组件是对 vee-validate 库的封装，提供以下功能：

• 用于构建表单的可组合组件
• 用于构建受控表单字段的 <FormField /> 组件
• 使用 zod 进行表单验证
• 根据状态为表单字段应用正确的 aria 属性，处理唯一 ID
• 设计与所有 Reka UI 组件协同工作
• 支持自定义模式库：我们使用 zod，但您也可以使用其他支持的验证库，如 yup 或 valibot
• 您完全控制标记和样式

vee-validate 提供两种方式为表单添加验证：

• 组合式 API
• 高阶组件（HOC）

结构剖析

<template>
  <Form>
    <FormField>
      <FormItem>
        <FormLabel />
        <FormControl>
        <!-- 任意表单输入组件或原生输入元素 -->
        </FormControl>
        <FormDescription />
        <FormMessage />
      </FormItem>
    </FormField>
  </Form>
</template>

示例

Input 组件

<template>
  <FormField v-slot="{ componentField }">
    <FormItem>
      <FormLabel>用户名</FormLabel>
      <FormControl>
        <Input placeholder="shadcn" v-bind="componentField" />
      </FormControl>
      <FormDescription />
      <FormMessage />
    </FormItem>
  </FormField>
</template>

安装

pnpm dlx shadcn-vue@latest add form

使用指南

创建表单模式

使用 Zod 模式定义表单结构。可在 Zod 文档 中详细了解 Zod 的使用方法。

使用 @vee-validate/zod 将 Zod 模式验证与 vee-validate 集成

toTypedSchema 还会自动为表单值和提交值添加类型，同时适配该模式的输入和输出类型。

<script setup lang="ts">
import { toTypedSchema } from '@vee-validate/zod'
import * as z from 'zod'

const formSchema = toTypedSchema(z.object({
  username: z.string().min(2).max(50),
}))
</script>

定义表单

使用 vee-validate 的 useForm 组合式函数或 <Form /> 组件创建表单。

<script setup lang="ts">
import { useForm } from 'vee-validate'
import { toTypedSchema } from '@vee-validate/zod'
import * as z from 'zod'

import {
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage
} from '@/components/ui/form'

const formSchema = toTypedSchema(z.object({
  username: z.string().min(2).max(50),
}))

const form = useForm({
  validationSchema: formSchema,
})

const onSubmit = form.handleSubmit((values) => {
  console.log('表单已提交!', values)
})
</script>

<template>
  <form @submit="onSubmit">
    ...
  </form>
</template>

构建表单

基于上一步，我们可以使用 <Form /> 组件或 useForm 组合式函数 推荐使用 useForm，因为能自动获得类型化值

<script setup lang="ts>
import { useForm } from 'vee-validate'
import { toTypedSchema } from '@vee-validate/zod'
import * as z from 'zod'

import { Button } from '@/components/ui/button'
import {
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@/components/ui/form'
import { Input } from '@/components/ui/input'

const formSchema = toTypedSchema(z.object({
  username: z.string().min(2).max(50),
}))

const form = useForm({
  validationSchema: formSchema,
})

const onSubmit = form.handleSubmit((values) => {
  console.log('表单已提交!', values)
})
</script>

<template>
  <form @submit="onSubmit">
    <FormField v-slot="{ componentField }" name="username">
      <FormItem>
        <FormLabel>用户名</FormLabel>
        <FormControl>
          <Input type="text" placeholder="shadcn" v-bind="componentField" />
        </FormControl>
        <FormDescription>
          这是您的公开显示名称。
        </FormDescription>
        <FormMessage />
      </FormItem>
    </FormField>
    <Button type="submit">
      提交
    </Button>
  </form>
</template>

完成

大功告成！您现在拥有了一个完全可访问、类型安全且支持客户端验证的表单。

Username

This is your public display name.

示例

查看以下链接，了解如何将 vee-validate 功能与其他组件配合使用的更多示例：

• 复选框
• 日期选择器
• 输入框
• 单选按钮组
• 选择器
• 滑块
• 开关
• 文本区域
• 组合框

附加功能

此示例展示如何使用 Formkit AutoAnimate 为表单添加动效

Username

This is your public display name.