本文介绍如何在 Unform 中不依赖 DOM 查询（如 document.getElementById），而是通过 formRef 安全、高效地在任意位置读取或修改指定字段的值，适用于按钮触发、联动校验、动态初始化等场景。

本文介绍如何在 unform 中不依赖 dom 查询（如 `document.getelementbyid`），而是通过 `formref` 安全、高效地在任意位置读取或修改指定字段的值，适用于按钮触发、联动校验、动态初始化等场景。

在使用 Unform 构建表单时，常见需求之一是在提交前、或响应其他交互（如点击“清除”按钮、“复制到剪贴板”、“自动填充示例值”）时，主动读取或修改某个字段的值。此时，你不应绕过表单状态管理直接操作 DOM，而应利用 Unform 提供的 FormHandles 实例方法——它们专为安全、响应式地访问和更新字段设计。

✅ 正确方式：使用 formRef.current 的内置方法

假设你已在主组件中正确声明了 formRef：

const formRef = useRef<FormHandles>(null);

并在

上绑定该 ref：

<Form ref={formRef} onSubmit={handleSubmit}>
  <TextInputInput name="cpf" placeholder="000.000.000-00" />
  <FormatedTextInput name="password" type="password" />
  <Button type="submit">登录</Button>
</Form>

你即可在任意事件处理函数中调用以下方法：

? 获取单个字段值

const handleGetCpf = () => {
  const cpfValue = formRef.current?.getFieldValue('cpf');
  console.log('当前 CPF 值:', cpfValue); // 如 '123.456.789-00'
};

? 获取全部字段值（等效于提交时的 data）

const handleGetAll = () => {
  const allValues = formRef.current?.getData();
  console.log('全部表单数据:', allValues); // { cpf: '...', password: '...' }
};

? 设置单个字段值（支持触发验证与 UI 更新）

const handleSetCpf = () => {
  formRef.current?.setFieldValue('cpf', '999.999.999-99');
};

? 批量设置多个字段

const handleResetForm = () => {
  formRef.current?.setData({
    cpf: '',
    password: ''
  });
};

⚠️ 注意事项：

• 所有 formRef.current.* 方法均需确保 formRef.current 已挂载（即 已渲染完成）。建议在 useEffect 或事件回调中调用，并添加可选链 ?. 防止空引用错误。
• getFieldValue 和 setFieldValue 会自动触发字段的验证逻辑（若已配置 validationSchema 或 rules），并同步更新视图。
• 自定义输入组件（如 TextInputInput）必须正确实现 useField 注册逻辑（如你已做的那样），否则字段将无法被识别。

? 实际应用示例：带“清空 CPF”功能的登录页

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

  const handleClearCpf = () => {
    formRef.current?.setFieldValue('cpf', '');
  };

  const handleCopyCpf = () => {
    const cpf = formRef.current?.getFieldValue('cpf');
    if (cpf) {
      navigator.clipboard.writeText(cpf);
      alert('CPF 已复制到剪贴板！');
    }
  };

  return (
    <Form ref={formRef} onSubmit={handleSubmit}>
      <TextInputInput name="cpf" placeholder="000.000.000-00" />
      <div style={{ marginTop: '8px' }}>
        <Button type="button" onClick={handleClearCpf}>清空 CPF</Button>
        <Button type="button" onClick={handleCopyCpf} style={{ marginLeft: '8px' }}>
          复制 CPF
        </Button>
      </div>

      <FormatedTextInput name="password" type="password" placeholder="********" />
      <Button type="submit">登录</Button>
    </Form>
  );
};

export default Login;

? 总结

Unform 的 formRef.current 不仅用于提交控制，更是表单状态的统一入口。通过 getFieldValue、setFieldValue 和 getData/setData 等方法，你可以：

• 完全避免 document.getElementById 等脆弱的 DOM 操作；
• 在任意组件层级（包括子组件、工具函数、自定义 Hook）中安全访问字段；
• 实现字段联动、条件重置、实时预览等高级交互。

务必确保自定义输入组件已完成 registerField 注册，且 formRef 已正确传递至

，即可开箱即用地享受响应式表单控制能力。