89.1k

React Hook Form

上一页下一页

使用 React Hook Form 和 Zod 构建表单。

文档

表单很棘手。它们是您在 Web 应用程序中最常构建的东西之一，但也是最复杂的东西之一。

设计良好的 HTML 表单应具备以下特点：

  • 结构良好，语义正确。
  • 易于使用和导航（键盘）。
  • 具有 ARIA 属性和正确标签，可访问性良好。
  • 支持客户端和服务器端验证。
  • 样式良好，与应用程序的其余部分保持一致。

在本指南中，我们将探讨如何使用 react-hook-form 和 zod 构建表单。我们将使用 <FormField> 组件，结合 Radix UI 组件来构建可访问的表单。

功能

<Form /> 组件是 react-hook-form 库的包装器。它提供了以下功能：

  • 用于构建表单的可组合组件。
  • 用于构建受控表单字段的 <FormField /> 组件。
  • 使用 zod 进行表单验证。
  • 处理可访问性和错误消息。
  • 使用 React.useId() 生成唯一ID。
  • 根据状态为表单字段应用正确的 aria 属性。
  • 旨在与所有 Radix UI 组件配合使用。
  • 使用您自己的模式库。我们使用 zod，但您可以使用任何您想要的库。
  • 您可以完全控制标记和样式。

解剖

<Form>
  <FormField
    control={...}
    name="..."
    render={() => (
      <FormItem>
        <FormLabel />
        <FormControl>
          { /* Your form field */}
        </FormControl>
        <FormDescription />
        <FormMessage />
      </FormItem>
    )}
  />
</Form>

示例

const form = useForm()
 
<FormField
  control={form.control}
  name="username"
  render={({ field }) => (
    <FormItem>
      <FormLabel>Username</FormLabel>
      <FormControl>
        <Input placeholder="shadcn" {...field} />
      </FormControl>
      <FormDescription>This is your public display name.</FormDescription>
      <FormMessage />
    </FormItem>
  )}
/>

安装

命令

pnpm dlx shadcn@latest add form

用法

创建表单模式

使用 Zod 模式定义表单的结构。您可以在 Zod 文档中阅读有关使用 Zod 的更多信息。

components/example-form.tsx
"use client"
 
import { z } from "zod"
 
const formSchema = z.object({
  username: z.string().min(2).max(50),
})

定义表单

使用 react-hook-form 的 useForm Hook 来创建表单。

components/example-form.tsx
"use client"
 
import { zodResolver } from "@hookform/resolvers/zod"
import { useForm } from "react-hook-form"
import { z } from "zod"
 
const formSchema = z.object({
  username: z.string().min(2, {
    message: "Username must be at least 2 characters.",
  }),
})
 
export function ProfileForm() {
  // 1. Define your form.
  const form = useForm<z.infer<typeof formSchema>>({
    resolver: zodResolver(formSchema),
    defaultValues: {
      username: "",
    },
  })
 
  // 2. Define a submit handler.
  function onSubmit(values: z.infer<typeof formSchema>) {
    // Do something with the form values.
    // ✅ This will be type-safe and validated.
    console.log(values)
  }
}

由于 FormField 使用的是受控组件，您需要为字段提供一个默认值。请参阅 React Hook Form 文档以了解更多关于受控组件的信息。

构建您的表单

我们现在可以使用 <Form /> 组件来构建我们的表单。

components/example-form.tsx
"use client"
 
import { zodResolver } from "@hookform/resolvers/zod"
import { useForm } from "react-hook-form"
import { z } from "zod"
 
import { Button } from "@/components/ui/button"
import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "@/components/ui/form"
import { Input } from "@/components/ui/input"
 
const formSchema = z.object({
  username: z.string().min(2, {
    message: "Username must be at least 2 characters.",
  }),
})
 
export function ProfileForm() {
  // ...
 
  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-8">
        <FormField
          control={form.control}
          name="username"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Username</FormLabel>
              <FormControl>
                <Input placeholder="shadcn" {...field} />
              </FormControl>
              <FormDescription>
                This is your public display name.
              </FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  )
}

完成

就是这样。您现在拥有一个完全可访问的表单，它具有类型安全和客户端验证功能。

示例

请参阅以下链接，了解更多关于如何将 <Form /> 组件与其他组件一起使用的示例

下拉菜单悬停卡片