TanStack Form 中 validatorAdapter 的类型适配问题解析

问题背景

在使用 TanStack Form 库时，开发者可能会遇到表单验证器适配器(validatorAdapter)与表单类型不匹配的问题。特别是当使用 TypeScript 泛型为 useForm 指定表单数据类型时，验证器适配器会出现类型错误。

问题表现

当开发者尝试以下写法时：

const form = useForm<MyType>({
  onSubmit: ({ value }) => submit(value),
  validatorAdapter: valibotValidator(),
});

会收到类型错误提示：

Type 'Validator<unknown, GenericSchema<unknown, unknown, BaseIssue<unknown>> | GenericSchemaAsync<unknown, unknown, BaseIssue<unknown>>>' is not assignable to type 'undefined'.

解决方案

方案一：使用 defaultValues 推导类型（推荐）

TanStack Form 能够通过 defaultValues 属性自动推导表单类型，无需显式指定泛型参数：

const form = useForm({
  defaultValues: {
    firstName: '',
    lastName: ''
  },
  validatorAdapter: valibotValidator(),
  onSubmit: ({ value }) => submit(value)
});

这种方式既保持了类型安全，又避免了复杂的泛型配置。

方案二：显式指定验证器类型

如果需要显式指定表单类型，必须同时提供验证器适配器的类型参数：

import { ValibotValidator, valibotValidator } from '@tanstack/valibot-form-adapter';

const form = useForm<MyType, ValibotValidator>({
  onSubmit: ({ value }) => submit(value),
  validatorAdapter: valibotValidator()
});

原理分析

TanStack Form 的类型系统设计需要同时考虑表单数据类型和验证器类型。当使用泛型时，必须确保两者类型一致：

1. 表单数据类型(MyType)：定义表单字段的结构
2. 验证器类型(ValibotValidator)：定义验证器的行为规范

验证器适配器(valibotValidator)返回的验证器实例必须与声明的验证器类型匹配，否则 TypeScript 会报类型错误。

最佳实践建议

1. 优先使用 defaultValues 推导类型，代码更简洁且不易出错
2. 当需要复杂类型控制时，确保表单数据类型和验证器类型同步更新
3. 检查相关库版本是否一致，避免因版本不匹配导致类型问题
4. 对于不同的验证库(Zod、Valibot等)，需要使用对应的类型定义

总结

TanStack Form 提供了灵活的类型系统来支持各种验证场景。理解表单数据类型与验证器类型之间的关系，能够帮助开发者更高效地构建类型安全的表单应用。通过合理选择类型推导或显式声明的方式，可以平衡开发便利性和类型精确性。