本文详解 React + TypeScript 项目中使用 react-hook-form 时表单提交后 data 对象属性全为 undefined 的根本原因与修复方法，重点在于 name 属性缺失导致字段未被正确注册。
本文详解 react + typescript 项目中使用 react-hook-form 时表单提交后 `data` 对象属性全为 `undefined` 的根本原因与修复方法，重点在于 `name` 属性缺失导致字段未被正确注册。
在使用 react-hook-form 构建表单时，一个常见但极易被忽视的问题是：即使调用了 register()，若 <Input>（或其他受控输入组件）缺少 name 属性，该字段将不会被纳入表单数据结构中。这直接导致 handleSubmit 回调接收的 data 对象中对应字段值为 undefined，无论用户是否已输入内容。
? 核心原因：name 是 react-hook-form 的注册契约
useForm() 的 register() 函数不仅返回事件处理器（如 onChange, onBlur），更关键的是——它依赖 name 字符串作为字段唯一标识符，用于：
- 在内部注册该字段；
- 将用户输入值映射到最终 data 对象的对应键；
- 触发验证、重置、脏检查等行为。
因此，仅展开 register('customerNameFilterText') 是不够的，必须确保 DOM 元素显式声明 name="customerNameFilterText"。否则，react-hook-form 无法建立“输入元素 ↔ 数据字段”的绑定关系。
完整的Galileo AI平台 TypeScript/JS SDK 参考，用于评估、观察和保护 GenAI 应用。适用于构建 Node.js 或 TypeScript 项目。
✅ 正确写法（关键修复）
<Input
{...register('customerNameFilterText')}
name="customerNameFilterText" // ← 必须显式添加！
className="form-control"
placeholder="Search by Customer Name"
type="text"
/>? 提示：register() 返回的对象中已包含 name 属性（即 register('xxx') 自动注入 name="xxx"），但 当使用第三方 UI 库（如 reactstrap 的 <Input>）时，其底层可能未自动透传该 name 值。此时必须手动补全，这是最常被忽略的实践细节。
? 完整可运行示例（含类型安全）
import { useForm } from 'react-hook-form';
interface FiltersProps {
customerNameFilterText: string;
// 其他字段...
}
const FilterModal = () => {
const {
register,
handleSubmit,
formState: { errors }
} = useForm<FiltersProps>();
const set_filter = (data: FiltersProps) => {
console.log('✅ 提交数据:', data); // 现在将正确输出 { customerNameFilterText: "xxx" }
collectionsCustomersFilterToggle();
applyFilter(data);
};
return (
<Modal isOpen={filterModal} toggle={collectionsCustomersFilterToggle} centered>
<ModalHeader>Filter Customers by</ModalHeader>
<ModalBody>
<form onSubmit={handleSubmit(set_filter)}>
<FormGroup row className="pb-2">
<Label for="customerNameFilterText" sm={4}>
Customer Name
</Label>
<Col sm={8}>
<Input
{...register('customerNameFilterText', {
required: 'Customer name is required'
})}
name="customerNameFilterText" // ← 强制显式声明（兼容性保障）
className="form-control"
placeholder="Search by Customer Name"
type="text"
/>
{errors.customerNameFilterText && (
<small className="text-danger">{errors.customerNameFilterText.message}</small>
)}
</Col>
</FormGroup>
<FormGroup check row>
<Row>
<Col sm={4}>
<Button className="view btn-secondary" type="button" onClick={() => reset()}>
Clear Filters
</Button>
</Col>
<Col sm={4}></Col>
<Col sm={4}>
<Button className="btn-primary" type="submit">
Apply Filters
</Button>
</Col>
</Row>
</FormGroup>
</form>
</ModalBody>
</Modal>
);
};⚠️ 注意事项与最佳实践
- 不要依赖 ref 或 value 手动取值：react-hook-form 的设计哲学是“声明式注册”，绕过 register 直接操作 DOM 会破坏数据同步。
- 清除过滤器建议用 reset()：如上例所示，reset() 可一键清空所有字段并重置状态，比手动设空更可靠。
- TypeScript 类型需严格对齐：确保 useForm<T> 的泛型 T 与 handleSubmit 回调参数类型一致，避免隐式 any 导致类型丢失。
- 调试技巧：在 handleSubmit 中打印 console.log(getValues()) 可实时查看当前所有注册字段的值，快速定位未注册字段。
通过补全 name 属性，你将彻底解决表单提交后数据为空的问题——这看似微小，却是 react-hook-form 正常工作的基石。
