用途:让 Web 与 App 界面能被键盘、屏幕阅读器、低视力和对动效敏感的用户使用。无障碍问题集中在少数几处:用 div 搭的自定义控件、没有标签的输入框、不可见的焦点、低对比度的“弱化”文字,以及焦点管理失当的弹窗,因此应优先排查这些点。
主要能力与用法: 一、语义化 HTML 优先。动作按钮用 <button type="button">,导航用 <a href="/path">,页面区域用 <header> <nav> <main> <footer>,标题按层级使用一个 <h1> 后接 <h2> 等,列表用 <ul>/<ol>,数据表用带 <th scope> 的 <table>。ARIA 只用于 HTML 无法覆盖的场景(选项卡、组合框、实时区域),错误 role 反而会误导辅助技术。 二、每个控件都要有名称。输入框配可见的 <label for>,占位符不能当标签;纯图标按钮用 aria-label 说明动作与对象;图片有意义的写 alt,装饰性的 alt="";错误信息用 aria-describedby 关联字段并设 aria-invalid="true";链接文字应独立可读。 三、键盘与焦点。用 Tab、Shift+Tab、Enter、Space、Esc 和方向键测试;所有交互元素可聚焦、顺序符合视觉顺序、焦点指示可见,不可只写 outline: none;可用 :focus-visible { outline: 2px solid <focus color>; outline-offset: 2px; }。弹窗打开时移入焦点、Tab 限制在内部、Esc 关闭并把焦点还给触发元素,原生 <dialog> 配合 showModal() 已覆盖大部分行为。内容较多页面首个可聚焦元素加“跳到内容”链接,避免键盘陷阱,不要用大于 0 的 tabindex。 四、实测对比度。WCAG AA 要求正文 4.5:1、大号文字(≥24px 或 ≥18.66px 粗体)及 UI 边界和焦点指示 3:1,需测量而非目测。可用命令:npx --yes @axe-core/cli "http://127.0.0.1:$PORT/" --tags wcag2a,wcag2aa。常见的占位符灰字、白色背景上约 #767676 以下的辅助文字、浅品牌色上的白字都要检查,明暗主题都测,且不要只用颜色表意。 五、动效、缩放与触控。响应 prefers-reduced-motion,可用 *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; scroll-behavior: auto !important; };文字放大 200% 不丢内容,字号用 rem,不要禁用缩放;触控目标至少 44×44px(最低 24×24px 并留间距);不要自动轮播或让表单无延长方式超时。 六、自动检查加人工复核。自动工具大约只能发现三分之一问题,只是底线。可用 Playwright + axe 编写测试,以 uv run --with playwright --with axe-playwright-python pytest 运行。每次涉及 UI 的 PR,花两分钟对改动页面做键盘走查、检查新颜色对比度,重要流程用 VoiceOver(macOS 按 Cmd+F5)听控件播报名称。 原生应用可借助系统组件:Button、Toggle、Label 和标准列表,支持 Dynamic Type 而不用固定点字号,给纯图标按钮加 .accessibilityLabel,用 .accessibilityElement(children: .combine) 组合相关元素,并用 VoiceOver 和 Accessibility Inspector 在最大字号下测试。
限制与反模式:不要用 div/span 的点击处理代替按钮和链接,不要为美观移除焦点轮廓,不要用占位符当标签,不要为“极简”使用浅灰文字,也不要把无障碍留到“以后再审计”,事后改造的成本远高于一开始就用对元素。
适用场景:Web 与原生 App 的界面开发、代码评审和无障碍整改;产品平台、框架版本等更多细节暂未提供。