本文详解如何通过 formRef 在外部组件或事件中安全、高效地读取或设置 Unform 表单字段值，避免使用 document.getElementById()，并提供可直接复用的代码示例与关键注意事项。
本文详解如何通过 `formref` 在外部组件或事件中安全、高效地读取或设置 unform 表单字段值，避免使用 `document.getelementbyid()`，并提供可直接复用的代码示例与关键注意事项。
在使用 Unform 构建复杂表单时，常需在提交前或交互过程中动态访问特定字段（如 cpf）的当前值——例如点击“校验身份证”按钮时实时获取输入内容，而非等待整个表单提交。此时，不应依赖 DOM 查询（如 document.getElementById），而应充分利用 Unform 提供的 FormHandles 实例方法，实现类型安全、响应式且符合 React 最佳实践的数据访问。
✅ 正确方式：通过 formRef.current 获取字段值
Unform 的 Form 组件暴露了 getFieldValue(fieldName: string) 方法，用于同步读取任意已注册字段的当前值。该方法仅对已通过 useField 注册的字段生效（如你封装的 TextInputInput 组件），且无需额外状态管理或 ref 透传。
以下是在 Login 组件中扩展按钮逻辑的完整示例：
const Login: React.FC = () => {
const formRef = useRef<FormHandles>(null);
const handleSubmit = useCallback(async (data: SignInFormData) => {
console.log('提交数据:', data);
}, []);
// ✅ 点击时获取 cpf 字段值
const handleCheckCPF = () => {
if (!formRef.current) return;
const cpfValue = formRef.current.getFieldValue('cpf');
console.log('当前 CPF 值:', cpfValue); // 如：'123.456.789-00'
// 可在此执行校验、API 请求等逻辑
};
// ✅ 同样支持批量获取全部字段值
const handleLogAllData = () => {
const allData = formRef.current?.getData();
console.log('全部表单数据:', allData);
};
return (
<Form ref={formRef} onSubmit={handleSubmit}>
<TextInputInput
type="text"
id="text"
name="cpf"
placeholder="000.000.000-00"
/>
<FormatedTextInput
type="password"
id="password"
name="password"
placeholder="********"
/>
<Button type="button" onClick={handleCheckCPF}>
校验 CPF
</Button>
<Button type="button" onClick={handleLogAllData}>
查看全部数据
</Button>
<Button type="submit">登录</Button>
</Form>
);
};
export default Login;⚠️ 关键注意事项
- formRef.current 可能为 null：务必在调用 getFieldValue 或 getData 前进行空值检查（如 if (!formRef.current) return;），尤其在异步或条件渲染场景下。
-
字段名必须严格匹配：getFieldValue('cpf') 中的 'cpf' 必须与
中的 name 属性完全一致（包括大小写和空格）。 - 仅适用于已注册字段：确保自定义输入组件（如 TextInputInput）正确调用了 registerField，且 ref 已绑定到真实 DOM 元素（你的代码中已满足此条件）。
- 不支持设置值？请用 setFieldValue：若需修改某字段值（如清空密码、填充默认 CPF），请使用 formRef.current.setFieldValue('cpf', 'new-value') —— 同样类型安全且触发表单重渲染。
- 性能友好：getFieldValue 是同步轻量操作，无额外渲染开销，适合高频交互场景（如实时搜索、联动筛选）。
? 总结
Unform 的 formRef 不仅服务于表单提交，更是跨组件控制与查询字段的核心枢纽。通过 getFieldValue 和 getData，你可以在任意时机、任意位置（只要持有 formRef）精准获取所需数据；配合 setFieldValue，还能实现动态赋值与状态同步。这既规避了反模式的 DOM 操作，又保持了组件的封装性与可测试性——是构建专业级 React 表单的必备技能。
