本文详解如何通过 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 表单的必备技能。