Skip to content

Form State:字段、校验、提交与服务端错误的完整模型 ​

表单要同时区分加载快照、用户草稿、交互元数据、验证结果和一次提交的不可变快照。dirty 是当前草稿与基准的关系,touched 是交互事实,二者不能互相推导,也不能由服务端实体状态代替。

前置知识与能力边界 ​

本文处理复杂表单所有权、校验时机、动态字段、提交与恢复;HTML 控件基础和具体表单库 API 不是主线。

1. 定义、所有权与数据流 ​

Form State 包括当前字段值、初始值、交互元数据、同步/异步错误和提交状态。它的生命周期通常短于领域实体,不能直接等同于服务端记录或全局状态。

mermaid
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. 校验和提交的时序 ​

  1. change 更新原始值;是否立即显示错误由产品定义的校验时机决定。

  2. blur 设置 touched,可显示已知格式错误但不阻断继续编辑。

  3. 异步唯一检查防抖、取消,并把结果关联到发起时的字段值。

  4. submit 先执行整表解析,失败聚焦错误摘要并链接字段。

  5. 服务端字段错误映射到稳定路径,不可映射错误保留在表单级。

5. 应用案例一:企业开户表单 ​

  1. 为公司、联系人、受益人定义 raw schema 和领域命令。

  2. 动态数组每项使用 field id,重排后错误仍跟随同一人。

  3. 提交错误摘要链接到第一个无效字段并可键盘到达。

  4. 服务端返回企业已存在时保留全部草稿。

  5. 背景数据更新只标记基线冲突,不覆盖 dirty 字段。

结果:错误摘要链接到具体字段,重排受益人不会错配错误。

失败分支:服务端返回已存在企业时保留草稿,并将冲突显示为表单级错误。

6. 应用案例二:异步用户名检查 ​

  1. 输入 alice 后300ms发检查,再快速改为 bob 并取消旧 signal。

  2. 响应携带被检查值,只有等于当前 raw value 才能写错误。

  3. 网络失败显示无法确认,不显示用户名可用。

  4. 提交仍由服务端唯一约束决定。

  5. 延迟 alice 响应到 bob 之后,断言 bob 状态不被覆盖。

结果:只有当前值对应结果能更新字段错误,网络失败不宣称用户名可用。

失败分支:先输入 alice 再快速输入 bob,延迟 alice 响应不得覆盖 bob。

7. TypeScript 核心实现 ​

下面代码区分字段值、交互元数据和提交状态,并让验证器返回结构化错误。DOM 焦点与网络提交留在边界,通过表单状态机测试成功、失败和重复提交。

tsx
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 顺序。响应到达时:

  1. 若 submissionId 不是当前提交,丢弃或只记录诊断。
  2. 把服务端索引路径映射回该次提交的 fieldId。
  3. 若该 fieldId 已被删除,把错误放入表单摘要而不是另一个字段。
  4. 若字段当前值已改变,保留“结果基于旧值”的状态并允许重新校验。
  5. 聚焦第一个仍存在且可操作的错误字段。

14. 提交结果未知 ​

请求超时不等于服务端未处理。创建企业这类非幂等操作必须携带幂等键,超时后用同一键查询或重试。没有幂等能力时,表单进入 unknown,提示用户先查询结果,不能立即发送第二次创建。

提交结果表单处理不应执行
422 字段错误保留草稿,映射字段和摘要清空整个表单
401保留允许保留的草稿,重新认证把密码写入持久化
409 版本冲突展示服务器新版本并允许比较自动覆盖
网络中断且可确认未到达回到可重试状态宣称已经成功
超时且结果未知查询幂等结果或进入 unknown换新幂等键重复提交

自动化测试应在提交后继续修改字段,再让旧响应到达,确认响应不会覆盖新输入。还要模拟组件卸载、服务器返回未知字段路径和错误摘要链接目标被删除。

来源 ​

从前端走向软件产品工程的长期路线图。