本文详细阐述了 Yup 库从旧版本（如 0.26.x）升级到新版本（如 1.x）后，`when` 方法在条件验证语法上的主要变化。重点解决了旧版中 `is` 属性不再被支持的问题，并提供了使用函数式回调进行条件判断的新方法，帮助开发者顺利迁移并正确实现复杂的表单验证逻辑。
在现代前端开发中，表单验证是不可或缺的一环。Yup 作为一款强大的 JavaScript 模式验证库，因其简洁的 API 和灵活的验证能力，在 React 等框架中广受欢迎。然而，随着 Yup 库的不断迭代更新，其 API 也可能发生变化，这在版本升级时会给开发者带来一些挑战。本文将聚焦于 Yup 从旧版本（如 0.26.x）升级到新版本（如 1.x）后，when 条件验证方法的核心语法变更，特别是旧版中 is 属性不再被支持的问题，并提供相应的解决方案。
旧版 when 语法及问题分析
在 Yup 的早期版本中，when 方法允许开发者根据另一个字段的值来条件性地应用验证规则。其语法通常采用一个对象字面量，其中包含 is、then 和 otherwise 属性，用于定义条件和对应的验证模式。
考虑以下一个典型的旧版 Yup 验证模式，它根据 enabled 字段的布尔值来决定 hostname 字段是否需要验证：
import * as Yup from 'yup'; // 假设 Yup 已导入
// 辅助函数，包含正则表达式定义
const helpers = {
regEx: {
domainName: /^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,6}$/
}
};
const { domainName } = helpers.regEx;
export default Yup.object({
enabled: Yup.boolean(),
hostname: Yup.string().when('enabled', {
is: true, // 旧版语法，判断 enabled 是否为 true
then: Yup.string()
.matches(domainName, '请提供一个完全限定域名')
.required('您必须提供主机名'),
otherwise: Yup.string().notRequired(),
}),
});
当尝试将包含上述代码的项目从 Yup 0.26.x 升级到 1.x 版本时，编译器会抛出以下错误：
No overload matches this call.
Overload 1 of 4, '(keys: string | string[], builder: ConditionBuilder<stringschema anyobject undefined>>): StringSchema<string anyobject undefined>', gave the following error.
Argument of type '{ is: boolean; then: Yup.StringSchema<string yup.anyobject undefined>; otherwise: Yup.StringSchema<string yup.anyobject undefined>; }' is not assignable to parameter of type 'ConditionBuilder<stringschema anyobject undefined>>'.
Object literal may only specify known properties, and 'is' does not exist in type 'ConditionBuilder<stringschema anyobject undefined>>'.</stringschema></stringschema></string></string></string></stringschema>
这个错误信息明确指出，传入 when 方法的第二个参数（一个对象字面量）与期望的类型 ConditionBuilder 不匹配，并且最关键的是，is 属性在 ConditionBuilder 类型中不再存在。这意味着 Yup 1.x 版本已经移除了通过 is 属性来定义条件的方式。
新版 when 语法：函数式回调的引入
在 Yup 1.x 及更高版本中，when 方法变得更加灵活，它不再接受一个包含 is 属性的对象，而是期望一个回调函数作为其第二个参数。这个回调函数负责接收依赖字段的值，并根据这些值返回相应的验证模式。
回调函数的签名通常是 ([dependentValue], schema) => Schema：
你是 TypeScript 项目架构专家，专注于脚手架搭建生产就绪的 Node.js 和前端应用。生成包含现代工具链（pnpm、Vite、Next.js）、类型
- [dependentValue]：一个数组，包含 when 方法第一个参数（依赖字段名）所对应的字段值。如果依赖多个字段，这个数组将包含所有这些字段的值。
- schema：当前正在构建的 Yup 模式实例。这允许你在回调函数内部链式调用 Yup 的验证方法。
这种函数式的方法提供了更大的灵活性，可以实现更复杂的条件逻辑。
实践案例：布尔值条件验证
让我们将前面提到的 hostname 验证逻辑，从旧版语法重构为 Yup 1.x 支持的新版函数式回调语法。
import * as Yup from 'yup';
const helpers = {
regEx: {
domainName: /^(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,6}$/
}
};
const { domainName } = helpers.regEx;
export default Yup.object({
enabled: Yup.boolean(),
hostname: Yup.string().when('enabled', ([enabled], schema) => {
// enabled 是一个数组，因为 'enabled' 是字符串数组的简写形式
// 如果只有一个依赖字段，可以安全地取第一个元素
if (enabled) { // 判断 enabled 字段的值是否为 true (或存在)
return schema
.matches(domainName, '请提供一个完全限定域名')
.required('您必须提供主机名');
}
return schema.notRequired();
}),
});
在这个新的实现中：
- when('enabled', ...)：我们依然指定 enabled 字段作为依赖。
- ([enabled], schema) => { ... }：第二个参数现在是一个箭头函数。
- [enabled] 解构了依赖字段的值。这里 enabled 变量将直接持有 enabled 字段的布尔值。
- schema 是当前 hostname 字段的 Yup.string() 实例。
- 在函数内部，我们使用简单的 if (enabled) 条件判断，然后返回链式调用的 schema，应用所需的验证规则。
实践案例：字符串值条件验证
新版 when 方法的函数式回调对于处理字符串或枚举类型的条件也同样强大。例如，根据 marital_status（婚姻状况）字段的值来决定 companion_name（伴侣姓名）字段是否必填。
假设 marital_status 的值可以是 'C' (已婚), 'D' (同居), 'E' (订婚) 或其他（单身，离异等）。只有当婚姻状况为 'C', 'D', 'E' 时，伴侣姓名才需要填写。
import * as Yup from 'yup';
export const userSchema = Yup.object({
marital_status: Yup.string().required('请选择婚姻状况'),
companion_name: Yup.string().when('marital_status', ([marital_status], schema) => {
// 定义需要伴侣姓名的婚姻状态列表
const requiresCompanionName = ['C', 'D', 'E'];
// 检查当前的 marital_status 是否在列表中
if (requiresCompanionName.includes(marital_status)) {
return schema
.trim() // 移除前后空格
.min(2, '伴侣姓名至少需要2个字符')
.required('请提供伴侣姓名');
}
return schema.notRequired();
}),
// 其他字段...
});
这个例子清晰地展示了如何利用回调函数内的 JavaScript 逻辑来处理更复杂的条件判断，例如使用 Array.prototype.includes() 方法。
注意事项与最佳实践
- 版本兼容性： 始终注意 Yup 的版本。本教程中的新语法适用于 Yup 1.x 及更高版本。如果你的项目仍在使用旧版本，请在升级前仔细阅读官方迁移指南。
- 官方文档： 遇到任何不确定的情况，官方文档永远是最好的参考来源。它会提供最权威、最新的 API 信息。
-
复杂条件： 对于涉及多个依赖字段或更复杂逻辑的条件，函数式回调的优势更加明显。你可以传递一个字段名数组给 when 方法，回调函数将接收一个包含所有这些字段值的数组。
// 示例：依赖两个字段 Yup.string().when(['fieldA', 'fieldB'], ([valueA, valueB], schema) => { if (valueA === 'someValue' && valueB > 10) { return schema.required(); } return schema.notRequired(); }); - 链式调用： 在回调函数内部，务必返回一个 Yup 模式实例。你可以对传入的 schema 参数进行链式调用，添加或修改验证规则。
总结
Yup 1.x 版本对 when 方法的语法更新，从 is 属性的对象字面量转向了函数式回调，这代表了一种更灵活、更强大的条件验证范式。虽然这要求开发者适应新的编码风格，但它也使得处理复杂依赖和动态验证逻辑变得更加直观和可维护。通过理解并掌握这种新的函数式方法，开发者可以更高效地构建健壮且用户友好的表单验证系统。在进行 Yup 版本升级时，务必注意这些语法变化，并根据本文提供的指南进行相应的代码调整。
