SuperAPI AI 工具集

tanstack-form

前端与建站

查看项目

更新于 10-16 02:35

技能介绍

用途:TanStack Form 是 headless 表单状态管理器,不是 UI 组件库。你需要自己提供输入控件并处理其事件,由它管理校验、状态和提交逻辑。适合复杂多步表单、可复用表单模式、动态字段数组、跨字段校验、异步服务端校验以及需要细粒度性能优化的表单。不适合简单表单(可用原生 HTML 校验)、仅服务端校验(可用 Server Actions)或无校验的纯静态表单。

主要能力:useForm({ defaultValues, onSubmit }) 创建表单实例,配合 form.Field 的 name 与 children 渲染函数使用。校验器支持 onChange、onBlur、onSubmit 同步校验,以及 onChangeAsync、onChangeAsyncDebounceMs 异步防抖校验。联动字段用 onChangeListenTo 在依赖变化时重新校验。数组字段用 mode="array" 配合 pushValue、removeValue。可直接传入 Zod、Valibot、ArkType、Yup 的 Standard Schema,无需适配器。表单组合用 createFormHook({ fieldComponents }),大表单拆分用 withForm,可复用字段组用 withFieldGroup,状态订阅用 form.Subscribe 配合 selector。

使用方式:用 field.handleChange(value) 管理状态,不要直接用 e.target.value;始终添加 onBlur={field.handleBlur};错误显示前检查 field.state.meta.isTouched && errors.length;异步校验设置 onChangeAsyncDebounceMs;提交时阻止默认行为并调用 form.handleSubmit();数组嵌套字段用 hobbies[${index}].name 模板语法;异步校验器直接返回 Promise。

限制:TanStack Form 尚不兼容 React Compiler,使用其 API 的文件或组件需禁用 React Compiler。校验器函数应提取为稳定引用或用 useCallback 包裹。提交前判断可用 canSubmit 状态选择器,而非 isValidating。

相关技能:若可用,可将组件样式与组合委托给 shadcn-ui 技能,缓存与 mutation 委托给 tanstack-query,服务端函数与提交委托给 tanstack-start,提交后导航委托给 tanstack-router,表单状态调试委托给 tanstack-devtools。