用途:在 React 中使用 TanStack Form v1(@tanstack/react-form 1.33.x)构建类型安全表单,覆盖校验、异步校验、字段数组与嵌套字段等场景。
主要能力:核心钩子包括 useForm()、useField()、form.Field 与 form.Subscribe。校验通过 Standard Schema 原生支持,直接把 schema 传给 validators(如 onChange: schema),无需 validatorAdapter 或 @tanstack/zod-form-adapter(已废弃)。支持 Zod(≥3.24.0,约12KB)、Yup(≥1.7.0,约40KB)、Valibot(≥1.0.0,约6KB),以及 ArkType、Effect Schema。还涵盖异步校验(防抖与加载状态)、React 19 Server Actions(useActionState、渐进增强)、数组与点号嵌套字段、TypeScript 类型推断、shadcn/ui 集成、监听器(onMount/onChange/onBlur/onSubmit 及防抖)、联动字段与跨字段校验、useStore 选择器响应式优化、Reset API、SSR/水合(TanStack Start)、Devtools 与 React Native 模式。
使用方式:资料要求实现前并行启动三个 Agent(explore-codebase、research-expert、mcp__context7__query-docs),实现后运行 fuse-ai-pilot:sniper 验证;并强制遵循 solid-react 的 SOLID 规则(源文件行数限制、接口置于 modules/[feature]/src/interfaces/、导出必须有 JSDoc、组件内无业务逻辑)。提供基础表单、多步表单、动态字段、文件上传、Server Action、乐观更新、嵌套表单、搜索、条件字段、表单组合、监听器、联动字段、响应式、重置、SSR、Devtools、React Native 等模板。
限制与最佳实践:校验用 Zod/Yup/Valibot 而非自定义正则;异步校验防抖 300-500ms;错误显示 field.state.meta.errors;嵌套用点号(address.street);数组用 mode="array" 配合 pushValue/removeValue;类型用 z.infer<typeof schema>。禁止用 useState 管理表单状态、组件内做校验、直接 onChange(应用 field.handleChange)、异步不防抖、缺少 TypeScript 类型。Next.js Server Actions 专用变体见 nextjs-tanstack-form。具体安装命令与完整代码示例资料未提供。