本文详解如何在 React Hook Form 中结合 Yup 实现“输入值必须属于指定字符串数组”的自定义校验逻辑，通过 yup.string().test() 方法灵活验证用户输入是否匹配白名单。
本文详解如何在 react hook form 中结合 yup 实现“输入值必须属于指定字符串数组”的自定义校验逻辑，通过 `yup.string().test()` 方法灵活验证用户输入是否匹配白名单。
在表单验证场景中，除了基础的必填、格式、长度校验外，常需判断用户输入是否属于服务端或前端预置的合法值集合（如用户名白名单、角色枚举、地区代码等）。Yup 提供了 .test() 方法，允许你插入任意同步校验逻辑，完美支持此类“存在性校验”。
以你的示例为例，目标是：当用户在 firstname 输入框中填写姓名时，仅当该姓名存在于 ['John', 'Paul', 'Mike', 'Adam'] 数组中才视为有效，否则显示自定义错误提示。
实现方式非常简洁——只需在 Yup Schema 中为 firstname 字段链式调用 .test()，传入校验配置对象：
const names = ['John', 'Paul', 'Mike', 'Adam'];
const schema = yup.object().shape({
firstname: yup
.string()
.required('First Name Required')
.test({
name: 'in-names-array', // 可选：唯一标识符，便于调试
message: 'must be in names array!', // 校验失败时显示的错误消息
test: (value) => typeof value === 'string' && names.includes(value),
}),
});
⚠️ 注意事项：
- 类型安全：value 可能为 undefined 或 null（尤其在字段为空时），因此建议在 test 回调中先做类型判断（如 typeof value === 'string'），避免 includes 报错；
- 大小写敏感：Array.prototype.includes() 默认区分大小写。若需忽略大小写，可改用 names.map(n => n.toLowerCase()).includes(value.toLowerCase())；
-
性能考量：对于静态小数组（如本例），includes 效率足够；若数组极大或需频繁查询，建议提前构建 Set
提升查找复杂度至 O(1)： const validNamesSet = new Set(names); // 定义在 schema 外部 // … 在 test 中使用：validNamesSet.has(value)
- 错误优先级：.required() 和 .test() 的执行顺序遵循链式调用顺序。建议将 .required() 放在前面，确保空值先被拦截，避免对 undefined 执行 includes。
完整整合后，你的 useForm 配置无需任何修改，React Hook Form 会自动触发并展示该自定义校验结果。用户输入 "Tom" 将触发 'must be in names array!' 错误；输入 "John" 则顺利通过。
总结：Yup 的 .test() 是处理业务特定约束的利器。它不破坏原有 Schema 声明式风格，又赋予你完全的 JavaScript 控制力——无论是数组校验、异步远程查重，还是复合规则判断，都能优雅落地。
