TanStack Form v0.43.0 版本深度解析：验证器功能全面升级

TanStack Form（原React Hook Form）是一个现代化的表单状态管理库，它提供了灵活的表单状态管理和验证功能。最新发布的v0.43.0版本带来了验证器功能的重大改进，让表单验证更加灵活和类型安全。

验证器功能全面升级

本次更新的核心特性是对验证器功能的全面增强。现在开发者可以在验证器中返回任意类型的值，而不仅限于字符串错误信息。这一改进为表单验证带来了更大的灵活性。

<form.Field 
  name="password" 
  validators={{
    onChange: () => ({
      hasUppercase: false, 
      hasLowercase: true
    }) 
  }} 
/>

这种改进特别适合需要返回复杂验证结果的场景，比如密码强度检查可能需要返回多个维度的验证结果。

类型安全增强

新版本在类型系统上也做了重大改进，现在能够严格保证验证器返回值类型的正确性：

const form = new FormApi({
  defaultValues: {
    name: 'test',
  },
} as const)

const field = new FieldApi({
  form,
  name: 'name',
  validators: {
    onChange: () => {
      return 123 as const
    },
  },
})

// 现在能正确推断出errorMap的类型为123 | undefined
assertType<123 | undefined>(field.state.meta.errorMap.onChange)

// errors数组也能正确推断出类型
assertType<Array<123 | undefined>>(field.state.meta.errors)

这种类型安全保证让开发者在使用TypeScript时能获得更好的开发体验和更少的运行时错误。

重大变更与迁移指南

验证适配器移除

v0.43.0移除了所有validatorAdapter相关实现，包括：

• 移除了@tanstack/yup-form-adapter、@tanstack/valibot-form-adapter和@tanstack/zod-form-adapter包
• 移除了相关代码和属性

对于使用Yup的用户，需要等待Yup官方支持Standard Schema规范后才能继续使用。在此期间，可以考虑迁移到Valibot、Zod或ArkType等已经支持Standard Schema的验证库。

标准Schema验证变更

使用标准Schema验证时，错误数据结构发生了变化：

• form.errors现在变为Record<string, StandardSchemaV1Issue[]>
• field.errors现在变为StandardSchemaV1Issue[]（默认会扁平化，除非在form.Field中设置disableErrorFlat）

Vue相关变更

• Vue 3.4成为最低支持版本
• 不再支持Vue JSX用法，需要迁移到单文件组件(SFC)

迁移建议

对于正在使用schema验证的用户：

1. 移除所有validatorAdapter属性
2. 卸载不再需要的适配器包
3. 更新错误处理代码，从简单的字符串映射改为处理完整的issue对象

对于Vue用户，需要将表单组件迁移到单文件组件形式。

其他改进

除了主要验证功能改进外，v0.43.0还包含以下优化：

• 改进了Vue单文件组件(SFC)的支持
• 更新了TanStack Start适配器以支持新API

总结

TanStack Form v0.43.0通过验证器功能的全面升级，为开发者提供了更灵活的表单验证方案。虽然带来了一些破坏性变更，但这些改进为表单验证带来了更好的类型安全和更丰富的功能。对于现有项目，建议仔细阅读迁移指南，逐步完成升级。新项目可以直接享受这些改进带来的开发体验提升。