---
name: react-form-handling
when: '表单处理, 表单校验, 用户输入, 表单提交, Form, 表单开发, 数据采集, 编辑表单, 新增表单'
scope:
  - frontend
products:
  - '*'
id: ka-pattern-react-form-handling
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 表单处理
  - 表单校验
  - 用户输入
  - 表单提交
  - Form
  - 表单开发
  - 数据采集
  - 编辑表单
  - 新增表单
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 必须使用 Ant Design Form 组件，禁止手动管理每个字段的 value/onChange
- 校验规则必须写在 Form.Item rules 中，禁止散落在 submit 逻辑里
- 提交按钮必须有 loading 状态防止重复提交
- 新建和编辑必须共用同一表单组件，通过 initialValues 区分
- 必填字段必须有 rules + message 提示
- 复杂表单必须使用表单库（React Hook Form / Formik），禁止手动管理每个字段状态
- 表单校验必须使用 schema 校验（Zod / Yup），禁止分散的 if-else 校验
- 表单提交必须处理 loading/success/error 三态，禁止只处理成功
- 表单必须支持编辑回填（传入 initial values），新增和编辑共用同一组件
- 长表单必须分步骤（Step Form），每步校验通过后才进入下一步

## 验收项
- [AC-01] 表单使用 Ant Design Form 组件
- [AC-02] 必填字段有校验规则和提示信息
- [AC-03] 提交按钮有 loading 防重复
- [AC-04] 新建和编辑共用同一组件
- [AC-05] 使用表单库管理
- [AC-06] Schema 校验
- [AC-07] 提交处理三态
- [AC-08] 新增/编辑共用组件
