# 【Demo】Form 表单校验（7 个知识点）

> 源文件：`lib/pages/demo/form_demo.dart` ｜ 分类：基础布局
> 一句话：注册表单校验的完整范式 —— validator、时机、跨字段对比、协议勾选、两段式校验。

---

## 一、这个 Demo 解决什么问题

做注册/登录表单时新手最头疼的几件事，本页一次讲全：
必填/长度/正则/密码强度校验、确认密码对比、协议勾选校验、
**validator 不能 await** 时怎么做异步查重、防重复提交、重置表单。

### 和 Vue 的对照（关键差异）
| Vue | Flutter |
|---|---|
| v-model 双向绑定 + rules 规则对象 | TextEditingController + 每个字段自带 `validator` 函数 |
| `validate()`（async-validator） | `formKey.currentState.validate()` 统一触发 |

**Flutter 的 validator 是同步函数，返回 `String?`**：
- 返回 `null` → 校验通过；
- 返回字符串 → 错误文本（自动显示在输入框下方红字）。

没有"规则对象"，每个字段的规则就写在它自己的 validator 里，**就近维护**。

---

## 二、怎么运行 / 演示内容

```dart
runApp(const MaterialApp(home: FormDemoPage()));
```

5 个输入框（用户名/手机号/邮箱/密码/确认密码）+ 协议勾选 + 提交/重置：
- 不填就提交 → 红字提示；填错即时提示（onUserInteraction）；
- 提交通过 → 模拟 1 秒异步查重 → "注册成功"；
- 重置 → 清空所有输入和校验状态。

---

## 三、核心知识点（新手向）

### 1. Form 的骨架
```dart
final GlobalKey<FormState> _formKey = GlobalKey<FormState>(); // Form 的唯一钥匙

Form(
  key: _formKey,
  autovalidateMode: AutovalidateMode.onUserInteraction, // 校验时机
  child: Column(children: [ TextFormField(validator: ...), ... ]),
)

// 提交 / 重置都靠这把钥匙
_formKey.currentState!.validate();
_formKey.currentState?.reset();
```

### 2. 三种校验时机（AutovalidateMode）
| 模式 | 行为 | 建议 |
|---|---|---|
| `disabled`（默认） | 只在点提交 validate() 时校验 | 简单表单 |
| `always` | build 时立刻校验 | **慎用**：空表单满屏红字 |
| `onUserInteraction` | 用户碰过的字段才即时校验 | **推荐** |

### 3. validator 写法范式
```dart
// 必填 + 长度
String? _validateName(String? v) {
  final s = v?.trim() ?? '';
  if (s.isEmpty) return '请输入用户名';
  if (s.length < 2 || s.length > 8) return '用户名需 2-8 个字符';
  return null;
}

// 正则全匹配：^...$ 必须写！不然 11 位之后还能续数字
String? _validatePhone(String? v) {
  final s = v?.trim() ?? '';
  if (s.isEmpty) return '请输入手机号';
  if (!RegExp(r'^1[3-9]\d{9}$').hasMatch(s)) return '手机号格式不正确';
  return null;
}

// 跨字段对比：validator 里读另一个 controller
String? _validatePwd2(String? v) {
  if (v == null || v.isEmpty) return '请再次输入密码';
  if (v != _pwdC.text) return '两次密码不一致';
  return null;
}
```

### 4. 两段式校验（重点！validator 不能 await）
```dart
// ① 同步校验：所有 validator 逐个执行
if (!_formKey.currentState!.validate()) {
  _toast('有字段未通过校验，请检查红字提示');
  return;
}
// ② 同步通过 → 再单独做异步业务校验（查重/验证码）
setState(() => _submitting = true);
await Future.delayed(const Duration(seconds: 1)); // 模拟查重请求
if (!mounted) return; // 异步后必须判 mounted 才能用 context
```

### 5. 协议勾选：FormField\<bool> 校验"非输入型"字段
```dart
FormField<bool>(
  initialValue: _agreed,
  validator: (v) => (v ?? false) ? null : '请先勾选同意协议',
  builder: (field) {
    return Column(children: [
      InkWell(
        onTap: () {
          field.didChange(!(field.value ?? false)); // 更新 FormField 自身
          setState(() => _agreed = field.value ?? false); // 同步外部镜像
        },
        child: ...,
      ),
      // 注意：自定义 FormField 的 errorText 要自己在 builder 里渲染！
      if (field.hasError)
        Text(field.errorText!, style: const TextStyle(color: Colors.red)),
    ]);
  },
)
```

### 6. 防重复提交 + 重置
```dart
// 提交中按钮禁用（onPressed: null 自动置灰 + 换 loading 转圈）
FilledButton(
  onPressed: _submitting ? null : _submit,
  child: _submitting ? CircularProgressIndicator() : const Text('提交'),
)

// 重置：reset() 只清校验错误和 FormField 状态，不碰 controller.text！
void _reset() {
  _formKey.currentState?.reset();
  _nameC.clear(); // 清空输入要手动 clear()
  ...
}
```

---

## 四、关键代码剖析

通用输入框抽取（本页把 label/hint/图标/校验规则全部参数化，避免 5 个输入框复制粘贴）：

```dart
Widget _buildField({
  required String label,
  required TextEditingController controller,
  required String? Function(String?) validator,
  TextInputType? keyboardType,
}) {
  return TextFormField(
    controller: controller,
    keyboardType: keyboardType,
    validator: validator,
    decoration: InputDecoration(
      labelText: label,
      prefixIcon: Icon(icon),
      border: const OutlineInputBorder(),
    ),
  );
}
```

---

## 五、踩坑记录

1. **`formState.reset()` 不碰 `controller.text`** —— 清空输入必须手动 `clear()`；
2. **validator 是同步函数，不能 await** —— 异步校验（查重/验证码）放 validate() 通过之后单独做；
3. **正则要 `^...$` 全匹配**，否则 `RegExp(r'1[3-9]\d{9}')` 能匹配"123456789012345"；
4. 所有 controller 都要 dispose（本页 5 个）；
5. 加了 `.w/.h/.sp` 的 widget 不能 `const`；
6. 异步（await）之后用 context 必须先 `if (!mounted) return`。

---

## 六、扩展思考

- 校验规则多了以后，可以把 validator 抽成独立函数文件（如 `lib/core/validators/`），表单只负责组装；
- 真实注册流程：本页"模拟查重"处换成 `DioClient` 请求（见 [dio_demo.md](dio_demo.md)）；
- 密码强度可以升级为正则组合：`(?=.*[A-Za-z])(?=.*\d)` 就是"必须同时含字母和数字"的零宽断言写法；
- 表单 + 状态管理：把 controller 和提交逻辑挪进 Riverpod `NotifierProvider`，页面只剩纯 UI（见架构文档的 ExamPage 分层思想）。