用途:面向 React 的 TanStack Form 最佳实践指南,帮助构建类型安全的表单,覆盖表单创建、校验、字段组合与提交处理。
主要能力:按优先级组织规则,包括表单设置与类型推断、校验、Schema 校验(Zod/Valibot/ArkType)、表单组合、字段状态、数组字段、联动字段、监听器、提交、SSR/元框架、UI 库集成。
必要用法:安装 npm install @tanstack/react-form;用 useForm 创建表单,从 defaultValues 推断类型,不要传泛型 useForm<T>();提交时先 e.preventDefault(); e.stopPropagation(); 再 form.handleSubmit();form.Field 使用 children 渲染属性;用 form.Subscribe 配合 selector 订阅状态;用 useStore(form.store, selector) 而非 useStore(form.store);生产环境推荐 createFormHook 预绑定组件;异步校验需设置 onChangeAsyncDebounceMs 或 asyncDebounceMs。
关键模式:表单级 Schema 校验、数组字段(mode="array" 与 pushValue)、联动字段(onChangeListenTo)、监听器(onChange 中 setFieldValue)、withForm 组合。
限制:不要用 useField 做响应式;不要省略 useStore 的 selector;type="reset" 需配合 e.preventDefault() 或改用 form.reset();onSubmit 中不会应用 Standard Schema 的 transform,需手动解析。
开发工具:npm install -D @tanstack/react-devtools @tanstack/react-form-devtools,配合 TanStackDevtools 与 formDevtoolsPlugin 使用。