YUP/react-hook-form如何实现带防抖且支持动态消息的异步校验

核心思路 #

把防抖逻辑内嵌到Yup的异步test校验中，直接将API返回的错误信息作为校验失败的抛出内容，同时处理防抖的竞态问题，避免用户连续输入时的旧请求干扰。

具体实现步骤 #

• 第一步：实现可取消的防抖工具函数
  普通防抖无法处理输入更新后取消旧的待执行请求的场景，所以需要封装带cancel方法的防抖函数：

// 可取消的防抖函数
const debounce = (func, wait) => {
  let timeout;
  const debounced = (...args) => {
    return new Promise((resolve) => {
      if (timeout) clearTimeout(timeout);
      timeout = setTimeout(() => resolve(func(...args)), wait);
    });
  };
  debounced.cancel = () => clearTimeout(timeout);
  return debounced;
};

• 第二步：封装带防抖的校验请求方法
  把调用校验API的逻辑用上述防抖函数包装，直接返回API给出的错误提示或者成功状态：

// 封装防抖的校验请求，防抖时长可根据业务调整，示例为300ms
const debouncedCheckField = debounce(async (fieldValue) => {
  try {
    // 替换为实际的业务校验API请求
    const res = await fetch('/api/validate-field', {
      method: 'POST',
      body: JSON.stringify({ value: fieldValue })
    });
    const data = await res.json();
    if (!data.valid) {
      // 直接返回API返回的错误提示
      return data.errorMsg;
    }
    return null;
  } catch (err) {
    return '校验请求失败，请稍后重试';
  }
}, 300);

• 第三步：在Yup校验Schema中配置异步校验
  使用Yup的test方法编写异步校验，每次触发新校验前先取消上一次未执行的防抖请求避免竞态，拿到错误信息后直接抛出：

import * as Yup from 'yup';

const validationSchema = Yup.object({
  // 替换为实际需要校验的字段名，示例为username
  username: Yup.string()
    .required('用户名不能为空')
    .test(
      'async-validate',
      // 此处默认提示会被API返回的动态内容覆盖，可随便填写
      '校验失败',
      async (value) => {
        // 空值已由前面的required规则处理，无需走异步校验
        if (!value) return true;
        // 先取消上一次未执行的防抖请求
        debouncedCheckField.cancel?.();
        const errorMsg = await debouncedCheckField(value);
        if (errorMsg) {
          // 直接抛出API返回的错误信息作为动态提示
          throw new Yup.ValidationError(errorMsg);
        }
        return true;
      }
    )
});

• 第四步：Formik正常接入校验Schema即可，无需额外修改配置

import { Formik, Form, Field } from 'formik';

const MyForm = () => {
  return (
    <Formik
      initialValues={{ username: '' }}
      validationSchema={validationSchema}
      onSubmit={(values) => console.log(values)}
    >
      {({ errors, touched }) => (
        <Form>
          <Field name="username" />
          {touched.username && errors.username && <div>{errors.username}</div>}
          <button type="submit">提交</button>
        </Form>
      )}
    </Formik>
  );
};

注意事项 #

• 防抖时长可根据业务需求调整，一般300-500ms即可避免大部分频繁输入触发的无效请求
• 如果使用axios作为请求工具，可额外给校验请求添加取消令牌，进一步取消已经发出的旧请求，优化性能
• 表单提交时如果需要强制校验，可在提交逻辑中主动调用一次校验接口，避免防抖未触发的边界情况

内容的提问来源于stack exchange，提问作者Daher