accessibility.api是什么

入门与上手

面向前端与移动开发者,讲清无障碍接口是干什么的、什么时候会用到,以及一套能落地的接入与自检思路。

做前端或移动端时,你可能突然收到一条无障碍相关的要求:按钮要能被读屏念出来、弹窗焦点不能跑丢、图片得有替代文字。这时你会搜到某个平台的无障碍接口文档,但看不出它是给谁用的、该在哪一层调。这篇只讲判断标准和动手顺序:先分清它管的是系统 UI 层还是网页内容层,再决定要不要接、接在哪一步。

前端或移动端开发做到一半,突然收到一条需求:按钮要能被读屏念出来、弹窗打开焦点不能跑丢、图片得有替代文字。你去翻某个平台的无障碍接口文档,文档写得很全,但看不出它到底给谁用、该在哪一层调。问题往往不在接口本身,而在于你没先分清它管的是系统 UI 层还是网页内容层。

这篇只讲判断标准和动手顺序:先看清这个接口作用于哪一层,再决定要不要接、接在哪一步、怎么自检。面向前端和移动端开发者,不谈规范史,只谈你明天上班能用的东西。

它到底管哪一层:先分清系统层和内容层

同样叫无障碍接口,落到不同平台上指的往往是两套东西。平台自带的系统级无障碍框架,管的是原生控件树、焦点顺序和朗读事件;网页那套标准管的是文档里的语义和可访问名称。两者不是一回事,接错层就是白做,还可能互相干扰。

系统层无障碍框架
各平台自家的那套能力,你通过标注原生控件的角色、状态、可访问名称,把元素的存在和可操作方式告诉辅助技术
内容层语义与可访问名称
网页侧走 HTML 语义标签加 ARIA 属性,让浏览器和读屏软件在文档树上理解每个节点是什么、叫什么
可访问名称
辅助技术实际念出来的那串文字来源,可能来自可见文本、标签关联或属性标注,多个来源同时存在时会有优先级

所谓调用无障碍接口,本质是你主动把「这是个什么、叫什么、现在什么状态、能怎么操作」告诉辅助技术,而不是让它自己去猜控件结构。改原生控件属性就走系统层,改 HTML 语义或 ARIA 属性就走内容层。

  • 判断第一问:我改的是原生控件属性,还是页面标签的语义与属性。答案决定你在哪一层动手。
  • 判断第二问:这个元素默认有没有语义。自绘控件默认是空的,必须补;标准控件通常已经有,别重复标。
  • 判断第三问:这个属性会被读屏念几次。混着改两层,最常见的结果是念两遍,用户反而更困惑。
  • 判断第四问:出问题是「念不出来」还是「念得不对」。前者多半是语义缺失,后者多半是名称或状态不同步。

什么情况下必须动它,什么情况下可以先不管

不是所有界面都值得投入同样精力。有两类情况必须动,有两类情况可以先放着,还有几类情况明确不值得做,提前说清楚能省掉很多无效工作。

场景要不要接原因
自绘按钮、自绘开关、自绘下拉必须接默认没有任何语义,辅助技术读到的是一片空白
模态弹窗、路由切换、动态插入的列表必须接焦点位置和内容变化不会自己通知出去,用户会以为页面卡住
以标准控件和语义标签搭的普通页面可以先不管语义已经够用,优先级低于把焦点顺序修对
纯装饰元素、纯视觉动效、内部开发工具通常不值得没有实际使用者依赖朗读,投入产出比很低

对内部后台这类使用者固定的场景,先把键盘可操作做通,比补一堆朗读属性更划算。反过来说,面向公众的产品、需要走合规验收的场景,自绘控件和弹窗这两块就别省。

验收标准不看标了多少属性,看能不能用:关掉屏幕、只用键盘和读屏走一遍主流程,能走完就算过关。走不完,属性标得再全也没意义。

接入的动作顺序:先语义、再状态、最后事件

很多人一上手就写一堆属性,顺序反了。比较稳的做法是分四步走,每一步都有可验证的结果,出了问题也容易定位是哪一层漏了。

  1. 补语义先让辅助技术知道「这是个什么、叫什么」。先补角色和可访问名称,验证方法是开读屏后每个可点元素都能被念出名字。
  2. 补状态把选中、展开、禁用、加载中这些会变的状态同步出去,变化时发通知。验证方法是切换状态后读屏重新念一遍,信息不是过期的。
  3. 管焦点弹窗打开把焦点移进去、关闭还回原处;路由切换或异步插入内容后,把焦点放到该去的位置。验证方法是不用鼠标能不能继续往下操作。
  4. 定顺序检查键盘 Tab 顺序是否和视觉顺序一致。不一致优先改结构,而不是强行调序号,序号调多了后面维护会越来越乱。

这四步的顺序别颠倒。语义没补就发状态通知,读屏只能念出一句没有主语的提示;焦点管理放在最后做,是因为前两步没做好时,焦点放在哪都读不出有效内容。

自检清单与常见踩坑

上线前跑一遍三项自检,比反复看文档有用。三项都过之后再谈细节优化,否则很容易在细枝末节上耗时间,主流程却仍然走不通。

  • 只用键盘能否走通主流程,中途有没有卡住进不去的地方。
  • 开读屏后每个可点元素是否都有名字,名字是不是能说明它的作用。
  • 弹窗打开关闭后焦点是否正确,有没有留在页面角落回不去。

常见坑有三个:给标准控件硬套自定义属性,读屏念两遍;动态内容更新了却不发通知,用户以为页面卡死;只用颜色和动画表达状态,色觉异常用户完全收不到信息。排查时按语义、状态、焦点的顺序过一遍,多数「无法访问」其实卡在第一步的语义缺失上。

需要拿数字做对照的时候,去站内页面核对当时的口径,别把别处的结论直接搬过来用。各家平台对可访问名称的取用规则和优先级不完全一样,照着旧经验套很容易出现念错或念两遍。

下一步如果你要挑检测工具或对比各平台的实现口径,去工具目录按分类筛一遍,再看资料库里的技术分类页,能省掉自己逐个试的时间。

常见问题

accessibility.api 和浏览器自带的无障碍树是一回事吗?

不是。前者是你主动去读写和通知的那层接口能力,后者是浏览器根据你的 DOM 自动生成、给读屏调用的结构。你改语义和属性,就是在影响这棵树;两边的角色不同,别把它们当成一个东西。

小团队没人力做无障碍,最低限度做哪几件?

先做三件:所有可点元素有可读的名字、键盘能完整走通主流程、弹窗焦点不丢。这三件覆盖了绝大多数实际投诉场景,投入不大;剩下的细节可以等有明确要求或用户反馈再补。

接入之后怎么知道做对了没有?

别只看工具打分。人工走一遍:关掉屏幕用键盘走完一条主流程,再开读屏听一遍关键操作。工具能查属性缺失,查不出「念出来听不懂」,所以人工那步不能省。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。