React Hook Form复选框数据结构异常问题排查及修复方案

问题现象 #

• 点击复选框本身时，选中功能正常，数据格式符合预期
• 点击复选框间隙区域时，已选中的复选框会全部取消，日志中出现异常数据结构
• 仅渲染单个复选框时，React Hook Form 会将原本的数组项转为布尔值，导致后端收到不符合要求的数据

根因分析 #

问题核心在于 CheckboxListItem 组件的 ref 属性使用 register 函数时，未传入指定的 name 作为第一个参数，导致复选框无法正确绑定表单字段值，在不同交互场景（点击间隙、单复选框渲染）下出现不一致的异常表现。

修复方案 #

方案一：为 register 函数添加 name 参数 #

调用 register 时显式传入对应字段的 name，确保复选框与表单字段正确绑定：

// 示例代码
<CheckboxListItem
  key={product.id}
  label={product.name}
  ref={register({ name: 'selectedProducts' })} // 显式传入name参数
  value={product.id}
/>

此方法可让 React Hook Form 正确识别数组类型字段，无论点击复选框本身还是间隙，都能维持正确的选中状态和数据格式。

方案二：为每个复选框设置独立名称（name + index） #

通过 name + index 的命名规则给每个复选框分配唯一名称，确保单个或多个复选框场景下数据结构一致：

// 示例代码
products.map((product, index) => (
  <CheckboxListItem
    key={product.id}
    label={product.name}
    ref={register({ name: `selectedProducts[${index}]` })} // 用索引生成唯一name
    value={product.id}
  />
))

这种方式会生成结构化的数组数据，避免单复选框时被转为布尔值的问题，同时保证点击间隙时不会触发全选取消的异常。

内容的提问来源于stack exchange，提问作者Mohsen Khadem Hoseini