本文详解如何通过 formRef 在外部组件或事件中安全、高效地读取或修改 Unform 表单字段值，避免使用 document.getElementById()，支持实时获取单个字段（如 getFieldValue('cpf')）或全部数据（getData()），并附完整用法示例与关键注意事项。

本文详解如何通过 `formref` 在外部组件或事件中安全、高效地读取或修改 unform 表单字段值，避免使用 `document.getelementbyid()`，支持实时获取单个字段（如 `getfieldvalue('cpf')`）或全部数据（`getdata()`），并附完整用法示例与关键注意事项。

在基于 Unform 构建的 React 表单中，常需在提交前、联动交互或条件校验等场景下，从非提交按钮的其他操作（如“自动填充”“清空字段”“校验手机号格式”等）中动态读取或设置某个字段的值。此时，直接操作 DOM（如 document.getElementById()）不仅违背 React 的数据流原则，还易导致 ref 失效、类型不安全及 SSR 兼容性问题。

Unform 提供了官方推荐的响应式 API：通过绑定到

的 ref，可直接调用实例方法安全访问字段状态。核心方法如下：

• formRef.current.getFieldValue(fieldName: string)：获取指定字段当前值（返回 any 类型，建议配合 TypeScript 接口约束）；
• formRef.current.setData(data: Partial)：批量设置字段值（仅更新传入的键）；
• formRef.current.getData()：获取整个表单当前快照（包含所有已注册字段的值）；
• formRef.current.setFieldValue(fieldName: string, value: any)：精确设置单个字段值（触发重渲染与验证）。

以下为实际应用示例——在 Login 组件中新增一个「一键复制 CPF」按钮，点击时读取 cpf 字段值并写入剪贴板：

const Login: React.FC = () => {
  const formRef = useRef<FormHandles>(null);

  const handleSubmit = useCallback(async (data: SignInFormData) => {
    console.log('表单提交数据:', data);
  }, []);

  // ✅ 安全获取字段值：无需 ref 透传，不依赖 DOM
  const handleCopyCPF = () => {
    if (!formRef.current) return;

    const cpfValue = formRef.current.getFieldValue('cpf');
    if (cpfValue && typeof cpfValue === 'string') {
      navigator.clipboard.writeText(cpfValue)
        .then(() => console.log('CPF 已复制'))
        .catch(err => console.error('复制失败:', err));
    }
  };

  // ✅ 安全设置字段值：例如点击后自动补全默认密码
  const handleSetDefaultPassword = () => {
    if (formRef.current) {
      formRef.current.setFieldValue('password', '12345678');
    }
  };

  return (
    <Form ref={formRef} onSubmit={handleSubmit}>
      <TextInputInput 
        type="text" 
        id="cpf" 
        name="cpf"
        placeholder="000.000.000-00" 
      />

      <FormatedTextInput 
        type="password" 
        id="password"
        name="password"
        placeholder="********"
      />

      {/* 非提交按钮，用于字段交互 */}
      <Button type="button" onClick={handleCopyCPF}>
        复制 CPF
      </Button>
      <Button type="button" onClick={handleSetDefaultPassword}>
        设置默认密码
      </Button>

      <Button type="submit">登录</Button>
    </Form>
  );
};

export default Login;

⚠️ 关键注意事项：

• formRef.current 在组件首次挂载前为 null，务必在调用前做存在性判断（如 if (!formRef.current) return;）；
• getFieldValue 返回值类型取决于字段初始值与用户输入，建议在 TypeScript 中为 SignInFormData 显式定义字段类型，提升类型安全性；
• setFieldValue 和 setData 会触发表单重渲染及关联验证规则（如 yup schema），适合用于受控联动逻辑；
• 若需监听字段变化（如实时搜索），应优先使用 useField 的 meta 或 input 属性，而非轮询 getFieldValue；
• 所有方法均要求字段已通过 registerField 正确注册（如你 TextInputInput 中的实现），未注册字段将返回 undefined。

综上，formRef.current.getFieldValue() 与 setFieldValue() 是 Unform 跨组件通信的标准方案，既保持了组件封装性，又提供了灵活可控的数据访问能力。合理运用这些 API，可显著提升复杂表单的可维护性与交互体验。