Forms And Validation

SKILL.md

---
name: forms-and-validation
description: Designs form structure, validation rules, error handling, and accessible form UX. Use when 表单, 校验, 提交, 受控组件, form validation, 错误提示, or form UX.
---

# 表单与校验（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