Valibot 表单验证：处理可选邮箱字段的最佳实践

在表单开发中，邮箱验证是一个常见但容易出错的功能点。特别是当我们需要处理可选邮箱字段时，如何正确设置验证规则就显得尤为重要。本文将以 Valibot 库为例，深入探讨如何优雅地处理表单中的可选邮箱字段验证。

问题背景

开发者在使用 Valibot 进行表单验证时，经常会遇到这样的场景：表单中包含必填和可选的邮箱字段。对于必填字段，我们通常会使用 v.pipe(v.string(), v.nonEmpty(), v.email()) 这样的验证链。但对于可选字段，开发者可能会尝试使用 v.nullish 验证器，期望当字段为空时不进行验证。

然而，实际使用中发现，当用户清空可选邮箱字段后，系统仍然会显示 "Invalid email" 的错误提示，这与预期行为不符。

解决方案分析

Valibot 的维护者提供了一个更优的解决方案：使用 v.union 结合 v.literal('') 来处理这种情况。这种方法的优势在于：

1. 明确区分空字符串和有效邮箱两种状态
2. 符合表单验证的常见需求模式
3. 代码可读性强，意图明确

具体实现如下：

const Schema = v.object({
  email_work: v.pipe(v.string(), v.email()), // 必填邮箱
  email_home: v.union([v.literal(''), v.pipe(v.string(), v.email())]), // 可选邮箱
});

技术原理

这种解决方案之所以有效，是因为它利用了 Valibot 的联合类型验证器 v.union，该验证器会依次尝试列表中的每个验证器，直到有一个验证通过为止。

1. 首先尝试 v.literal('') 验证空字符串
2. 如果字段不为空，则尝试邮箱格式验证
3. 只有当两者都失败时才会报错

这种方式比使用 v.nullish 更精确，因为：

• 表单字段提交时，空值通常表示为空字符串而非 null/undefined
• 明确表达了"允许空字符串或有效邮箱"的业务需求

最佳实践建议

基于这个案例，我们可以总结出一些 Valibot 表单验证的最佳实践：

1. 对于必填字段，使用完整的验证链：

   v.pipe(v.string(), v.nonEmpty(), v.email())
   

2. 对于可选字段，优先考虑使用 v.union 组合验证：

   v.union([v.literal(''), v.pipe(v.string(), v.email())])
   

3. 明确区分 null/undefined 和空字符串的场景：

   • 使用 v.nullish 处理真正的 null/undefined 值
   • 使用 v.literal('') 处理空字符串

4. 考虑添加自定义错误信息提升用户体验：

   v.union([
     v.literal(''), 
     v.pipe(v.string(), v.email('请输入有效的邮箱地址'))
   ])
   

总结

Valibot 提供了灵活而强大的验证组合方式，理解各种验证器的适用场景对于构建健壮的表单验证逻辑至关重要。通过合理使用 v.union 和 v.literal，我们可以精确控制可选字段的验证行为，既保证了数据质量，又提供了良好的用户体验。