本文旨在解决Yup版本更新（0.26.6到1.2.0及更高版本）后，`Yup.when` 方法中 `is` 属性不再被支持的问题。我们将详细介绍如何将旧的对象式条件判断转换为新的回调函数式语法，以确保表单验证逻辑的兼容性和正确性，避免在ReactJS等应用中遇到类型错误。
在现代前端开发中，表单验证库如Yup因其强大的功能和简洁的API而广受欢迎。然而，随着库版本的迭代，API有时会发生变化。本文将重点探讨在将Yup从旧版本（例如0.26.6）升级到新版本（例如1.2.0及更高版本）时，Yup.when 方法中 is 属性不再有效的问题，并提供详细的迁移指南和示例，帮助开发者顺利过渡。
旧版 Yup.when 的用法与局限性
在Yup的早期版本中，Yup.when 方法允许开发者根据其他字段的值来动态调整当前字段的验证规则。其中，一种常见的用法是通过 is 属性直接指定一个布尔值或特定值作为条件判断。例如，当某个布尔字段为 true 时，应用一组验证规则：
import * as Yup from 'yup';
// 假设 domainName 是一个已定义的正则表达式
export default Yup.object({
enabled: Yup.boolean(),
hostname: Yup.string().when('enabled', {
is: true, // 旧版语法：直接使用 'is' 属性
then: Yup.string()
.matches(domainName, '请提供一个完全限定域名')
.required('您必须提供一个主机名'),
otherwise: Yup.string().notRequired(),
}),
});然而，当升级到Yup 1.x版本后，上述代码会触发类似 Object literal may only specify known properties, and 'is' does not exist in type 'ConditionBuilder<...>' 的类型错误。这表明 is 属性已被废弃或其用法已发生根本性改变。
新版 Yup.when 的回调函数语法
Yup 1.x版本对 when 方法进行了重大改进，引入了基于回调函数的新语法，提供了更强大的灵活性和更清晰的类型推断。现在，when 方法的第二个参数不再是一个包含 is 属性的对象，而是一个接收回调函数的参数。这个回调函数接收两个参数：
- values (或解构后的 [value]): 一个数组，包含 when 方法所监听的字段的当前值。如果只监听一个字段，通常会解构为 [value]。
- schema: 当前字段的Schema实例，允许你在回调函数内部对其进行链式调用以应用不同的验证规则。
新的语法结构如下：
fieldName: Yup.string().when('watchedFieldName', ([watchedValue], schema) => {
// 根据 watchedValue 的值返回不同的 schema 实例
if (watchedValue === someCondition) {
return schema.required('此字段为必填');
}
return schema.notRequired();
});示例：将布尔条件转换为回调函数
让我们将最初的 hostname 字段的验证逻辑迁移到新语法。原先的 is: true 条件现在需要通过回调函数来判断 enabled 字段的值。
旧版代码 (Yup v0.26.6):
hostname: Yup.string().when('enabled', {
is: true,
then: Yup.string()
.matches(domainName, '请提供一个完全限定域名')
.required('您必须提供一个主机名'),
otherwise: Yup.string().notRequired(),
}),新版代码 (Yup v1.2.0+):
import * as Yup from 'yup';
// 假设 domainName 是一个已定义的正则表达式，例如：
// import helpers from '../../../Shared/validationHelpers';
// const { domainName } = helpers.regEx;
export default Yup.object({
enabled: Yup.boolean(),
hostname: Yup.string().when('enabled', ([enabledValue], schema) => {
return enabledValue // 检查 enabledValue 是否为真
? schema
.matches(domainName, '请提供一个完全限定域名')
.required('您必须提供一个主机名')
: schema.notRequired();
}),
});在这个例子中，([enabledValue], schema) 回调函数会检查 enabledValue 是否为真。如果为真，则返回应用了 matches 和 required 规则的 schema；否则，返回应用了 notRequired 规则的 schema。
示例：处理更复杂的条件判断
新版 when 方法的回调函数不仅能处理简单的布尔条件，还能轻松应对更复杂的逻辑，例如判断一个值是否在某个列表中。
场景： 根据 marital_status（婚姻状况）字段的值，动态决定 companion_name（伴侣姓名）字段是否必填。假设当 marital_status 为 'C', 'D', 'E' 时，companion_name 必填。
import * as Yup from 'yup';
export const userSchema = Yup.object({
marital_status: Yup.string().required('请选择婚姻状况'),
companion_name: Yup.string().when('marital_status', ([maritalStatus], schema) => {
return ['C', 'D', 'E'].includes(maritalStatus) // 检查 maritalStatus 是否在指定列表中
? schema
.trim()
.min(2, '伴侣姓名至少需要2个字符')
.required('伴侣姓名是必填项')
: schema.notRequired();
}),
});此示例清晰展示了如何在回调函数内部利用JavaScript的条件逻辑来构建动态的验证规则。includes 方法用于检查 maritalStatus 是否属于特定集合，从而决定返回何种 schema。
注意事项
在迁移和使用新版 Yup.when 时，请注意以下几点：
- 版本兼容性： 确保您的Yup版本至少为1.x。旧版Yup不识别此新语法。
- 参数解构： 回调函数的第一个参数是一个数组。即使只监听一个字段，也建议使用数组解构 ([value]) 来获取其值，这有助于保持代码风格一致性，并且在未来需要监听多个字段时更易于扩展。
- 返回Schema： 回调函数必须始终返回一个 Yup.Schema 实例。这是关键，因为Yup会使用这个返回的Schema来执行后续的验证。
- 链式调用： 在回调函数内部，您可以对传入的 schema 参数进行链式调用，添加或修改验证规则。
- 多字段监听： 如果 when 方法监听了多个字段（例如 when(['fieldA', 'fieldB'], ...)），回调函数的第一个参数将是一个包含这些字段值的数组，顺序与监听的字段名顺序一致。
总结
Yup库的持续发展带来了API的演进，旨在提供更强大、更灵活的验证机制。Yup.when 方法从对象式 is 属性到回调函数式语法的转变，是其提升功能性和类型安全性的一个重要体现。通过理解并掌握新的回调函数语法，开发者可以更有效地构建复杂的、动态的表单验证逻辑，确保应用在升级后依然稳定可靠。在进行库版本升级时，务必查阅官方文档，了解所有可能影响现有代码的API变更。
