form-state-patterns

用途

Form State Patterns 用于在 React 应用中构建生产级表单，解决复杂表单的校验、状态管理与性能问题。它把 React Hook Form v7 与 Zod 组合作为基础方案，并覆盖 React 19 的 useActionState 与 Server Actions 等新特性。

主要能力

基础表单与 Zod Schema：使用 zodResolver 将 Zod 校验接入 useForm，通过 z.infer 获得类型推断，支持 refine 实现跨字段校验（如确认密码一致）。
动态字段数组：使用 useFieldArray 实现添加、删除、交换、移动等操作，适用于发票、问卷等可增删条目的表单。
异步字段校验：通过 Zod 的异步 refine 或 mode: 'onBlur' 实现用户名可用性等异步校验，避免每次按键都触发请求。
Server Actions（React 19 / Next.js）：在 'use server' 中解析 FormData 并用 Zod safeParse 校验，返回字段错误；客户端使用 useActionState 获取 state、formAction 与 isPending。
多步向导：用 steps 常量与 wizardSchema 分步定义，通过 methods.trigger(stepKey) 做局部校验，配合 FormProvider 在步骤组件间共享表单上下文。
文件上传与预览：用 Zod 校验 FileList 的数量、大小与类型，结合 watch 与 URL.createObjectURL 生成预览。
受控组件集成：使用 Controller 将 DatePicker 等第三方组件接入表单，处理 value、onChange、onBlur 与错误信息。

使用方式

以 useForm 配置 resolver、defaultValues 与 mode 为基础；输入通过 register 注册并配合 aria-invalid、aria-describedby 与 role="alert" 提升可访问性；非原生输入使用 Controller；服务端变更使用 useActionState 与 Server Actions；动态字段使用 useFieldArray 并以 field.id 作为 key。

适用场景

复杂表单与校验、多步向导、动态字段数组、服务端校验、异步字段校验、带文件上传的表单。

限制与注意事项

资料明确列出若干反模式：禁止 watch 整个表单（会导致任意字段变化都触发重渲染）；禁止在字段数组中使用 index 作为 key（重排或删除时会产生 bug，应使用 field.id）；必须为所有字段提供 defaultValues，否则会出现非受控到受控的警告；使用 Zod 时应通过 noValidate 禁用原生校验以避免冲突；setError 后需在下次提交时手动 clearErrors；异步校验不应在每次按键触发，应使用 mode: 'onBlur' 或防抖；Zod 中应提供自定义错误消息而非默认的通用错误。

关键决策

校验库推荐 Zod（更好的 TypeScript 推断、更小的包体积）；校验模式推荐 onBlur（性能更好、噪音更少）；复杂组件推荐 Controller；服务端校验推荐 Server Actions；表单状态库推荐 React Hook Form（性能更好、重渲染更少）；字段数组推荐 useFieldArray。

可访问性检查清单

所有输入都有对应标签；错误消息使用 role="alert"；无效输入设置 aria-invalid="true"；提交按钮显示加载状态；错误时进行焦点管理。

参考资料

references/validation-patterns.md（高级 Zod 模式）、scripts/form-template.tsx（生产表单模板）、checklists/form-checklist.md（实现检查清单）、examples/form-examples.md（真实表单示例）。

技能介绍

用途