表单与校验（Forms and Validation）#

帮助设计表单结构、校验规则、错误提示与无障碍表单体验。

触发场景#

• 用户说「表单」「校验」「提交」「受控组件」「form validation」「错误提示」
• 需求：多字段、联动、异步校验、防重复提交、无障碍

分析维度#

1. 表单结构#

要点做法受控 vs 非受控需校验/联动用受控；简单场景可用非受控 + ref状态集中单表单用 useState 或 useReducer；复杂用 React Hook Form / Formik / 自管理字段命名name 与后端一致，便于序列化与错误映射

2. 校验时机与规则#

时机适用失焦 (blur)单字段格式（邮箱、手机、长度）输入中 (change)实时格式提示，避免提交才报错提交时必填、跨字段、异步校验（如用户名是否存在）规则实现必填、长度、格式正则或 Zod/Yup/ajv 等 schema跨字段如「密码与确认一致」「起止日期」在 submit 或 schema 里校验异步防抖后调接口，结果写回字段错误状态

3. 错误展示与无障碍#

要点做法错误位置字段下方或旁侧，与字段 id 关联关联aria-describedby 指向错误文案的 id； aria-invalid="true" 当有误提交失败列表汇总 + 滚动到首个错误字段并 focus读屏错误文案在 DOM 中且与控件关联，便于读屏朗读

4. 提交与防重复#

要点做法防重复提交提交中禁用按钮或 loading 态，避免多次触达接口成功/失败成功跳转或提示；失败保留填写内容并展示错误重置明确「清空」与「重置为初始值」语义

执行流程#

1. 先搞清楚用户在哪个阶段#

用户描述实际需求第一步「表单怎么写」「从零做一个表单」设计表单结构问：字段有哪些？有没有联动/异步校验？用什么框架？「校验怎么做」「怎么提示错误」校验逻辑问：是已有表单加校验，还是新写？校验时机要 blur 还是 submit？「表单提交报错了」「校验没触发」具体 bug直接看代码，定位问题，不要先讲理论「用 RHF 还是 Formik」选型给明确推荐：RHF（性能好、非受控、与 Zod 配合好）；Formik 适合已有项目迁移成本低的场景

2. 设计表单时，按这个顺序推进#

第一步：确认字段和规则

让用户列出字段，或者读现有代码，整理出：

• 每个字段的类型（文本/选择/文件/日期）
• 必填/选填
• 格式规则（邮箱/手机/长度限制）
• 有没有跨字段校验（密码确认、起止日期）
• 有没有异步校验（用户名是否已存在）

第二步：给出选型建议

• 字段 ≤ 5 个、无联动 → useState 足够，不需要引入库
• 字段多、有联动、需要性能 → React Hook Form + Zod
• 已有 Formik 的项目 → 继续用 Formik，不要为了换而换

第三步：给完整代码，不要只给片段

包含：表单结构 + 校验规则 + 错误展示 + 提交处理 + 防重复提交。

3. 校验逻辑的决策#

遇到这些情况，按以下方式处理：

• 用户没说校验时机 → 默认 blur 触发单字段校验，submit 触发全量校验
• 有异步校验 → 必须加防抖（300-500ms），校验中显示 loading 状态，不要让用户等着没反馈
• 跨字段校验（如密码确认）→ 放在 schema 层（Zod refine）而不是单字段校验里
• 后端返回字段级错误 → 用 setError 写回对应字段，不要只 toast

4. 无障碍是必须的，不是可选的#

每个表单方案都要包含：

• 每个 input 有对应 <label>（ for/ id 关联，不是 placeholder 代替 label）
• 错误信息用 aria-describedby 关联到对应字段
• 有错误时字段加 aria-invalid="true"
• 提交失败后焦点移到第一个错误字段

不要等用户问「无障碍怎么做」才加，直接写进方案里。

输出模板#

markdown

## 表单与校验方案

### 表单范围
- 字段：…（必填/选填、格式）
- 特殊：异步校验 / 联动 / 文件

### 结构与选型
- 状态：受控 + React Hook Form / Formik / 自管理
- 校验：Zod / Yup / 自定义

### 校验规则（按字段）
| 字段 | 时机 | 规则 |
|------|------|------|
| … | blur/change/submit | … |

### 错误与无障碍
- 展示方式：…
- aria / 焦点 / 汇总：…

项目相关#

• React：受控 + useState 或 React Hook Form + Zod；错误用 setError / 字段级 error
• Vue：v-model + 计算/校验；可配合 VeeValidate 或自写
• 无障碍：每个 input 配 label（for/id）；错误用 aria-describedby 指向同一 id