React MUI多复选框选中后react-hook-form提交数据不同步问题

核心原因 #

复选框视觉更新但表单值不同步，本质是状态双数据源不一致：单独维护了复选框的本地checked状态控制UI，但变更事件没有同步到react-hook-form（以下简称RHF）的内部状态，提交时RHF读的始终是自己初始化时存的默认false值。

正确实现代码 #

直接用RHF管理所有复选框状态，不要额外写useState存勾选值，参考如下AccountInformations组件写法：

import { useForm } from 'react-hook-form';
import { Checkbox, FormControlLabel, FormGroup, Button } from '@mui/material';
import { useEffect } from 'react';

const AccountInformations = ({ userSettings }) => {
  // 表单初始化，默认值直接取父组件传入的配置
  const { 
    register, 
    handleSubmit, 
    reset,
    formState: { isSubmitting } 
  } = useForm({
    defaultValues: {
      emailNotice: false,
      smsNotice: false,
      marketingPush: false,
      // 按你实际的userSettings字段补全，字段名必须和后端要求的参数名一致
      ...userSettings
    }
  });

  // 如果userSettings是父组件异步拉取的，数据返回后同步重置表单值
  useEffect(() => {
    if (userSettings) reset(userSettings);
  }, [userSettings, reset]);

  // 提交逻辑
  const submitHandler = async (formData) => {
    console.log('正确同步的复选框值：', formData);
    // 此处直接写POST请求逻辑即可，formData里的布尔值和页面勾选状态完全一致
    await fetch('/api/user/settings', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(formData)
    });
  };

  return (
    <form onSubmit={handleSubmit(submitHandler)}>
      <FormGroup>
        <FormControlLabel
          control={<Checkbox {...register('emailNotice')} />}
          label="接收邮件通知"
        />
        <FormControlLabel
          control={<Checkbox {...register('smsNotice')} />}
          label="接收短信通知"
        />
        <FormControlLabel
          control={<Checkbox {...register('marketingPush')} />}
          label="接收营销推送"
        />
      </FormGroup>
      <Button 
        type="submit" 
        variant="contained" 
        loading={isSubmitting}
      >
        保存设置
      </Button>
    </form>
  );
};

export default AccountInformations;

如果你需要用Controller做自定义逻辑（比如字段校验、联动逻辑），复选框部分按如下写法即可，核心是不要覆盖RHF提供的onChange和value绑定：

import { Controller } from 'react-hook-form';

// 替换FormGroup内对应表单项
<Controller
  name="emailNotice"
  // 注意control需要从useForm的返回值里解构拿到
  control={control}
  rules={{ required: false }}
  render={({ field }) => (
    <FormControlLabel
      control={
        <Checkbox
          checked={field.value}
          onChange={field.onChange}
        />
      }
      label="接收邮件通知"
    />
  )}
/>

排查避坑点 #

• 删掉所有单独维护复选框checked状态的useState、自定义onChange逻辑，所有表单状态统一交给RHF管理，从根源避免双数据源不同步
• 注册字段时register/Controller的name字段必须和defaultValues里的字段名完全一致，嵌套字段注意路径写法
• 不要给MUI Checkbox硬编码value属性，复选框的选中状态完全靠checked对应的布尔值判定，硬编码固定value会导致RHF取值类型错误
• 提交逻辑必须包裹在handleSubmit里执行，不要自己给按钮绑onClick调用getValues取值，避免状态未完成同步时就拿到旧值
• 初始配置如果是异步接口返回的，必须在数据拿到后调用RHF的reset方法更新表单默认值，不要直接修改本地state

内容的提问来源于stack exchange，提问作者Yohav Rn