用途:这是一个用于构建健壮 React 表单的 Skill,按需触发,主要覆盖受控表单模式、React Hook Form 配置与校验、Zod schema 校验、动态字段、Server Actions、乐观更新、可复用字段、文件上传、拖拽以及多步骤向导。当用户需要实现指导、调试、架构选型、生产加固或性能敏感决策时,可先从此编排入口开始,再加载匹配细节层级的参考文件。
核心流程:先选择表单模型——简单表单用受控状态,复杂客户端表单用 React Hook Form,框架原生提交用 Server Actions。校验应贴近数据契约定义,形状共享或复杂时优先使用 Zod 等 schema 校验。从一开始接入无障碍:标签、aria-invalid、aria-describedby、字段附近错误文本、提交按钮的禁用与加载状态。动态字段使用 useFieldArray 提供的稳定字段 ID,在新增、删除、移动时保留校验路径。文件上传需校验类型与大小,仅在合适时生成预览,并通过 FormData 提交。多步骤表单在前进前只校验当前步骤,需要保留数据时跨步骤共用同一表单上下文。
注意事项:不要在同一输入上混用受控与非受控模式,除非有刻意设计的桥接组件;挂起期间禁用提交以防重复提交;即使已有客户端校验,也要展示服务端校验错误;文件预览若不撤销 object URL 可能造成内存泄漏,大文件用 Data URL 会过大;Server Actions 中要保留渐进增强,并让挂起与错误状态对用户可见。
参考:references/react-forms-complete-guide.md 为完整原始指南。回复时优先保留用户既有的框架、库与工具选择,只为当前任务提供可复制代码,并说明取舍、失败模式与生产验证步骤。具体平台支持与安装方式暂未提供。