Next.js 中表单处理与校验：React Hook Form 实战

作者：码力无边

---

无论是在注册页面、联系我们、还是在复杂的后台管理系统中，表单都是用户与应用进行数据交互的核心。然而，构建一个优秀的表单体验远非看上去那么简单。我们需要处理：

• 组件状态：管理每个输入框的值。
• 性能问题：避免用户每次按键都触发整个组件树的重新渲染。
• 用户反馈：实时显示错误信息。
• 数据校验：确保用户提交的数据符合我们的业务规则（客户端和服务器端）。
• 提交逻辑：处理异步提交、加载和错误状态。

手动处理这些问题会产生大量冗余、难以维护的 useState 和 useEffect 代码。幸运的是，社区已经为我们提供了成熟的解决方案。其中，React Hook Form 以其卓越的性能和简洁的 API 成为了当下的首选。

本文将指导你如何在 Next.js App Router 项目中，结合使用 React Hook Form 进行表单状态管理，以及使用 Zod 定义数据校验模式，构建一个完整的、生产级别的表单。

为什么选择 React Hook Form？

React Hook Form (RHF) 的核心设计理念是性能优先和非受控组件 (Uncontrolled Components)。

• 极致性能：传统的表单库通常将输入框的值存储在 React state 中，导致每次按键都会触发 re-render。RHF 则将表单状态保留在内部，仅在必要时（如提交、校验失败）才触发 re-render，从而极大地提升了复杂表单的性能。
• 更少的代码：其基于 Hooks 的 API 非常简洁，可以显著减少你编写的模板代码量。
• 易于集成：可以与任何 UI 组件库（如 Material UI, Chakra UI）和数据校验库（如 Zod, Yup）无缝集成。
• 强大的功能：开箱即用地支持动态表单、表单数组、异步校验等高级功能。

结合 Zod 进行模式校验

虽然 RHF 可以进行简单的内置校验，但其真正的威力在于与模式校验库 (schema validation library) 结合使用。Zod 是一个 TypeScript 优先的模式声明和校验库，它因其出色的类型推断和简洁的语法而备受青睐。

使用 Zod，你可以用一种非常直观的方式定义数据的“形状”，并自动获得完整的 TypeScript 类型支持。

实战：构建一个用户注册表单

我们将创建一个包含用户名、邮箱和密码的注册表单，并对输入进行校验。

步骤一：安装依赖

npm install react-hook-form zod @hookform/resolvers

@hookform/resolvers 是一个帮助 RHF 与 Zod 等库集成的适配器。

步骤二：定义校验模式 (Schema)

我们首先使用 Zod 来定义我们的表单数据结构和校验规则。

lib/schemas.ts (创建一个新文件来存放 Zod 模式)

import { z } from 'zod';

export const registerSchema = z.object({
  username: z.string().min(3, '用户名至少需要3个字符').max(20, '用户名不能超过20个字符'),
  email: z.string().email('请输入有效的邮箱地址'),
  password: z.string().min(6, '密码至少需要6个字符'),
  confirmPassword: z.string(),
})
// 使用 refine 来添加跨字段的自定义校验逻辑
.refine((data) => data.password === data.confirmPassword, {
  message: "两次输入的密码不一致",
  path: ["confirmPassword"], // 将错误信息附加到 confirmPassword 字段
});

// 从模式中推断出 TypeScript 类型
export type RegisterFormValues = z.infer<typeof registerSchema>;

步骤三：创建表单组件

现在，我们来创建表单组件。由于表单是交互式的，它必须是一个客户端组件。

components/RegisterForm.tsx

"use client";

import { useForm, SubmitHandler } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { registerSchema, RegisterFormValues } from '@/lib/schemas';
import { useState } from 'react';

export default function RegisterForm() {
  const [isSubmitting, setIsSubmitting] = useState(false);
  const [submitError, setSubmitError] = useState<string | null>(null);

  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<RegisterFormValues>({
    resolver: zodResolver(registerSchema),
  });

  const onSubmit: SubmitHandler<RegisterFormValues> = async (data) => {
    setIsSubmitting(true);
    setSubmitError(null);

    try {
      // 在这里，你可以调用一个 API 路由来处理注册逻辑
      // const response = await fetch('/api/register', { ... });
      console.log('表单数据提交成功:', data);
      alert('注册成功！');
      // 可以在此重置表单: reset();
    } catch (error) {
      console.error('提交失败:', error);
      setSubmitError('注册失败，请稍后再试。');
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)} noValidate>
      <div>
        <label htmlFor="username">用户名</label>
        <input id="username" type="text" {...register('username')} />
        {errors.username && <p style={{ color: 'red' }}>{errors.username.message}</p>}
      </div>
      <div>
        <label htmlFor="email">邮箱</label>
        <input id="email" type="email" {...register('email')} />
        {errors.email && <p style={{ color: 'red' }}>{errors.email.message}</p>}
      </div>
      <div>
        <label htmlFor="password">密码</label>
        <input id="password" type="password" {...register('password')} />
        {errors.password && <p style={{ color: 'red' }}>{errors.password.message}</p>}
      </div>
      <div>
        <label htmlFor="confirmPassword">确认密码</label>
        <input id="confirmPassword" type="password" {...register('confirmPassword')} />
        {errors.confirmPassword && <p style={{ color: 'red' }}>{errors.confirmPassword.message}</p>}
      </div>

      {submitError && <p style={{ color: 'red' }}>{submitError}</p>}
      
      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? '注册中...' : '注册'}
      </button>
    </form>
  );
}

代码解读与核心概念：

1. "use client"：表单组件是交互的核心，必须是客户端组件。
2. useForm<RegisterFormValues>：useForm 是 RHF 的核心 Hook。我们传入了从 Zod 推断出的类型，获得了完整的类型提示和安全。
3. resolver: zodResolver(registerSchema)：这一行代码将我们的 Zod 模式与 RHF 连接起来，RHF 会自动使用 Zod 来校验表单数据。
4. register('fieldName')：register 函数是 RHF 的魔法所在。它会将 name, onChange, onBlur, ref 等必要的 props 注入到输入框中，实现对非受控组件的“注册”。
5. handleSubmit(onSubmit)：handleSubmit 是一个高阶函数。它会先用我们的 Zod 模式对表单数据进行校验。只有在校验通过时，它才会调用我们提供的 onSubmit 回调函数，并将格式化好的数据作为参数传入。如果校验失败，它会自动更新 formState.errors 对象。
6. formState: { errors }：errors 对象包含了所有字段的校验错误信息，我们可以用它来在 UI 中方便地展示错误。
7. noValidate：在 <form> 标签上添加 noValidate 属性可以禁用浏览器内置的 HTML5 校验，让我们完全交给 RHF 和 Zod 来处理。

服务端校验的重要性

客户端校验提供了即时的用户反馈，但它永远不能被信任。恶意用户可以轻易地绕过客户端 JavaScript，直接向你的 API 发送请求。因此，在处理表单提交的 API 路由中，必须进行服务端校验。

幸运的是，因为我们使用了 Zod，这个过程非常简单，我们可以复用同一个 schema！

app/api/register/route.ts

import { NextResponse } from 'next/server';
import { registerSchema } from '@/lib/schemas';

export async function POST(request: Request) {
  try {
    const body = await request.json();
    
    // 在服务端使用 Zod 解析和校验数据
    const validatedData = registerSchema.parse(body);

    // ... 此处是你的数据库操作，创建用户等 ...
    // const { username, email, password } = validatedData;
    // ...

    return NextResponse.json({ message: '用户创建成功' }, { status: 201 });

  } catch (error) {
    // Zod 的 parse 方法在校验失败时会抛出错误
    if (error instanceof z.ZodError) {
      return NextResponse.json({ errors: error.errors }, { status: 400 });
    }
    
    // 处理其他可能的错误
    return NextResponse.json({ message: '服务器内部错误' }, { status: 500 });
  }
}

通过在前后端共享同一个 Zod schema，我们保证了数据一致性，并以极低的成本实现了双端校验。

总结

React Hook Form 和 Zod 的组合，为 Next.js 应用中的表单处理提供了一个现代化、高性能且类型安全的黄金标准。

核心优势回顾：

• 性能：RHF 通过非受控组件模式，最大限度地减少了不必要的重渲染。
• 开发体验：简洁的 Hooks API 和 Zod 直观的模式定义，让代码更清晰、更易维护。
• 类型安全：Zod 自动推断的 TypeScript 类型贯穿了从表单组件到 API 路由的整个流程。
• 代码复用：同一个 Zod schema 可以在客户端和服务端被复用，确保了校验逻辑的一致性。

掌握了这套组合拳，你将能够自信地构建任何复杂的表单，同时为用户提供流畅、可靠的交互体验。

在下一篇文章中，我们将讨论如何为我们的 Next.js 应用编写测试，以确保代码的质量和稳定性。我们将探索使用 Jest 和 React Testing Library 进行单元测试和集成测试的最佳实践。敬请期待！