用途:在 Next.js 16 中构建类型安全、性能较好的表单,覆盖复杂校验、Server Actions 提交、多步向导、动态字段数组与实时异步校验(如用户名可用性)等场景。
主要能力:基于信号的响应式状态以减少重渲染;完整 TypeScript 推断(DeepKeys、DeepValue);原生集成 Next.js 16 Server Actions;Zod 适配器实现 schema 优先校验;框架无关且无头,可配合 shadcn/ui 等任意 UI 库。
使用方式:先定义 Zod schema 与共享 formOptions,客户端与服务端复用;客户端用 onChange、onBlur、onSubmit 校验,服务端在 onServerValidate 做数据库检查;用 React 19 的 useActionState 处理 Server Actions,并用 mergeForm 合并服务端错误。字段通过 Field API 获取 state(value、errors、touched、validating)与 handleChange、handleBlur。异步校验可用 asyncDebounceMs 防抖,form.Subscribe 做选择性重渲染。
结构建议:按功能模块组织,表单放 modules/[feature]/src/components/forms/,类型与 schema 放 interfaces/,Server Actions 放 actions/,共享工具放 modules/cores/lib/forms/。
限制:资料未提供具体安装命令、版本兼容细节、收费与平台信息;技能要求实现前使用 Codex 子代理做代码库探索与文档核对,实现后用 fuse-ai-pilot:sniper 验证,这些流程依赖相应环境。