理解 react-hook-form 的 handleSubmit 机制

在使用 react-hook-form 构建表单时，开发者常遇到的一个问题是，尽管尝试了各种方法（如手动调用 event.preventDefault()），表单提交后页面依然会刷新，导致表单数据暴露在URL中，并且后端请求及前端验证（如Yup）也无法正常工作。这通常源于对 react-hook-form 提供的 handleSubmit 函数的误用。

react-hook-form 的 handleSubmit 是一个高阶函数，它的主要作用是接收一个自定义的表单提交逻辑函数作为参数，并返回一个新的事件处理函数。这个返回的事件处理函数在被调用时，会执行以下关键步骤：

1. 阻止默认行为： 自动调用 event.preventDefault()，阻止浏览器默认的表单提交行为（即页面刷新和数据编码到URL）。
2. 触发验证： 在执行自定义提交逻辑之前，根据配置的验证规则（如Yup resolver）对表单数据进行验证。
3. 执行提交逻辑： 如果验证通过，则调用传入的自定义提交逻辑函数，并将验证后的表单数据作为参数传递。

常见错误：将 handleSubmit 包装在箭头函数中

许多开发者可能会尝试以下方式来绑定表单的 onSubmit 事件：

<form onSubmit={() => handleSubmit(onSubmit)}>
  {/* ... 表单字段 ... */}
</form>

这种写法是导致页面刷新的主要原因。当 React 渲染组件时，onSubmit={() => handleSubmit(onSubmit)} 这段代码会被执行。这意味着 handleSubmit(onSubmit) 会被立即调用，并将其返回值（一个事件处理函数）包装在一个新的匿名箭头函数 () => ... 中。

问题在于，当表单实际提交时，React 调用的并不是 handleSubmit 返回的那个能够阻止默认行为的函数，而是这个外部的匿名箭头函数。这个匿名箭头函数在执行时，仅仅是再次调用了 handleSubmit 返回的函数，但此时它并没有接收到原生的 SyntheticEvent 对象。由于没有 event 对象，handleSubmit 内部的 event.preventDefault() 也就无法被执行，导致浏览器执行了默认的表单提交行为，从而引发页面刷新。

正确姿势：直接传递 handleSubmit 的返回值

要正确地阻止页面刷新并确保 react-hook-form 的验证机制正常工作，应该将 handleSubmit 的返回值直接赋给

字节跳动旗下的免费AI编程工具

<form onSubmit={handleSubmit(onSubmit)}>
  {/* ... 表单字段 ... */}
</form>

在这种写法中，handleSubmit(onSubmit) 会在组件渲染时被调用一次，它会返回一个已经“准备好”的事件处理函数。React 会将这个返回的函数作为

示例代码：修正后的表单提交

以下是一个修正后的 react-hook-form 示例，展示了如何正确地配置表单提交：

import React from 'react';
import { useForm, type SubmitHandler } from 'react-hook-form';
import { yupResolver } from '@hookform/resolvers/yup';
import * as yup from 'yup';
import { useAppDispatch } from 'redux/hooks';
import { s*eEmail } from 'redux/reducers/usersSlice';
import { useSessionMutation } from 'shared/httpService';

// 假设 IFormData 和 useSessionMutation 等已定义
interface IFormData {
  email: string;
  password: string;
}

const schema = yup
  .object({
    email: yup.string().email('请输入有效的邮箱地址').required('邮箱不能为空'),
    password: yup.string().min(8, '密码至少8位').max(16, '密码最多16位').required('密码不能为空'),
  })
  .required();

const Session = (): JSX.Element => {
  const dispatch = useAppDispatch();
  const [session] = useSessionMutation();

  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<IFormData>({
    resolver: yupResolver(schema),
    // 默认值可以在这里设置，或者在 input 元素上使用 defaultValue
    defaultValues: {
      email: '',
      password: ''
    }
  });

  // onSubmit 函数不需要手动接收 event 参数，react-hook-form 会处理
  const onSubmit: SubmitHandler<IFormData> = async (data) => {
    // 注意：这里不再需要 event 参数，也不需要手动调用 event.preventDefault()
    try {
      await session(data).unwrap();
      dispatch(s*eEmail(data.email));
      console.log('Form submitted successfully:', data);
    } catch (error) {
      console.error('Submission error:', error);
    }
  };

  return (
    // 关键修正：直接传递 handleSubmit(onSubmit)
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label htmlFor="email">邮箱:</label>
        <input id="email" type="email" {...register('email')} placeholder="请输入邮箱" />
        {errors.email && <span>{errors.email.message}</span>}
      </div>

      <div>
        <label htmlFor="password">密码:</label>
        <input id="password" type="password" {...register('password')} placeholder="请输入密码" />
        {errors.password && <span>{errors.password.message}</span>}
      </div>

      <button type="submit">提交</button>
    </form>
  );
};

export default Session;

在上述代码中，onSubmit={handleSubmit(onSubmit)} 是解决问题的核心。它确保了 react-hook-form 能够完全接管表单的提交流程，包括阻止默认行为、执行验证以及调用您的自定义提交逻辑。同时，自定义的 onSubmit 函数也不再需要手动处理 event 对象。

注意事项与最佳实践

• event.preventDefault() 是内置的： 记住 handleSubmit 已经内部处理了 event.preventDefault()，因此您的自定义提交逻辑中无需再次调用。
• Yup 验证集成： 确保 yupResolver 正确配置，并且 Yup schema 定义清晰，这样 formState.errors 才能捕获并显示验证消息。
• 错误消息显示： 利用 formState.errors 对象来显示与特定字段关联的验证错误信息，例如 errors.email?.message。
• 可访问性： 考虑为表单元素添加 label 标签和 htmlFor 属性，以提高表单的可访问性。
• 提交按钮类型： 确保提交按钮的 type 属性设置为 submit。

总结

正确使用 react-hook-form 的 handleSubmit 函数是构建高效、无刷新且验证功能完善的 React 表单的关键。通过将 handleSubmit(yourCustomSubmitFunction) 直接传递给