react-forms

React 表单技能

此技能适用于构建健壮的 React 表单：受控输入、React Hook Form、Zod 验证、动态数组、Server Actions、乐观更新、可复用字段、文件上传、拖放和多步骤向导。

何时使用此技能

当用户提出的问题属于 frontmatter 触发条件所涵盖的任务时使用，尤其是实现指导、调试、架构选择、生产环境强化或此领域中对性能敏感的决策。从此编排器开始，然后加载与所需详细程度相匹配的专用参考文件。

核心工作流

1. 选择表单模型：简单表单使用受控状态，复杂的客户端表单使用 React Hook Form，或使用框架原生的 Server Actions 提交表单。
2. 在数据契约附近定义验证；当数据结构由多个部分共享或较为复杂时，优先使用 Zod 等基于 schema 的验证。
3. 从一开始就做好无障碍支持，包括标签、aria-invalid、aria-describedby、字段附近的错误文本，以及禁用／加载状态下的提交按钮。
4. 对于动态字段，使用 useFieldArray 中稳定的字段 ID，并在添加、删除或移动项目时保留验证路径。
5. 对于文件上传，验证类型／大小，仅在适当时生成预览，并通过 FormData 提交。
6. 对于多步骤表单，在进入下一步前仅验证当前步骤；如果数据必须保留，则在各步骤间共用一个表单上下文。

主要注意事项

• 除非有意使用桥接组件，否则不要在同一个输入框上混用受控和非受控模式。
• 在请求处理中禁用提交，以防止重复提交。
• 即使存在客户端验证，也始终显示服务端验证错误。
• 如果未撤销对象 URL，文件预览可能会造成内存泄漏；对于大文件，Data URL 可能会占用大量空间。
• 在 Server Actions 中，渐进增强以及请求处理中／错误状态都应清晰地展示给用户。

参考索引

• references/react-forms-complete-guide.md - 完整原始指南，涵盖受控表单、验证、React Hook Form、Zod、字段数组、条件字段、Server Actions、乐观更新、自定义组件、上传、拖放、多步骤表单和最佳实践。

回复指南

• 除非有明确的兼容性或性能理由建议替代方案，否则保留用户现有的框架、库和工具选择。
• 仅针对当前具体任务提供可直接复制粘贴的代码；否则，指向相关参考章节。
• 指出生产工作流中的权衡、故障模式和验证步骤。
• 优先选择无障碍、易维护且效果可衡量的方案，而不是巧妙的微优化。