如何在 Unform 中跨组件获取或设置表单字段值

• 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 字段值并写入剪贴板：

ExcelFormulaBot

在AI帮助下将文本指令转换为Excel函数公式

下载

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，可显著提升复杂表单的可维护性与交互体验。