表单错误状态契约

大理论

表单错误状态契约用于把前端实现和交互设计统一起来。一个健康表单不仅要在字段下方显示错误，还要知道每个字段的 label、hint、required/optional 文案、输入目的、校验来源、触发时机、错误锚点、提交状态、服务端失败分支和移动端键盘行为。这个条目是入口：当任务只是字段反馈，优先查 accessible-form-feedback；当是长表单顶部摘要，查 error-summary-pattern；当是高信任提交失败和保留输入，查 transactional-form-error-recovery；当是 label/hint/placeholder 边界，查 form-label-persistence；当是流程拆分与保存草稿，查 form-flow-and-validation。

小知识点

1. 字段契约先于视觉样式：每个输入都需要 visible label、helper、error、required/optional、default value、format rule、server rule、autocomplete、inputMode 和 submit owner。
2. 验证时机要按风险选择：未触碰的空必填通常在 submit/continue 后校验；格式错误可在 blur 后显示；输入中只做轻量帮助；异步用户名、优惠码和地址校验要 debounce 并可取消。
3. 不要只因为表单未验证就禁用提交按钮；用户需要能触发验证并看到怎么修。提交中可以防重复点击，但要显示 validating/submitting 状态和失败后的重试路径。
4. aria-invalid 只在字段确实无效时设置；错误消息、hint 和说明文本通过 aria-describedby 或清晰锚点连接，aria-errormessage 只在错误消息可见且字段 invalid 时使用。
5. 错误摘要不是内联错误的替代品；长表单、多错误或滚动距离大时，顶部摘要负责导航，字段旁错误负责具体修复。
6. 字段组错误要落到 fieldset/legend、组级 hint/error 和第一个可编辑控件，而不是只给外层 div 加红框。
7. 服务端错误要分 recoverable 与 fatal：recoverable 保留输入、解释原因、给重试或修改路径；fatal 说明系统/权限/网络状态和下一步支持。
8. 移动端错误状态必须检查键盘弹出、底部固定提交栏、sticky header、自动滚动、enterKeyHint 和 44px 目标，避免错误文字被遮挡。

设计判断

如果 agent 能输出字段清单、验证时机表、错误摘要结构、ARIA/focus 连接、submit state matrix、移动输入属性和服务端失败分支，这个表单才进入可实现状态。只有红框、toast、禁用按钮或浏览器原生提示，说明它还没有形成契约。

实现建议

定义 FormFieldContract：id、name、label、helper、requiredText、inputType、inputMode、autocomplete、valueState、validationTrigger、validationRules、errorId、describedByIds、ariaInvalid、serverErrorPolicy、mobileKeyboard、focusTarget。再定义 FormSubmitState：idle、dirty、validating、submitting、success、recoverableError、fatalError。React 实现中，字段组件不应自行决定所有错误文案；表单层统一管理错误摘要、焦点移动、重复提交防护和服务端响应映射。

反例/风险

提交按钮一直 disabled 且没有说明；输入一个字符就报错；错误只靠 toast；aria-invalid 初始就为 true；错误摘要链接不到字段；字段组没有 legend；服务端失败清空已填内容；移动端底部操作栏挡住错误；支付或身份表单失败后没有重试/支持路径。

案例分析

GOV.UK validation pattern 把错误处理拆成重新显示用户输入、页面 title 错误前缀、顶部错误摘要、字段旁错误、关闭 HTML5 validation 和服务端校验等协同行为。NHS error summary 在健康服务语境中要求错误摘要链接到每个出错答案，并同时在字段旁显示错误。WCAG Error Identification 强调必须用文本指出错误及其位置；W3C ARIA21、MDN aria-invalid、aria-describedby 和 aria-errormessage 给出前端连接边界。Baymard 的结账研究提醒 inline validation 可以降低成本，但过早验证会制造摩擦；NN/g 也把 validation messages 归为用户输入相关的错误反馈。可学习点是：表单错误设计要同时管理状态、语义、位置和时机。

来源链接

GOV.UK Validation pattern: https://design-system.service.gov.uk/patterns/validation/ GOV.UK Error summary: https://design-system.service.gov.uk/components/error-summary/ NHS Error summary: https://service-manual.nhs.uk/design-system/components/error-summary WCAG Error Identification: https://www.w3.org/WAI/WCAG22/Understanding/error-identification.html W3C ARIA21: https://www.w3.org/WAI/WCAG22/Techniques/aria/ARIA21 MDN aria-invalid: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid MDN aria-describedby: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby MDN aria-errormessage: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-errormessage NN/g form validation messages: https://www.nngroup.com/articles/indicators-validations-notifications/ Baymard inline validation: https://baymard.com/blog/inline-form-validation