TanStack表单验证优化：实现单错误优先展示机制

背景介绍

在表单验证过程中，开发者经常会遇到一个常见问题：当用户输入不满足多个验证条件时，系统会同时显示所有错误信息。这种设计虽然全面，但在用户体验上却存在明显缺陷。以用户注册表单为例，当用户刚删除输入内容时，系统可能同时显示"必填字段"、"格式不正确"和"年龄不足18岁"三条错误信息，这显然不够友好。

问题分析

TanStack Form当前版本（0.19.0）在处理验证错误时，会将字段的所有验证错误通过逗号连接后显示。这种处理方式虽然简单直接，但缺乏灵活性，特别是在以下场景中表现不佳：

1. 优先级处理：某些验证条件具有明显的优先级关系（如必填检查应先于格式验证）
2. 渐进式反馈：用户更希望看到最紧急的错误提示，而非所有可能的错误
3. 界面整洁：同时显示多条错误会导致界面拥挤，影响用户体验

技术解决方案

经过社区讨论，最终确定通过验证适配器(validatorAdapter)的配置化改造来解决这个问题。核心思路是：

1. 引入错误映射函数：允许开发者自定义错误信息的处理逻辑
2. 保持向后兼容：默认行为仍保持现有实现
3. 类型安全：通过TypeScript确保类型系统的完整性

具体实现采用了Valibot验证库作为示例，关键代码如下：

type Params = {
  errorMap?: (errors: [BaseIssue<unknown>, ...BaseIssue<unknown>[]]) => BaseIssue<unknown>
}

export const valibotValidator = (params: Params = {}) => {
  return {
    validate({ value }, fn) {
      if (fn.async) return
      const result = safeParse(fn, value)
      if (result.success) return
      return params.errorMap 
        ? params.errorMap(result.issues)
        : result.issues.map(i => i.message).join(', ')
    },
    // 异步验证实现类似
  }
}

使用示例

开发者现在可以灵活控制错误信息的展示方式：

1. 只显示第一个错误：

validatorAdapter: valibotValidator({
  errorMap: errors => errors[0]
})

2. 自定义优先级逻辑：

validatorAdapter: valibotValidator({
  errorMap: errors => {
    const requiredError = errors.find(e => e.message.includes('必填'))
    return requiredError || errors[0]
  }
})

3. 保持默认行为：

validatorAdapter: valibotValidator() // 显示所有错误

设计考量

在方案设计过程中，团队考虑了以下几个关键因素：

1. API一致性：确保新功能与现有API风格保持一致
2. 渐进式增强：不影响现有代码的正常运行
3. 类型安全：完善的TypeScript类型定义
4. 性能影响：最小化额外抽象带来的性能开销

最佳实践建议

基于此功能，我们推荐以下表单验证实践：

1. 分层验证：将验证条件按优先级排序，先检查基础条件（如必填），再检查复杂条件
2. 上下文感知：根据用户操作阶段显示适当的错误信息（如初次聚焦时只显示必填错误）
3. 渐进披露：在用户修正主要错误后，再显示次要验证条件
4. 错误分组：对相关错误进行逻辑分组，提升信息可读性

总结

TanStack Form通过这次改进，为开发者提供了更精细的错误展示控制能力。这种设计不仅解决了多错误同时显示带来的用户体验问题，还保持了框架的灵活性和扩展性。对于追求完美用户体验的表单场景，这无疑是一个值得关注的重要改进。

未来，团队还计划将此模式扩展到其他验证适配器，并探索更丰富的错误处理策略，如错误分类、条件显示等高级功能，进一步强化表单验证的表现力和可控性。