该技能用于在 Next.js 16 项目中基于 TanStack Form v1 构建类型安全、高性能的表单,并集成 Server Actions、Zod 校验与 shadcn/ui。
用途与适用场景:构建校验要求复杂的表单;需要 Server Actions 处理提交;实现多步骤向导或动态字段数组;需要实时异步校验(如用户名可用性);希望表单具备完整 TypeScript 类型推断。
主要能力:基于信号的响应式状态,减少重渲染;完整 TypeScript 推断(DeepKeys、DeepValue);原生支持 Next.js 16 的 Server Actions;提供 Zod 适配器,支持以 schema 优先的校验;框架无关的 API;无头(headless)设计,可配合任意 UI 库(如 shadcn/ui)。
使用方式:文档给出的工作流要求在任何实现前,视情况使用可用的 Codex 子代理能力,建议并行执行:用 fuse-ai-pilot:explore-codebase 分析现有表单与校验模式;用 fuse-ai-pilot:research-expert 通过 Context7/Exa 核对最新 TanStack Form 文档;用 mcp__context7__query-docs 查看表单选项与字段 API。实现完成后运行 fuse-ai-pilot:sniper 进行验证。
关键规则:formOptions 共享定义一次,客户端与服务端复用;数据库检查放在 onServerValidate 而非客户端;Zod schema 用于客户端即时反馈;使用 React 19 的 useActionState 处理 Server Actions;用 mergeForm 合并服务端错误与客户端状态;按 SOLID 路径将表单放在 modules/[feature]/src/components/forms/。
代码组织:按功能模块组织,如 modules/auth/src/components/forms/ 存放认证表单,modules/auth/src/interfaces/ 存放表单类型与 schema,modules/auth/src/actions/ 存放提交用的 Server Actions,modules/cores/lib/forms/ 存放共享表单工具。建议文件包括 form-options.ts(共享 formOptions + Zod schema,50 行内)、FormComponent.tsx(客户端表单 UI,80 行内)、form.action.ts(带校验的 Server Action,30 行内)、form.interface.ts(表单值类型,30 行内)。
核心概念:表单选项模式(一次定义、客户端与服务端共享);字段 API(每个字段含 value、errors、touched、validating 等状态及 handleChange、handleBlur 等处理器);校验层级(onChange 实时、onBlur 失焦、onSubmit 提交前、onServer 服务端);错误管理(字段级与表单级错误,分别通过 field.state.meta.errors 与 form.state.errorMap 获取)。
最佳实践:先定义 schema,由 Zod 同时驱动校验与类型;共享 formOptions 作为客户端/服务端单一事实来源;异步校验用 asyncDebounceMs 做防抖;用 form.Subscribe 选择性订阅提交状态以减少重渲染;用 shadcn/ui 组合可复用字段组件;用 mergeForm 展示服务端校验错误。
与 React Hook Form 对比:类型安全为 100%(DeepKeys)对需手动标注;性能基于信号(最小重渲染)对基于 refs;Server Actions 为原生支持对需手动集成;包体积约 12KB 对约 9KB;学习曲线中等对较低;适用场景为复杂应用对标准表单。
限制:资料未提供安装命令、具体代码示例及兼容性细节,相关安装与迁移步骤需参考其 installation.md、migration-rhf.md 等参考文档。