tanstack-form

TanStack Form

概览

TanStack Form 是一个无头表单状态管理器，而不是 UI 组件库。你需要提供自己的输入控件并处理其事件；TanStack Form 负责管理验证、状态和提交逻辑。

**适用场景：**复杂的多步骤表单、可复用的表单模式、动态字段数组、跨字段验证、异步服务端验证，以及需要进行细粒度性能优化的表单。

**不适用场景：**使用原生 HTML 验证的简单表单（使用纯表单元素）、仅在服务端进行验证的表单（使用 Server Actions）、没有验证逻辑的纯静态表单。

**React Compiler：**TanStack Form 尚未兼容 React Compiler。对于使用 TanStack Form API 的文件或组件，请禁用 React Compiler。

快速参考

模式	API	要点
基本表单	useForm({ defaultValues, onSubmit })	包含 Field 组件的表单实例
字段	form.Field，带有 name 和 children render 函数	使用 render prop 模式进行全面控制
字段验证	validators: { onChange, onBlur, onSubmit }	同步验证，返回错误字符串或 undefined
异步验证	onChangeAsync、onChangeAsyncDebounceMs	防抖的服务端检查
关联字段	onChangeListenTo: ['fieldName']	依赖项更改时重新验证
表单提交	form.handleSubmit()	验证通过后调用 onSubmit
表单状态	form.state.values、isSubmitting、isValid	访问表单级状态
字段状态	field.state.value、meta.errors、meta.isTouched	访问字段级状态
数组字段	mode="array"、pushValue、removeValue	使用辅助函数管理动态列表
Standard Schema	直接传入 Zod/Valibot/ArkType/Yup schema	原生支持，无需适配器
表单组合	createFormHook({ fieldComponents })	通过上下文使用可复用字段
拆分大型表单	withForm({ defaultValues, render })	用于表单分区且具备类型安全的 HOC
可复用字段组	withFieldGroup({ defaultValues, render })	共享验证逻辑的分组字段
订阅状态	使用 selector 的 form.Subscribe	高效控制重新渲染
显示字段错误	meta.isTouched && meta.errors.length	用户交互后显示错误
表单级验证	返回 { fields } 的 validators.onSubmit	在表单级别为特定字段设置错误
重置表单	form.reset()	重置为 defaultValues

常见错误

错误	正确做法
直接使用 e.target.value	使用 field.handleChange(value) 正确管理状态
缺少 onBlur={field.handleBlur}	始终添加，以控制验证时机并跟踪已触碰状态
立即显示错误	检查 field.state.meta.isTouched && errors.length
未指定异步验证的防抖时间	将 onChangeAsyncDebounceMs 设为适当值，避免向服务器发送过多请求
使用 listeners 进行验证	在验证器中使用 onChangeListenTo 以重新验证
仅在提交时验证	添加 onChange 或 onBlur 验证器，改善用户体验
未正确处理表单提交	阻止默认行为并调用 form.handleSubmit()
创建类似 QueryClient 的实例	直接在组件中使用 useForm hook
内联验证器函数	将其提取为稳定引用，或用 useCallback 包装
数组字段缺少字段名称	使用模板语法 hobbies[${index}].name 表示嵌套字段
未等待异步验证器	直接返回 Promise，由 Form 负责等待
提交前检查 isValidating	改用 canSubmit 状态选择器

委派

• 表单模式探索：使用 Explore Agent 查找现有表单实现
• 验证模式设计：使用 Task Agent 处理复杂的跨字段验证逻辑
• 代码审查：委派给 code-reviewer Agent 检查表单验证覆盖情况

如果有 shadcn-ui skill，请将组件样式和组合委派给它。否则，建议使用：npx skills add oakoss/agent-skills --skill shadcn-ui

如果有 tanstack-query skill，请将缓存管理和变更模式委派给它。 如果有 tanstack-start skill，请将服务端函数和服务端表单提交委派给它。 如果有 tanstack-router skill，请将提交后的导航和路由模式委派给它。 如果有 tanstack-devtools skill，请将表单状态调试委派给它。

参考资料

• 基础模式和表单设置
• 字段验证（同步、异步、关联字段）
• 模式验证（Zod、Valibot、ArkType、Yup）
• 数组字段和动态列表
• 表单组合和可复用字段
• 高级模式（多步表单、文件上传）
• 服务端集成（变更、缓存协调、服务端函数）
• React Aria 集成（TextField、Select、Switch、Checkbox、RadioGroup）
• shadcn/ui 集成（Field 布局、Input、Select、Switch、Checkbox、RadioGroup）