TanStack Form 自定义错误处理机制详解

TanStack Form 是一个功能强大的表单库，它提供了灵活的错误处理机制，允许开发者根据业务需求返回不同类型的错误信息。本文将深入探讨 TanStack Form 中自定义错误处理的几种实现方式。

字符串类型错误处理

最基本的错误处理方式是返回字符串类型的错误信息。这种方式简单直观，适合大多数基础验证场景：

validators: {
  onChange: ({ value }) => {
    return {
      fields: {
        username: value.username && value.username.length < 3 
          ? "用户名至少需要3个字符" 
          : undefined,
        email: value.email && !value.email.includes("@")
          ? "邮箱必须包含@符号"
          : undefined
      }
    };
  }
}

当用户输入不符合要求时，表单会显示相应的错误提示信息。这种方式的优点是实现简单，适合大多数基础验证场景。

非字符串类型错误处理

TanStack Form 的强大之处在于它支持返回任意类型的错误信息，这为复杂的业务场景提供了灵活性。

数值类型错误

onBlur: ({ value }) => {
  return {
    fields: {
      age: value.age < 18 
        ? 18 - value.age // 返回数值，表示还需要多少年才满18岁
        : undefined
    }
  };
}

对象类型错误

onBlur: ({ value }) => {
  return {
    fields: {
      email: value.email && !value.email.endsWith(".com")
        ? {
            message: "仅支持.com后缀的邮箱",
            severity: "warning",
            code: 1001
          }
        : undefined
    }
  };
}

对象类型的错误可以携带更多元的信息，如错误级别、错误代码等，方便前端进行更细致的处理。

混合类型错误处理

TanStack Form 还支持在同一表单中使用不同类型的错误信息：

onSubmit: ({ value }) => {
  return {
    fields: {
      username: !value.username || value.username.length < 5
        ? [
            "用户名不能为空",
            "用户名至少需要5个字符"
          ]
        : undefined,
      age: value.age <= 0
        ? true // 使用布尔值简单标记错误
        : undefined
    }
  };
}

禁用错误扁平化

TanStack Form 默认会将错误信息扁平化为字符串显示，但可以通过disableErrorFlat属性禁用这一行为：

<Field
  name="email"
  disableErrorFlat
/>

这样设置后，字段将保留原始的错误信息结构，方便开发者获取完整的错误对象进行处理。

类型安全

TanStack Form 提供了完善的类型支持，errors和errorMap都能保持类型安全。这意味着TypeScript能够准确推断错误信息的类型，帮助开发者在编码阶段发现潜在的类型问题。

总结

TanStack Form 的错误处理机制既简单又强大，从基本的字符串错误到复杂的自定义错误对象都能完美支持。这种灵活性使得它能够适应各种复杂的业务场景，同时保持代码的整洁和可维护性。开发者可以根据实际需求选择合适的错误处理方式，构建出用户体验优秀的表单应用。