Front-End-Checklist 无障碍表单校验（Form Validation）完整指南：从 ARIA 语义到 React 实现与代码审查

Front-End-Checklist 无障碍表单校验（Form Validation）完整指南：从 ARIA 语义到 React 实现与代码审查

【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist

本文以 Front-End-Checklist 仓库中的form-validation规则文档（skills/form-validation/SKILL.md）为核心骨架，系统讲解如何为表单校验构建可访问的错误提示：从aria-describedby、aria-invalid、aria-required等 ARIA 语义，到原生 HTML 校验、React 受控组件中的完整实现，再到 MCP 审查工具如何自动识别"客户端 React 表单"这一关键误报场景。读完本文，你将掌握一套可直接落地的无障碍表单校验实现方案，并能理解该规则在 AI 审查管线中的底层判定逻辑。

一、规则定位：为什么表单校验必须"可访问"

表单校验是前端最日常的功能之一，但不可访问的校验反馈会让屏幕阅读器用户完全无法理解"到底哪里错了、该如何修正"，最终导致挫败感与表单放弃率上升——这正是 form-validation 规则 与 SKILL.md 反复强调的核心痛点。

在 Front-End-Checklist 仓库中，该规则被定义为：

规则的一句话主旨：表单应提供清晰的校验反馈，配合可访问的错误消息与正确的 ARIA 属性。它不是一个孤立的规则，在 html-foundations 检查清单 中与input-types、search-input、file-upload-accessibility、accessible-tooltips等表单类规则一起被审查，共同构成 HTML 表单质量的完整防线。

二、快速参考：无障碍表单校验的六条铁律

来自 SKILL.md 的 Quick Reference，是每次实现与审查前都应默念的检查点：

1. 用aria-describedby将错误消息与字段关联——错误文本不能只"显示在附近"，必须被程序化地绑定到输入框上，屏幕阅读器才能朗读；
2. 用aria-invalid标记校验状态——aria-invalid="true"告诉辅助技术"这个字段当前无效"；
3. 用required或aria-required程序化标记必填字段——必填状态必须暴露在标记中，而不能只靠视觉上的红星；
4. 在字段附近提供内联错误消息——错误提示要紧贴对应输入框；
5. 不能仅靠颜色传达错误——必须同时有图标、文字或边框等非颜色线索（参考 color-contrast 等配套规则的精神）；
6. 帮助文本与错误文本在整个校验周期内都要保持与字段的关联——字段从"待填"到"报错"再到"修正"，aria-describedby的引用链不能断。

三、核心实现：一份可直接复制的语义化 HTML 表单

references/rule.md 与 form-validation.mdx 给出了完全一致的基线代码示例，这是理解后面所有 React 封装的基础：

<form novalidate> <div class="form-field"> <label for="email">Email address</label> <input type="email" id="email" name="email" aria-describedby="email-help email-error" aria-invalid="false" required /> <span id="email-help" class="form-field__help"> We'll never share your email </span> <span id="email-error" class="form-field__error" role="alert" hidden> Please enter a valid email address </span> </div> <button type="submit">Subscribe</button> </form>

注意几个关键设计决策，它们正是无障碍表单校验的"灵魂"：

• novalidate与required并存：novalidate关闭浏览器原生校验气泡，让自定义校验逻辑接管；required仍保留在标记中，确保必填状态对辅助技术可感知；
• aria-describedby="email-help email-error"：一个字段可以同时引用多个 ID，帮助文本与错误文本都会被朗读；引用顺序即朗读顺序；
• role="alert"+hidden：错误消息默认隐藏，一旦出现（移除hidden）就会触发即时播报，无需用户重新聚焦；
• aria-invalid="false"作为初始值：显式声明当前有效状态，后续由 JS 切换为"true"。

验证需求对照表

四、分组控件：fieldset 与 legend 的正确姿势

单选按钮与相关复选框必须有一个共享的语义标签，让用户先听到"问题是什么"，再听到各个选项。这一点 references/rule.md 用fieldset/legend给出了标准答案：

<fieldset aria-describedby="contact-help"> <legend>Preferred contact method</legend> <p id="contact-help">Choose the primary way we should contact you.</p> <label> <input type="radio" name="contact" value="email" required> Email </label> <label> <input type="radio" name="contact" value="phone"> Phone </label> </fieldset>

要点：legend为整组控件提供唯一可编程名称；fieldset上的aria-describedby可把组级帮助文本也纳入播报；组内单个控件（如第一个 radio）依然可以用required声明组级别必填。审查时的验证标准是：屏幕阅读器必须能在朗读选项标签之前先朗读到<legend>内容。

五、React 场景：可复用 FormField 组件的源码级实现

规则文档特别强调了一个容易踩坑的认知："不要在 React 表单上误报缺陷"。当onSubmit明确在客户端处理提交时，表单缺少method或action并不是可访问性缺陷——这条反误报逻辑在仓库的 MCP 审查工具中有着精确的代码实现（见第七节）。

下面是从 references/rule.md 继承并整理的 React 可复用组件，完整实现了前文全部 ARIA 语义：

import { useState, useRef, useId, FormEvent } from 'react' interface FormFieldProps { label: string name: string type?: string required?: boolean error?: string help?: string value: string onChange: (value: string) => void } export function FormField({ label, name, type = 'text', required = false, error, help, value, onChange }: FormFieldProps) { const inputId = useId() const helpId = useId() const errorId = useId() const describedBy = [ help ? helpId : null, error ? errorId : null, ].filter(Boolean).join(' ') || undefined return ( <div className="form-field"> <label htmlFor={inputId}> {label} {required && <span aria-hidden="true">*</span>} </label> <input id={inputId} name={name} type={type} value={value} onChange={(e) => onChange(e.target.value)} aria-describedby={describedBy} aria-invalid={!!error} aria-required={required} className={error ? 'form-field__input--error' : ''} /> {help && ( <span id={helpId} className="form-field__help"> {help} </span> )} {error && ( <span id={errorId} className="form-field__error" role="alert"> <span className="form-field__error-icon" aria-hidden="true">⚠</span> {error} </span> )} </div> ) }

该组件值得逐行学习的工程细节：

• useId()三连：输入框、帮助文本、错误文本各取一个唯一 ID，天然避免 ID 冲突，且保证aria-describedby引用的 ID 始终存在——这直接呼应了 SKILL.md 中"检查每个aria-describedby引用都能解析到可见文本"的审查项；
• describedBy动态拼接：帮助与错误都可能缺席，用filter(Boolean).join(' ')组装出 "helpId errorId" 或只有其一，字段无帮助无错误时不输出aria-describedby（undefined）；
• aria-invalid={!!error}：错误字符串存在即为true，错误清除后自动回落到false；
• aria-hidden="true"的必填星号：视觉上的*装饰标记对屏幕阅读器隐藏，必填语义交给aria-required承担，避免重复播报；
• 错误消息的role="alert"：错误出现时立即播报，图标用aria-hidden="true"隐藏，不会把 ⚠ 也读出来。

完整注册表单示例

将上述组件组装成真实业务表单，规则文档中的 Complete Form Example 展示了"校验函数 + 焦点管理 + 错误摘要"的完整闭环：

interface FormData { name: string email: string password: string } interface FormErrors { name?: string email?: string password?: string } export function SignupForm() { const [formData, setFormData] = useState<FormData>({ name: '', email: '', password: '' }) const [errors, setErrors] = useState<FormErrors>({}) const [submitted, setSubmitted] = useState(false) const formRef = useRef<HTMLFormElement>(null) const validate = (): FormErrors => { const newErrors: FormErrors = {} if (!formData.name.trim()) { newErrors.name = 'Name is required' } if (!formData.email.trim()) { newErrors.email = 'Email is required' } else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(formData.email)) { newErrors.email = 'Please enter a valid email address' } if (!formData.password) { newErrors.password = 'Password is required' } else if (formData.password.length < 8) { newErrors.password = 'Password must be at least 8 characters' } return newErrors } const handleSubmit = (e: FormEvent) => { e.preventDefault() const newErrors = validate() setErrors(newErrors) setSubmitted(true) if (Object.keys(newErrors).length > 0) { // Focus first field with error const firstErrorField = formRef.current?.querySelector('[aria-invalid="true"]') ;(firstErrorField as HTMLElement)?.focus() return } // Submit form console.log('Form submitted:', formData) } const updateField = (field: keyof FormData) => (value: string) => { setFormData(prev => ({ ...prev, [field]: value })) // Clear error when user starts typing if (errors[field]) { setErrors(prev => ({ ...prev, [field]: undefined })) } } return ( <form ref={formRef} onSubmit={handleSubmit} noValidate> {/* Error summary (optional but helpful) */} {submitted && Object.keys(errors).length > 0 && ( <div role="alert" className="form-errors" aria-live="assertive"> <h2>Please correct the following errors:</h2> <ul> {errors.name && <li><a href="#name">{errors.name}</a></li>} {errors.email && <li><a href="#email">{errors.email}</a></li>} {errors.password && <li><a href="#password">{errors.password}</a></li>} </ul> </div> )} <FormField label="Full name" name="name" required value={formData.name} onChange={updateField('name')} error={errors.name} /> <FormField label="Email address" name="email" type="email" required value={formData.email} onChange={updateField('email')} error={errors.email} help="We'll never share your email" /> <FormField label="Password" name="password" type="password" required value={formData.password} onChange={updateField('password')} error={errors.password} help="Must be at least 8 characters" /> <button type="submit">Create Account</button> </form> ) }

这段代码里包含三个必须保留的无障碍细节：

1. 错误焦点管理：提交失败时通过querySelector('[aria-invalid="true"]')找到第一个出错字段并调用.focus()，让键盘与屏幕阅读器用户直接落点于问题所在（对应验证需求表中的"Focus management"）；
2. 错误摘要：role="alert"+aria-live="assertive"的摘要区块会中断性播报"请修正以下错误"，内部错误项使用<a href="#name">锚点链接，点击即可跳转到对应字段；
3. 输入即清除：updateField中一旦用户开始修改出错字段立即清除对应错误，同时FormField的aria-invalid自动回落为false——错误提示不会顽固残留。

实时校验：useValidation 自定义 Hook

规则文档还提供了一个"失焦即校验、输入即重验"的轻量 Hook 模式，适合不需要表单库的场景：

function useValidation(value: string, validators: ((v: string) => string | null)[]) { const [error, setError] = useState<string | null>(null) const [touched, setTouched] = useState(false) const validate = () => { for (const validator of validators) { const result = validator(value) if (result) { setError(result) return false } } setError(null) return true } const onBlur = () => { setTouched(true) validate() } return { error: touched ? error : null, onBlur, validate, isValid: !error } } // Validators const required = (message: string) => (value: string) => value.trim() ? null : message const minLength = (min: number, message: string) => (value: string) => value.length >= min ? null : message const email = (message: string) => (value: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value) ? null : message // Usage function EmailInput() { const [email, setEmail] = useState('') const validation = useValidation(email, [ required('Email is required'), email('Please enter a valid email') ]) return ( <FormField label="Email" name="email" type="email" value={email} onChange={(v) => { setEmail(v) validation.validate() }} onBlur={validation.onBlur} error={validation.error} /> ) }

设计要点：校验器采用柯里化（currying）写法，required('Email is required')返回一个(value) => string | null的纯函数，方便任意组合与单元测试；touched状态保证错误只在用户离开过该字段（onBlur）后才显示，避免"输入前就报错"的糟糕体验。

六、样式与原生校验：不给颜色"独自扛"的机会

错误样式的正确写法

references/rule.md 的 Styling 章节展示了"错误不能只靠颜色"的完整 CSS 配套：

.form-field { margin-bottom: 1.5rem; } .form-field label { display: block; font-weight: 600; margin-bottom: 0.5rem; } .form-field input { width: 100%; padding: 0.75rem; border: 2px solid #ccc; border-radius: 4px; font-size: 1rem; } .form-field input:focus { outline: none; border-color: #0066cc; box-shadow: 0 0 0 3px rgba(0, 102, 204, 0.2); } .form-field__input--error { border-color: #dc3545; } .form-field__input--error:focus { border-color: #dc3545; box-shadow: 0 0 0 3px rgba(220, 53, 69, 0.2); } .form-field__help { display: block; font-size: 0.875rem; color: #666; margin-top: 0.25rem; } .form-field__error { display: flex; align-items: center; gap: 0.25rem; font-size: 0.875rem; color: #dc3545; margin-top: 0.25rem; } .form-field__error-icon { flex-shrink: 0; } /* Error summary */ .form-errors { padding: 1rem; background: #f8d7da; border: 1px solid #f5c6cb; border-radius: 4px; margin-bottom: 1.5rem; } .form-errors h2 { font-size: 1rem; margin: 0 0 0.5rem; } .form-errors ul { margin: 0; padding-left: 1.25rem; } .form-errors a { color: #dc3545; }

注意：错误态并不只改变边框颜色，还配了form-field__error的图标行（⚠+ 文字）与聚焦时的红色box-shadow——颜色之外始终有形状与文本双重线索。form-errors摘要区块使用浅红背景 + 边框 + 文字列表，同样不依赖单一颜色通道。

原生 HTML 校验：零 JS 的兜底方案

规则文档同时给出不写一行 JavaScript 的浏览器原生校验方案，适合无需自定义交互的场景：

<form> <label for="email">Email (required)</label> <input type="email" id="email" name="email" required pattern="[^@]+@[^@]+\.[^@]+" title="Please enter a valid email address" /> <label for="password">Password (8+ characters)</label> <input type="password" id="password" name="password" required minlength="8" /> <button type="submit">Submit</button> </form>

原生方案的取舍很清晰：type="email"、required、minlength、pattern都是标准属性，零依赖即可拦截大多数输入错误；但错误气泡的样式与文案由浏览器控制，无法完全自定义——这决定了它适合"够用就好"的表单，而需要精细控制体验的业务表单仍应回到自定义校验 + ARIA 的方案。

七、审查视角：MCP 审查工具如何判定 form-validation

Front-End-Checklist 仓库最独特的地方在于：每一条规则不仅有人类可读的文档，还实现了可被 AI/Agent 调用的审查逻辑。form-validation在 packages/mcp/src/tools/review-code.ts 中的判定代码（第 857-869 行）值得专门研究：

// Form method check — <form> without explicit method attribute defaults to GET, which may be unintentional if (slug.includes('form-validation') || slug.includes('form-method')) { if (code.match(/<form[^>]*onSubmit\s*=/i) && !code.match(/<form[^>]*action\s*=/i)) { return { hasIssue: false } } if (lowerCode.includes('<form') && !code.match(/<form[^>]*method\s*=/i)) { return { hasIssue: true, issue: 'Form element missing method attribute — add method="get" or method="post"' } } }

这段代码精确实现了 SKILL.md 中 "Check" 部分的指导："Do not flag React forms just because they omitmethodoractionwhenonSubmitclearly handles submission client-side"：

• 分支一（反误报）：只要<form>上存在onSubmit且没有action属性，就判定无问题（hasIssue: false）——这是典型的客户端 React 表单模式，提交由 JS 处理，不要求服务端action；
• 分支二（真缺陷）：若表单存在但没有method属性（即不是 React 客户端模式），则报告"Form element missing method attribute"。

配套的单元测试在 packages/mcp/tests/unit/review-code-detection.test.ts 中给出了两条直接验证该逻辑的用例（第 852-863 行与第 890-893 行）：

// 用例一：客户端 React 表单处理器不应被标记 it('does not flag form-validation on a client-side React form handler', () => { const jsx = ` export function SearchForm() { return ( <form onSubmit={event => event.preventDefault()}> <input type="text" name="q" /> </form> ) } ` expect(noIssuesIn(jsx, 'form-validation')).toBe(true) }) // 用例二：带 method 属性的服务端表单同样不应被标记 it('does not flag form-validation when method attribute is present', () => { const html = '<form action="/submit" method="post"><input type="text" name="q"></form>' expect(noIssuesIn(html, 'form-validation')).toBe(true) })

这对"文档 — 实现 — 测试"三者相互印证，正是 AI 审查类工具的最佳实践：文档定义语义标准，代码实现启发式判定，测试锁定关键边界。审查规则还在 heuristic-coverage.test.ts 与 false-positive-audit.test.ts 中登记为被覆盖的规则之一，确保每条启发式都经过了误报审计。

八、Code Review 检查清单：审查表单时必须核对什么

综合 SKILL.md 的 Code Review 与 Explain 部分，审查模板、服务端渲染 HTML 或共享组件输出时，应逐项核对：

1. 审查对象：模板文件、服务端渲染 HTML、任何会输出表单标记的共享组件——审查最终浏览器面对的标记（rendered HTML），而不是框架源码抽象层；
2. 精确定位：明确指出违反规则的确切元素、属性和路由；
3. aria-describedby完整性：帮助文本与错误文本都应被包含在aria-describedby中——只关联其一即为缺陷；
4. 必填状态暴露在标记中：required/aria-required必须出现在渲染后的 HTML 里，不能只存在于视觉样式（如红色星号）中；
5. 不误报客户端表单：onSubmit处理提交的 React 表单缺少method/action不是缺陷（参照第七节的判定逻辑）。

自动化验证清单

• 检查焦点是否移动到第一个无效字段；
• 测试纯键盘完成整个表单；
• 检查用户修正输入后错误是否清除；
• 检查必填字段在渲染标记中是否暴露required或aria-required；
• 检查每个aria-describedby引用是否解析到可见的帮助或错误文本。

手动验证清单

• 用空必填字段提交表单；
• 验证屏幕阅读器是否播报错误消息；
• 验证aria-invalid设置是否正确；
• 验证错误消息在"不只看颜色"的前提下可见；
• 验证分组控件先播报<legend>再播报选项标签；
• 验证字段的帮助文本在出错前与出错后都能与字段一起被播报。

九、总结：一条规则背后的完整方法论

回看 Front-End-Checklist 对form-validation的整条知识链，可以提炼出可复用的方法论：

1. 语义先行：aria-describedby（关联）、aria-invalid（状态）、aria-required（必填）、fieldset/legend（分组）是四根支柱，缺一不可；
2. 实现分层：原生 HTML 校验（零依赖兜底）→ 自定义校验 + ARIA（精细控制）→ React Hook 封装（可复用、可测试），按业务复杂度递进；
3. 反馈闭环：错误出现（role="alert"播报）→ 焦点跳转（首个出错字段）→ 输入即清除（错误状态回落），覆盖完整交互周期；
4. 审查智能化：规则文档驱动启发式实现，测试锁定"客户端 React 表单不误报"等关键边界，让 AI 审查结果既准确又可解释。

当你在 form-validation.mdx 与 references/rule.md 中看到同一套代码示例时，请理解这正是仓库刻意为之的"单一事实来源"设计：人类开发者阅读规则页面，AI Agent 通过 SKILL.md 获得任务指令与审查要领，而 review-code.ts 中的实现与测试则是规则的可执行化身。三者协同，才构成了"为人类与 AI Agent 服务的现代 Web 开发清单"这一项目愿景在表单校验领域的具体落地。

【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist