Form State:字段、校验、提交与服务端错误的完整模型
表单要同时区分加载快照、用户草稿、交互元数据、验证结果和一次提交的不可变快照。dirty 是当前草稿与基准的关系,touched 是交互事实,二者不能互相推导,也不能由服务端实体状态代替。
前置知识与能力边界
- 单一职责与组合
- Controlled 与 Uncontrolled
- React State、Context、Effect 与 TypeScript 判别联合
- 浏览器事件、HTTP 和可访问性基础
本文处理复杂表单所有权、校验时机、动态字段、提交与恢复;HTML 控件基础和具体表单库 API 不是主线。
1. 定义、所有权与数据流
Form State 包括当前字段值、初始值、交互元数据、同步/异步错误和提交状态。它的生命周期通常短于领域实体,不能直接等同于服务端记录或全局状态。
flowchart LR
A0["初始值"] --> A1
A1["字段编辑"] --> A2
A2["客户端约束"] --> A3
A3["提交编码"] --> A4
A4["服务端校验"] --> A5
A5["错误映射或成功"]Form State 同时包含原始输入、初始基线、dirty/touched 元数据、校验错误和提交模式。字符串输入必须允许用户处于暂时不完整状态,只有在解析边界才能转换成领域命令。
2. 关键机制
2.1 values
保存用户当前输入,字符串输入在边界解析为领域类型。
若边界缺失,输入中途的空字符串被强制转 0。
验证:区分 raw value 与 parsed value。
2.2 initial values
作为 dirty 比较和重置基线,异步加载后需明确是否重建。
若边界缺失,数据刷新覆盖用户草稿。
验证:加载完成与用户已编辑竞态测试。
2.3 dirty/touched
dirty 表示与基线不同,touched 表示经历交互;二者用途不同。
若边界缺失,只用 touched 判断离开提示。
验证:逐字段测试焦点和回退。
2.4 同步校验
格式、必填和跨字段约束可在客户端快速反馈。
若边界缺失,把客户端校验当安全边界。
验证:绕过 JS 直接请求仍被服务端拒绝。
2.5 异步校验
用户名唯一等检查要防抖、取消并关联当前值。
若边界缺失,旧校验结果覆盖新值。
验证:延迟旧响应并比较 value token。
2.6 提交状态
idle/submitting/succeeded/failed 互斥,重复提交被拒绝。
若边界缺失,isLoading 与 isSuccess 独立。
验证:状态机测试转移。
2.7 动态数组
每项使用稳定业务 key,增删重排保留错误和焦点。
若边界缺失,数组索引作 key 后错误串行。
验证:重排后验证每项 id 与错误归属。
2.8 服务端错误
字段错误映射到路径,全局冲突放表单摘要。
若边界缺失,未知字段被静默丢弃。
验证:保留不可映射错误并记录。
2.9 序列化
FormData、JSON 对空值、文件、时区和数字处理不同。
若边界缺失,直接 JSON.stringify DOM value。
验证:提交 fixture 检查请求体。
2.10 恢复
草稿持久化要版本、过期、隐私和服务端基线冲突。
若边界缺失,密码和上传句柄被持久化。
验证:存储扫描确认敏感字段排除。
3. 原始值、解析值与服务端事实
age 输入框编辑期间可能是空字符串、- 或尚未完成的数字,这些都不能强制存成 number。提交时解析器把 raw values 转为领域类型并返回字段错误。服务端重复业务、授权与唯一性校验;成功响应才成为新的基线,客户端 schema 不是安全边界。
4. 校验和提交的时序
change 更新原始值;是否立即显示错误由产品定义的校验时机决定。
blur 设置 touched,可显示已知格式错误但不阻断继续编辑。
异步唯一检查防抖、取消,并把结果关联到发起时的字段值。
submit 先执行整表解析,失败聚焦错误摘要并链接字段。
服务端字段错误映射到稳定路径,不可映射错误保留在表单级。
5. 应用案例一:企业开户表单
为公司、联系人、受益人定义 raw schema 和领域命令。
动态数组每项使用 field id,重排后错误仍跟随同一人。
提交错误摘要链接到第一个无效字段并可键盘到达。
服务端返回企业已存在时保留全部草稿。
背景数据更新只标记基线冲突,不覆盖 dirty 字段。
结果:错误摘要链接到具体字段,重排受益人不会错配错误。
失败分支:服务端返回已存在企业时保留草稿,并将冲突显示为表单级错误。
6. 应用案例二:异步用户名检查
输入 alice 后300ms发检查,再快速改为 bob 并取消旧 signal。
响应携带被检查值,只有等于当前 raw value 才能写错误。
网络失败显示无法确认,不显示用户名可用。
提交仍由服务端唯一约束决定。
延迟 alice 响应到 bob 之后,断言 bob 状态不被覆盖。
结果:只有当前值对应结果能更新字段错误,网络失败不宣称用户名可用。
失败分支:先输入 alice 再快速输入 bob,延迟 alice 响应不得覆盖 bob。
7. TypeScript 核心实现
下面代码区分字段值、交互元数据和提交状态,并让验证器返回结构化错误。DOM 焦点与网络提交留在边界,通过表单状态机测试成功、失败和重复提交。
type RawProfile = { displayName: string; age: string };
type Profile = { displayName: string; age: number };
type ParseResult =
| { ok: true; value: Profile }
| { ok: false; errors: Partial<Record<keyof RawProfile, string>> };
export function parseProfile(raw: RawProfile): ParseResult {
const errors: Partial<Record<keyof RawProfile, string>> = {};
const name = raw.displayName.trim();
const age = Number(raw.age);
if (name.length < 2) errors.displayName = "名称至少两个字符";
if (!Number.isInteger(age) || age < 0 || age > 130) errors.age = "年龄必须是 0 到 130 的整数";
return Object.keys(errors).length > 0
? { ok: false, errors }
: { ok: true, value: { displayName: name, age } };
}字段类型不能替代运行时约束,也不能保证异步校验结果属于当前输入版本。应以请求序号或取消信号丢弃过期结果,并测试服务器字段错误如何映射回当前表单。
8. 方案选择
| 方案 | 适用条件 | 成本与限制 |
|---|---|---|
| 原生 FormData | 简单表单、渐进增强和服务端 action | 复杂动态字段需额外模型 |
| 受控 React state | 字段少且需即时派生 | 每次输入渲染和样板增加 |
| 表单库 | 动态数组、订阅、schema 与错误映射复杂 | 需要理解注册、卸载和默认值语义 |
短表单可以由局部受控状态管理,动态数组、跨字段验证和大规模订阅再考虑表单库。选择依据是字段生命周期、验证依赖和渲染成本,不是团队是否熟悉某个 API。
9. 调试与失败注入
| 现象 | 检查 | 修正 |
|---|---|---|
| 输入卡顿 | 是否整表受控重渲染 | 字段级订阅或非受控注册 |
| 错误闪烁 | 校验时机是否混乱 | 定义 blur/change/submit 策略 |
| 异步错误串值 | 是否关联当前值 | 取消并核对请求 token |
| 重置覆盖草稿 | 初始数据刷新是否自动 reset | 仅在 pristine 时替换 |
| 数组错误错位 | 是否使用 index key | 稳定 field id |
| 提交两次 | 是否禁用转移和服务端幂等 | 状态机加幂等键 |
| 屏幕阅读器不知错误 | aria-describedby 是否关联 | 焦点到摘要并保留内联错误 |
| 草稿泄密 | 是否持久化敏感字段 | 字段白名单与过期删除 |
先比较初始值、当前草稿和提交快照,再检查错误属于字段、表单还是服务器,最后确认异步校验是否对应最新输入。失败信号包括 reset 覆盖用户编辑、旧校验闪回和重复提交;用延迟响应、快速输入和失败重试测试复现。
10. 性能、安全与运维边界
- 服务端重复所有业务、安全和唯一性校验。
- 提交按钮禁用不能替代幂等处理。
- 错误文本与字段通过 id 和 aria-describedby 关联。
- 提交失败保留可安全重试的用户输入。
- 大表单使用字段级订阅并测量提交与输入延迟。
- 文件字段不尝试恢复不可序列化句柄。
- 草稿持久化排除密码、令牌和高敏个人信息。
- 统计字段错误率、放弃点和提交失败类型但不记录原始值。
生产验证至少记录一次正常路径和一次故障路径;对“Form State”的结论必须能关联到日志、Profile、网络记录或自动化测试。
11. 与其他架构模块集成
- State Machine 管理多步骤模式,Form State 管理字段。
- Server State 提供初始快照,不能在背景刷新时直接覆盖 dirty 表单。
- Persistent State 只保存允许恢复的白名单字段。
- 统一错误层把服务端 validation errors 映射为稳定字段路径。
集成时查询缓存提供加载时快照,表单拥有未提交草稿,提交命令只接收明确 DTO。后台刷新不得直接 reset 脏表单;应记录最新服务端版本并触发冲突处理。
12. 综合练习
实现带动态联系人、异步唯一检查、离开确认、草稿恢复和服务端字段错误的开户表单。
验收标准
- [ ] 区分 raw value、parsed value 与服务端记录。
- [ ] 动态字段重排不串错误或焦点。
- [ ] 异步校验覆盖取消、乱序和网络失败。
- [ ] 提交覆盖字段错误、全局冲突和重复点击。
- [ ] 草稿排除密码与文件句柄。
13. 动态字段的身份、错误和焦点
受益人数组不能用当前位置同时作为 React key、错误路径身份和服务端记录身份。每行至少有一个只用于前端编辑生命周期的 fieldId;已有记录另有 beneficiaryId。
删除第二行后,第三行虽然移动到索引 1,它的 fieldId、脏状态和错误仍属于原对象。提交时才按当前顺序生成服务端命令。若错误 API 只返回 beneficiaries.1.name,客户端还要确认响应对应哪一次提交;用户已重排后,旧索引错误不能直接写入当前表单。
稳定做法是给提交生成 submissionId,同时保存该次提交的 fieldId 顺序。响应到达时:
- 若 submissionId 不是当前提交,丢弃或只记录诊断。
- 把服务端索引路径映射回该次提交的 fieldId。
- 若该 fieldId 已被删除,把错误放入表单摘要而不是另一个字段。
- 若字段当前值已改变,保留“结果基于旧值”的状态并允许重新校验。
- 聚焦第一个仍存在且可操作的错误字段。
14. 提交结果未知
请求超时不等于服务端未处理。创建企业这类非幂等操作必须携带幂等键,超时后用同一键查询或重试。没有幂等能力时,表单进入 unknown,提示用户先查询结果,不能立即发送第二次创建。
| 提交结果 | 表单处理 | 不应执行 |
|---|---|---|
| 422 字段错误 | 保留草稿,映射字段和摘要 | 清空整个表单 |
| 401 | 保留允许保留的草稿,重新认证 | 把密码写入持久化 |
| 409 版本冲突 | 展示服务器新版本并允许比较 | 自动覆盖 |
| 网络中断且可确认未到达 | 回到可重试状态 | 宣称已经成功 |
| 超时且结果未知 | 查询幂等结果或进入 unknown | 换新幂等键重复提交 |
自动化测试应在提交后继续修改字段,再让旧响应到达,确认响应不会覆盖新输入。还要模拟组件卸载、服务器返回未知字段路径和错误摘要链接目标被删除。
来源
- HTML Living Standard:Forms(访问日期:2026-07-18)
- React:input(访问日期:2026-07-18)
- React:form(访问日期:2026-07-18)
- WAI-ARIA APG:Forms Practices(访问日期:2026-07-18)