无障碍富互联网应用(WAI-ARIA)1.3

W3C 首个公开工作草案

关于本文档的更多信息
本版本:
https://www.w3.org/TR/2024/WD-wai-aria-1.3-20240123/
最新发布版本:
https://www.w3.org/TR/wai-aria-1.3/
最新编辑草案:
https://w3c.github.io/aria/
历史记录:
https://www.w3.org/standards/history/wai-aria-1.3/
提交历史
最新推荐版本:
https://www.w3.org/TR/wai-aria/
编辑:
James NurthenAdobe
Peter Krautzbergerkrautzource UG
前编辑:
Michael CooperW3C)(编辑至2023年)
Joanmarie DiggsIgalia, S.L.)(编辑至2021年)
Shane McCarronSpec-Ops )(编辑至2018年)
Richard SchwerdtfegerKnowbility)(编辑至2017年10月)
James CraigApple Inc.)(编辑至2016年5月)
反馈:
GitHub w3c/aria拉取请求新建议未解决的问题

摘要

网页内容的无障碍性需要关于控件、结构和行为的语义信息,以便辅助技术能够向残障人士传递适当的信息。本规范提供了一套角色、状态和属性的本体,定义了可访问的用户界面元素,并可用于提升网页内容和应用的无障碍性与互操作性。这些语义旨在使作者能够在文档级标记中,向辅助技术正确传递用户界面行为和结构信息。本版本在 WAI-ARIA 1.1 [wai-aria-1.1] 基础上新增特性,以提升与辅助技术的互操作性,为 [HTML] 和 [SVG2] 形成更一致的无障碍模型。本规范可作为 [HTML] 和 [SVG2] 的补充。

本文档属于 WAI-ARIA 系列,详见 WAI-ARIA 概览

本文档状态

本节描述了本文档在发布时的状态。可在 W3C 技术报告索引 https://www.w3.org/TR/ 查阅当前 W3C 所有出版物及本技术报告的最新版本。

无障碍富互联网应用工作组欢迎就规范的任何方面提供反馈。在提交反馈时,请结合配套文档进行考虑。要发表评论,请W3C ARIA GitHub 仓库提交 issue。如无法通过此方式,请发送邮件至 public-aria@w3.org评论存档)。本文件的更新进展可在公开可见的编辑草案中查看。

本文档由无障碍富互联网应用工作组 作为 推荐路线的首个公开工作草案发布。

作为首个公开工作草案发布,并不代表 W3C 及其成员的认可。

本文档为草稿,可能随时进行更新、替换或作废。除作为在研工作外,不宜引用本文件。

本文档由遵循 W3C 专利政策 的小组编写。 W3C 维护了一份 与本组相关交付物的公开专利披露列表;该页面还包含披露专利的说明。任何知晓包含 必要声明 的专利的个人,都必须依照 W3C 专利政策》第6节披露相关信息。

本文档受 2023年11月03日 W3C 流程文档约束。

1. 引言

本节为非规范性内容。

本规范的目标包括:

WAI-ARIA 是一份技术规范,旨在为提升网页内容和应用的无障碍性和互操作性提供框架。本文档主要面向定制控件及其他网页应用组件的开发者。其他读者请参见 WAI-ARIA 概览,其中包含面向其他受众的相关文档链接,如 WAI-ARIA 编写实践 [WAI-ARIA-PRACTICES-1.2],介绍了 WAI-ARIA 旨在解决的无障碍问题、基本概念及技术方案。

本规范目前处理了角色的两个方面:用户界面功能和结构性关系。更多信息和用例可参见 WAI-ARIA 编写实践 [WAI-ARIA-PRACTICES-1.2],了解角色在交互内容无障碍中的应用。

本规范定义的角色旨在支持平台无障碍 API 使用的角色。在动态网页内容中声明这些角色,旨在实现网页内容与利用无障碍 API的辅助技术间的互操作。

为支持本标准而设计的模式具有可扩展性,因此可以通过扩展基础角色来创建自定义角色。这允许用户代理至少支持基础角色,而支持自定义角色的用户代理能够提供更丰富的访问体验。需要注意的是,许多内容可以正式化为 [XMLSCHEMA11-2],但诸如baseConcepts和更具描述性的定义等角色间的相似性,在 XSD 中并不适用。

WAI-ARIA 1.2 属于 WAI-ARIA 1.2 系列,定义了如何将 WAI-ARIA 及其他网页内容语言的语义暴露给 无障碍 API

1.1 富互联网应用的无障碍性

网页无障碍领域定义了如何让网页内容对残障人士可用。部分用户借助辅助技术AT)与内容交互。辅助技术可以将内容转换为更适合集合的形式,并允许以不同方式进行交互。例如,用户可能需要或选择通过方向键操作滑块控件,而不是用鼠标拖拽。为有效实现此目标,软件需理解内容的语义。语义即意义科学,在此用于给用户界面与内容元素分配角色、状态和属性,让其如同人类理解一般。例如,若某段落被明确标识为段落,辅助技术即可将之视为与其他内容区分的单元;可调整范围的滑块或可折叠列表(即树控件)等更复杂例子中,各组成部分的语义需被正确标识,辅助技术方能支持有效交互。

新技术常常忽略对无障碍所需语义的适配,而新的编写实践又常常错误使用了相关语义。元素原本在语言中有明确定义,却被以不同意义使用。

例如,Web应用开发者在 HTML 中使用 CSS 和 JavaScript 创建可折叠树控件,即便 HTML 并没有语义化的 tree 元素。对于非残障用户,这看起来像一个树控件,但若无适当语义,辅助技术就可能无法识别其角色,从而导致此树控件对有残障用户不可感知或不可操作。同样,开发者也会在 SVG 里用 JavaScript 制作按钮控件,而 SVG 本无语义化 button 元素。对非残障用户而言,这就是按钮,但无适当语义,残障用户也无法感知操作

引入 WAI-ARIA 能让作者为自定义控件补充正确的语义,从而让控件无障碍、可用、且具备良好的互操作性。本规范通过提供本体来标识无障碍产品通常识别的控件和结构类型,并为内容附加相应角色,使具有特定角色的元素无论实现语言如何,都能被理解为特定控件或结构类型。角色是平台无障碍 API的通用属性,辅助技术可据此为用户提供有效的表现及交互。

角色模型涵盖了交互控件和用于表达文档结构的元素,描述了继承关系及每个角色支持的属性详情。有关角色到无障碍 API 的映射,详见 核心无障碍 API 映射 [CORE-AAM-1.2]。

角色是元素类型,不会因时间或用户操作而改变。角色信息通过与用户代理交互被辅助技术使用,以实现对指定元素类型的常规处理。

状态和属性用于声明影响和描述交互的重要属性。它们使用户代理及操作系统能正确处理元素,即便这些属性被客户端脚本动态更改。例如,屏幕阅读器、语音输入等替代输入输出技术需能识别和有效处理各种交互状态(如禁用、已勾选等),并传达给用户。

尽管辅助技术可通过 文档对象模型 [DOM] 直接访问这些属性,但推荐做法是用户代理将状态和属性映射到操作系统的无障碍 API。详见 核心无障碍 API 映射 [CORE-AAM-1.2] 和 可访问名称与描述计算 [ACCNAME-1.2]。

图1.0展示了用户代理(如浏览器)、无障碍 API 及辅助技术之间的关系,描述了用户代理向辅助技术提供的“契约”,包括许多主流图形化界面无障碍 API 中常见的信息(角色、状态、选择、事件通知、关系信息和描述等)。DOM 通常指 HTML,在典型的MVC架构中充当数据模型与视图,JavaScript 则作为控制器,操控呈现数据的样式与内容。用户代理将相关信息传递至操作系统的无障碍 API,供屏幕阅读器等辅助技术使用。

The contract model with accessibility APIs

图1:无障碍 API 的契约模型

更多关于角色用于交互内容无障碍的信息,参见 WAI-ARIA 编写实践

替代输入设备用户需要键盘可访问内容。结合推荐的键盘交互,及 WAI-ARIA 编写实践,新语义可方便替代输入方案实现命令与控制。

WAI-ARIA 通过角色模型和 XHTML 角色地标,引入了导航地标,可帮助运动障碍及视障用户提升键盘导航体验。WAI-ARIA 还可协助有认知障碍的用户,作者可利用这些附加语义,对内容结构进行重组或替换。

辅助技术需能够通过获取和设定控件状态和属性的当前值,实现对替代输入的支持,还需管理如列表框和网格等可多选控件中被选中的对象

基于语音的命令与控制系统可借助 WAI-ARIA 语义(如 role 属性)帮助用户传达音频信息。例如,遇到具有 menu 角色的元素,且其子元素角色均为 menuitem 并分别代表不同口味时,语音系统可提示用户:“可选三种口味:巧克力、草莓或香草。”

WAI-ARIA 目的是补充宿主语言语义而非替代。当宿主语言已具备与 WAI-ARIA 等效的无障碍功能时,优先使用宿主语言特性。WAI-ARIA 仅应在宿主语言缺少相应角色状态属性指示时使用。应选择尽可能类似的宿主语言特性,再辅以 WAI-ARIA 精细化含义。例如,多选网格可先实现为表格,再用WAI-ARIA明确其为交互式网格而非静态数据表。这样有助于对不支持 WAI-ARIA 的用户代理实现良好回退,也维护了宿主语言语义的完整性。

1.2 目标受众

本规范定义了 WAI-ARIA 的基础模型,包括角色、状态、属性和值,影响如下几类受众:

每条符合性要求都明确了适用的受众。

尽管本规范适用于上述受众,但并非专门针对某一类,也不是唯一信息来源。以下文档提供了重要的补充信息:

1.3 用户代理支持

WAI-ARIA 依赖用户代理的双重支持:

除利用 WAI-ARIA 标记提升无障碍 API 显示外,用户代理本身保持原生行为。辅助技术依据无障碍 API 中新增信息作出反应,正如它处理非 Web 内容一样。而非辅助技术的用户代理,仅需向无障碍 API 正确推送信息,无需做其他事。

WAI-ARIA 规范并不要求,也不禁止用户代理基于 WAI-ARIA 标记强化原生表现或交互。主流用户代理可能以对话框、快捷键等形式暴露 WAI-ARIA 导航地标,以便所有用户导航。鼓励用户代理尽可能提升对(包括无障碍用户在内)所有用户的可用性。

WAI-ARIA 旨在提供缺失的语义信息,以便作者意图可传递给辅助技术。一般来说,使用 WAI-ARIA 的作者会自行提供恰当的表现与交互。随时间推移,宿主语言可补充 WAI-ARIA 对应特性,如新控件,由用户代理实现为标准可访问控件,作者可以用它们,而不是自定义 WAI-ARIA 组件。这时用户代理就支持宿主语言特性。编写实现 WAI-ARIA 的宿主语言时建议继续支持 WAI-ARIA 语义,只要与宿主语言语义不冲突,因为 WAI-ARIA 更能明确作者意图,若宿主语言本身难以满足作者需求。

1.4 WAI-ARIA 与宿主语言的共同演进

WAI-ARIA 旨在补充 [HTML]、[SVG2] 等支持语言的语义,或为不显式支持 ARIA 的标记语言作为无障碍增强技术使用。它可以在作者借助样式与脚本自创新对象类型而网页语言标准尚未直接支持这些对象时,向辅助技术明确语义。

若宿主语言已具备该对象类型的语义元素,不宜使用样式和脚本自创对象。虽然 WAI-ARIA 能提升这类对象的无障碍性,最佳无障碍体验仍应由用户代理原生支持该对象实现。例如,HTML 中应优先使用 h1 元素,而非在 div 上附加 heading 角色。

预计今后宿主语言会逐步为当前只能用 WAI-ARIA 定义的对象类型提供原生语义。这也是 WAI-ARIA 目标之一,即推动更语义化、更无障碍的标记标准的形成。原生语义出现后,建议作者直接采用原生特性,停止为该特性使用 WAI-ARIA;但遗留内容仍可继续用 WAI-ARIA,因此用户代理对其支持依然是必要的。

尽管 WAI-ARIA 部分具体特性可能随时间褪去重要性,但其为网页补充语义的能力将长期存在。宿主语言可能并未实现 WAI-ARIA 的所有语义,不同宿主语言也可能仅实现部分语义。新的对象类型会不断出现,WAI-ARIA 目标之一正是为此类对象提供可访问方案,因为网页开发实践常常快于宿主语言标准演进。就此,WAI-ARIA 与宿主语言将共同演进,但速度各异。

部分宿主语言仅为其他特征(非用户界面)赋予语义。例如 SVG 描述图形对象语义,而非这些对象可表达的用户界面组件。宿主语言可能设计时就不提供能映射 WAI-ARIA 特性的原生语义,此时适合采用 WAI-ARIA 作为长期为用户界面组件添加语义信息的方案。

1.5 编写实践

1.5.1 编辑工具

WAI-ARIA 角色状态属性的定义中有许多可在开发流程中自动检测,类似于代码质量控制。为帮助编写自定义控件的作者,编辑工具可比对自定义控件的角色、状态和属性与 WAI-ARIA 及相关引用角色、状态和属性的支持情况。编辑工具可通知作者控件设计模式中的错误,也可提示开发者补充上下文难以获得的信息。例如,脚本库可确定树视图中各树项的标签,但需提示作者定义整棵树的标签。为辅助作者可视化逻辑无障碍结构,编辑环境可基于 WAI-ARIA 标记,呈现网页资源的大纲视图。

HTMLSVG 中,tabindex 是浏览器为实现 WAI-ARIA 鍵盘焦点导航的重要手段;编辑和调试工具可检查 tabindex 是否设置合理。例如,若同一 tree 中有多个 treeitem 的 tabindex 不小于0,或者 treeitem 都未设置 tabindex,又或带有 tree 角色的元素 tabindex ≥0 却未定义 aria-activedescendant,皆属错误情况。

1.5.2 测试实践与工具

交互内容的无障碍性不能仅靠静态检查确认。开发者应测试控件和应用的设备无关访问,并应验证用户交互过程中全部内容及变更的无障碍 API 访问。

1.6 辅助技术

辅助技术依赖对无障碍语义的编程访问。大多数辅助技术通过被认可的无障碍 API 与用户代理(如其他应用)交互。界面中可感知对象以无障碍 API 接口定义的可访问对象形式暴露给辅助技术。为保证准确传达,必须通过无障碍 API 完整传递角色、状态、属性以及上下文信息。当状态变更发生时,用户代理向无障碍 API 触发相应事件通知。在 HTML 等许多宿主语言中,DOM 本身即可提供作为上下文树层级确定上下文信息。

部分辅助技术利用上述无障碍 API 交互,亦有部分直接从 DOM 读取内容。这些技术可对内容重构、简化、样式化或重排,以帮助不同用户群体。例如,区域导航地标的存在允许移动设备根据语义仅显示一部分内容,从而减少用户需同时处理的信息量。在其他情况下,也可能将复杂的自定义控件替换为更容易用键盘或触摸屏导航的组件。

2. 重要术语

本节为非规范性内容。

部分术语已在文中定义,以下定义则在本文档中多次使用。

无障碍 API

操作系统和其他平台提供一组接口,将对象事件的信息暴露给辅助技术。辅助技术通过这些接口获取对象信息并与这些控件交互。无障碍 API 的例子有 Microsoft Active Accessibility [MSAA]、Microsoft User Interface Automation [UI-AUTOMATION]、MSAAUIA Express [UIA-EXPRESS]、Mac OS X 无障碍协议 [AXAPI]、Linux/Unix 无障碍工具包 [ATK] 与 辅助技术服务提供接口 [AT-SPI],以及 IAccessible2 [IAccessible2]。

可访问对象

平台无障碍树中的节点。可访问对象会为辅助技术暴露各类状态属性事件。在标记语言(如 HTMLSVG)以及 WAI-ARIA 中,标记元素及其属性都会被表示为可访问对象。

辅助技术

包括如下硬件和/或软件:

  • 依赖用户代理提供服务来获取和呈现网页内容
  • 通过 API 与用户代理或网页内容交互,
  • 为残障用户与网页内容的交互,提供超越用户代理的功能

本定义可能与其他文档的定义不同。

与本文档相关的重要辅助技术实例包括:

  • 屏幕放大器,用于放大和提升文本与图像的可读性;
  • 屏幕阅读器,通常通过语音合成或可刷新的盲文显示器传递信息;
  • 文本转语音软件,将文本转换为合成语音;
  • 语音识别软件,允许语音控制与语音输入;
  • 替代输入技术(包括头指针、屏幕键盘、单开关、吹吸装置等),可模拟键盘输入;
  • 替代指点设备,用于模拟鼠标指点与点击。
弃用

已弃用的角色状态属性指已被更先进的构造或新情况取代,未来可能会从 WAI-ARIA 规范中移除。鼓励用户代理为兼容历史继续支持标记为弃用的项目。详情见符合性章节的弃用要求

定义

用于属性描述中,表示值类型整数数字字符串

相关术语:标识指示

桌面焦点事件

来自/发往主机操作系统的事件,通过无障碍 API 通知输入焦点变化。

事件

用于传递对象状态离散变化的编程消息,并供系统内其他对象接收。用户输入常通过抽象事件传递,事件可说明交互过程,也可通知文档对象状态的变化。在部分编程语言中,事件也称为通知(notification)。

暴露

无障碍 API 的定义,转换为平台专有的无障碍 API,详见 核心无障碍 API 映射

图形文档

包含用户可导航部分的图形表示的文档。例如图表、地图、图解、蓝图和仪表盘。图形文档可由符号、图片、文本及图形基本元素(如圆、点、线、路径、矩形等)组合构成。

隐藏

表示该元素已从无障碍树中移除,因此不会暴露给无障碍 API

相关:从无障碍树排除元素对所有用户隐藏aria-hidden

对所有用户隐藏

表示该元素所有用户均不可见、不可感知或不可交互。注意,通过aria-hidden元素可以隐藏,但并未做到对所有用户隐藏

相关:从无障碍树排除元素隐藏aria-hidden

标识

用于属性描述中,表示值类型ID 引用(标识单个元素)或ID 引用列表(标识一个或多个元素)。

相关术语:定义指示

指示

用于属性描述中,表示值类型为具名标记或类似标记,包括布尔型 true/falsetrue/false/undefined三态(true/false/mixed)、单一具名标记标记列表

相关术语:定义标识

键盘可访问

用户可通过键盘或模拟键盘输入的辅助技术(如吹吸管)访问。本文档提及内容与 WCAG 2.1 指南2.1:所有功能可通过键盘实现 [WCAG21] 相关。

地标

页面上一类用户可能希望快速定位的区域。该区域中的内容与页面其他区域不同,并与特定用户目标(如导航、搜索、主要内容浏览等)相关。

动态区域

动态区域指网页中因外部事件而更新的可感知区域。这类区域的更新不一定由用户交互触发,即使未获得焦点也可能接收更新。如聊天记录、股票行情或定期更新赛事比分的模块等。由于这些异步区域通常在用户未聚焦时更新,屏幕阅读器等辅助技术可能无法感知其变化。WAI-ARIA 提供了一组属性,允许作者标识并处理动态区域:aria-live、aria-relevant、aria-atomic 和 aria-busy。

托管状态

无障碍 API中由用户代理控制的状态,如焦点和选中状态。与“非托管状态”相对,后者通常由作者控制。但部分托管状态如 aria-posinset 和 aria-setsize 可被作者重写。许多托管状态在 CSS 中有对应伪类(如 :focus)和伪元素(如 ::selection),同样由用户代理同步更新。

尼梅斯盲文

尼梅斯数学盲文(Nemeth Braille Code for Mathematics)是一种用于数学和科学符号的盲文编码。详见 尼梅斯盲文-维基百科

对象

在用户界面上下文中,指感知体验中的项目,通常以一个或多个元素在标记语言中表达,并由用户代理渲染。

在编程上下文中,指一个或多个类和接口的实例,定义了一类对象的基本特征。无障碍 API 中的对象可代表一个或多个 DOM 对象。无障碍 API 拥有与 DOM 不同的接口定义。
本体

描述各类之间特性及其相互关系的说明。

可操作

用户能以自身可控方式使用。本文档相关内容参考 WCAG 2.1 原则2:内容必须可操作 [WCAG21]。参见 键盘可访问

可感知

以用户可感知的方式呈现。本文档提及内容参考 WCAG 2.1 原则1:内容必须可感知 [WCAG21]。

属性

属性是对象的本质特征,或代表与对象关联的数据值。属性变更可能显著影响对象的含义或表现。部分属性(如aria-multiline)较不易变,更频繁变更如aria-activedescendantaria-valuenowaria-valuetext。更多说明见状态与属性的区分

关系

两个不同事物间的关联。可用以表明哪个对象标记了另一个、被控制等。

角色

类型的主要指示符。该语义 关系允许工具以符合用户期望的方式展示对象并支持其交互。

语义

指人类理解的含义,并以方式让计算机能处理对象的表达,例如元素属性,并保证不同用户对对象有一致的理解。

状态

状态是一种属性,用于表达对象随用户操作或自动化进程发生变化的特征。状态不会改变对象的本质属性,而是表示与对象相关或用户交互相关的数据。更多说明见状态与属性的区分

目标元素

WAI-ARIA 关系中的指定元素。例如, <div aria-controls=”elem1”>“elem1” 作为目标元素的 ID。

Unicode 盲文模式

在 Unicode 中,盲文以 Braille Patterns(U+2800..U+28FF)区域表示。该区域包含 8 点盲文单元全部 256 种模式,包括6点单元的全部范围(U+2800..U+283F)。所有盲文系统中,盲文点0(U+2800)用于空格或无内容,又称空白盲文。详见 Braille Patterns - 维基百科

控件

用户可交互的离散用户界面对象。控件既可为仅有单个取值或操作的简单对象(如复选框、菜单项),也可为含有多个受控子对象的复杂对象(如树控件、网格)。

3. 符合性

无障碍富互联网应用规范的主要内容为规范性,定义了影响符合性声明的要求。引言、附录、标记为“非规范性”的章节及其子章节、图示、示例和说明均为参考性(非规范性)内容。参考性内容为帮助解读指南提供建议信息,但不会造成影响符合性声明的要求。

规范性章节规定了实现符合本规范时作者和 用户代理 必须遵循的要求。本文件中的关键字 MUSTMUST NOTREQUIREDSHALLSHALL NOTSHOULDRECOMMENDEDMAYOPTIONAL 应按 RFCs 中表述需求级别的关键字 [RFC2119] 的说明理解。RFC-2119 关键字均大写并包含在 class="rfc2119" 的元素中。当上述关键字被采用、但未用此格式时,不代表 RFC 2119 意义上的正式要求,仅为说明性(即参考性)。本规范尽量避免这样用法。

非规范性(参考性)部分提供有助于理解本规范的信息。这些部分可能包含推荐做法示例,但并不要求遵循这些推荐才能符合本规范。

3.1 不干扰宿主语言

WAI-ARIA用户代理 的处理MUST NOT干扰宿主语言内置特性的正常操作。

如果 CSS 选择器包含 WAI-ARIA 属性(如 input[aria-invalid="true"]),用户代理MUSTDOM中添加/更改/移除属性时,更新匹配或不再匹配该选择器的所有元素的可视显示。用户代理MAY更改宿主语言特性到 无障碍 API 的映射,但MUST NOT为将 WAI-ARIA 标记重新映射为宿主语言特性而更改 DOM

3.2 所有 WAI-ARIADOM

实现了文档对象模型且不符合 W3C DOM 规范的合规 用户代理 MUSTDOM 中,包含 role 及所有 WAI-ARIA 角色值 的内容属性,以及 WAI-ARIA 状态和属性,并且保留作者指定的值,即使后续处理可能影响元素如何暴露给无障碍 API。这样可确保每个 role 属性以及所有 WAI-ARIA 的状态和属性及其值,均以未修改形式存于文档,便于辅助技术等工具读取。符合 W3C DOM 的实现满足本条要求。

3.3 辅助技术通知传达给 Web 应用

辅助技术,如语音识别系统和针对行动障碍用户的替代输入设备,需要能够以设备无关的方式控制 Web 应用。WAI-ARIA状态属性反映富互联网应用组件的当前状态。辅助技术具备向 Web 应用通知必要变更的能力非常关键,这样的替代输入解决方案即可不依赖用户可能无法直接有效控制的标准输入设备实现对应用的控制。

用户代理MUST提供机制,在系统无障碍 API 状态或属性变化时通知 Web 应用。Web 应用作者SHOULD在接到用户代理或辅助技术的变更请求时,及时同步更新 Web 应用。

3.4 符合性检查器

任何用于验证文档符合性或有效性的应用或脚本SHOULD测试本规范中所有规范性作者要求。若验证某项要求时,符合性检查器MUST在未满足作者“MUST”要求时报告错误,未满足作者“SHOULD”要求时报告警告。

3.5 弃用要求

随着技术发展,有些用例会有新的、更优的解决方案出现,能比此前定义的特性更好地满足需求。但由于旧特性的实际实现仍在使用,为了不让曾经合规的内容变为不合规,这些特性不能直接从符合性模型中移除。在这种情况下,旧特性会被标记为“弃用”。这意味着该特性在符合性模型中仍被允许,用户代理仍应支持,但推荐作者勿在新内容中使用该特性。如果该特性以后不再被广泛使用,未来规范版本可以将其移除,并不再要求用户代理支持。

4. WAI-ARIA 的使用

辅助技术无法获知文档部分的语义,或用户无法有效地可用性导航全部内容区域时(参见WAI-ARIA 编写实践),复杂 Web 应用就会变得不可访问。WAI-ARIA 将语义划分为角色(界面元素类型定义)以及由角色支持的状态属性

作者需在文档生命周期内,将元素关联到 WAI-ARIA 角色和相关状态与属性(aria-* 属性),除非这些元素本身已有合适的内隐 WAI-ARIA 语义。在此情况下,宿主语言等效的状态和属性优先,以避免冲突,而 role 属性则会覆盖宿主语言元素的内隐角色。

4.1 WAI-ARIA 角色

通过 role 属性,可在元素上设置 WAI-ARIA 角色,同 Role Attribute [ROLE-ATTRIBUTE] 中定义的 role 属性类似。

<li role="menuitem">打开文件…</li>

模型中每个角色的定义包括以下信息:

为元素附加角色可向辅助技术告知如何处理每个元素。当 WAI-ARIA 角色覆盖宿主语言语义时,只有无障碍树发生改变,DOM 不变。

用户代理MUST使用 role 属性值中按顺序出现的第一个与任意非抽象 WAI-ARIA 角色名称匹配的标记。更多详情参见role 属性在宿主语言中的实现章节。

4.2 WAI-ARIA 状态与属性

WAI-ARIA 提供一组无障碍状态属性,用于支持多种操作系统平台上的平台无障碍 API辅助技术可通过暴露的用户代理 DOM或映射到平台无障碍 API 获取这些信息。结合角色,用户代理可随时为辅助技术提供需向用户传达的界面信息。状态或属性变化会向辅助技术发出通知,提醒用户有改动。

下例中,用 list item(html:li)创建可勾选菜单项,JavaScript 事件 用于捕捉鼠标和键盘事件以切换 aria-checked 的值。通过 role 指定该简单控件的行为让用户代理知晓。随用户操作变化的属性(如 aria-checked)定义于状态与属性章节。

<li role="menuitemcheckbox" aria-checked="true">按修改时间排序</li>

部分无障碍状态,称为托管状态,由用户代理管理。托管状态例子包括键盘焦点和选中。托管状态通常有对应的 CSS 伪类(如 :focus::selection)来定义样式变化。而本规范中的状态通常由作者控制,称为非托管状态。有些状态(如aria-posinsetaria-setsize)虽然由用户代理管理,但当DOM不完整且导致计算错误时,作者可覆盖。用户代理会把托管和非托管状态都映射到平台无障碍 API

大部分现代用户代理支持 CSS 属性选择器([CSS3-SELECTORS]),允许作者基于 WAI-ARIA 属性信息实现 UI 变更,减少实现等效功能所需的脚本量。以下示例用 CSS 选择器根据 aria-checked 属性值决定文本是否加粗和是否显示勾选图标。

[aria-checked="true"] { font-weight: bold; }
[aria-checked="true"]::before { background-image: url(checked.gif); }

如果未用 CSS 控制复选标志的可视表现,作者可用额外标记和脚本协助管理 menuitemcheckbox 是否被选中的图片。

<li role="menuitemcheckbox" aria-checked="true">
  <img src="checked.gif" alt="">
  <!-- 说明:需要额外脚本切换图片 src -->
  按修改时间排序
</li>

4.3 管理焦点与键盘导航支持

当使用标准 HTML 交互元素和简单 WAI-ARIA 控件时,应用开发者可修改元素在文档中的 tab 顺序或分配键盘快捷键。

WAI-ARIA 包含多种“可管理容器”控件,也称作“复合”控件。在适当情况下,容器负责追踪上次激活的后代元素(默认通常为容器内首项)。容器需在焦点离开又重新聚焦时,保持可用且一致的策略。尽管有例外,建议容器再次聚焦时,激活的后代元素应为上次聚焦时所激活者。例外场景包含控件内容变化等,或如菜单栏等场景常希望永远回到首项。例如树组内第二项上被激活,Tab 出后再聚焦,仍为第二项。用户也可点击容器内部的后代激活容器。当容器或其激活后代获得焦点时,用户可用额外按键(如方向键)遍历容器,切换当前激活项。导航主按键(通常是 TAB 键)再按下会移出容器到下一个控件。

富互联网应用中的键盘导航不同于静态文档中交互元素间的 tab 跳转。在富应用中,用户用 tab 进诸如菜单、表格等复杂控件,并用方向键在控件内部导航。WAI-ARIA 引入的键盘导航改进了可访问性。在 WAI-ARIA 下,任意元素均可获键盘焦点。除 tabindex 等宿主语言机制外,aria-activedescendant 也是一种键盘操作机制。WAI-ARIA 控件开发的许多方面依赖于键盘导航。

按下述方式实现 aria-activedescendant 时,用户代理会让 DOM 焦点保持在容器元素或其控制的输入元素上。 但用户代理会将桌面焦点事件和状态传递给辅助技术,好像 aria-activedescendant 所指元素获得了焦点。 用户代理无需校验被激活的后代是否为容器的后代。 用户代理需确保键盘事件在获得 DOM 焦点的元素上处理。 面向激活后代的键盘事件会冒泡至获焦元素进行处理。

4.3.1 作者参考信息

若作者移除了获得焦点的元素,则SHOULD将焦点转移到逻辑元素。同样,作者SHOULD不要主动把获取焦点的元素滚动出可视区域,除非用户执行了滚动操作。

作者SHOULD确保所有交互元素可获取焦点,所有复合控件各部分均可获焦,或有文档化替代实现。

作者MUST管理以下容器角色的焦点:

支持 WAI-ARIA 的用户代理, 将宿主语言机制如 tabindexfocusblur 扩展至所有元素。如宿主语言支持,作者MAY通过设置tabindex="0"将任何元素(如 divspanimg)加入默认 tab 顺序。此外,tabindex 为负数使元素可经脚本或鼠标获焦,但不在默认 tab 顺序之列。以上在 [HTML] 和 [SVG2] 中均支持。

作者MAYaria-activedescendant告知辅助技术,控件元素哪个后代在界面上被当作已获键盘焦点(如果控件角色支持该属性)。这种做法便于在如listbox等控件内实现键盘导航,该控件只占 1 个 Tab 停留点,内部元素由方向键等获焦。

通常作者用宿主语言语义让控件进入 Tab 流(如 HTML 的 tabindex="0"),用 aria-activedescendant 指定当前激活的后代 ID。激活后代的样式需由作者负责,不能用 :focus 伪类实现样式,因为实际焦点在容器上。

关于焦点管理的详细信息见 开发键盘接口章节。

4.3.2 用户代理参考信息

为实现aria-activedescendant,用户代理MUST满足以下要求:

  1. 实现宿主语言的键盘导航机制,使支持 aria-activedescendant 的控件可进 tab 顺序;
  2. 对于将桌面焦点或无障碍 API 焦点与 DOM 焦点分离的平台,不要在无障碍 API 上暴露获焦状态,当元素获得 DOM 焦点且有 aria-activedescendant 且指向合法 ID 引用 时。
  3. 当具 DOM 焦点元素的 aria-activedescendant 变化时,从先前获焦对象移除焦点状态,对新引用元素触发无障碍 API 桌面焦点事件。若属性被清空或不指向文档内元素,则对属性变更对象触发桌面焦点事件。
  4. 对任何可被带有 aria-activedescendant 且获 DOM 焦点的元素引用的 ID(其可为本体或由 comboboxtextboxsearchbox 控制的元素),应用下列无障碍 API 状态:
    1. 若元素也具 WAI-ARIA 角色,则其必须是可获焦的,因为可被 aria-activedescendant 所引用。无角色的原生元素无需检测,其原生语义即可决定可获焦性。
    2. 当元素是 aria-activedescendant 属性目标,且拥有该属性的元素获 DOM 焦点时,其为获焦态。

当辅助技术用平台无障碍 API 请求改变焦点时,用户代理MUST完成如下:

  1. 移除平台上先前获焦对象的焦点状态。
  2. 设置 DOM 焦点:
    1. 若该元素可获取 DOM 焦点,用户代理MUST将焦点设至本元素。
    2. 否则,若获焦元素具 ID 且被可获焦元素的 aria-activedescendant 属性引用,用户代理MUST将 DOM 焦点设至带该属性的元素。

      一个带 ID 的元素可被带 无障碍后代 的容器元素或由带 aria-activedescendant 属性控制的容器元素引用(如 combobox)。否则 aria-activedescendant 属性引用即为作者错误。

      无法将 DOM 焦点设至容器元素,即为作者错误。

    3. 否则用户代理MAY尝试将 DOM 焦点设至子元素本身。
  3. 若获焦元素具 ID 且为带有 aria-activedescendant 属性且获 DOM 焦点的容器元素的无障碍后代,或由带 aria-activedescendant 属性且获焦的容器控制,用户代理MUSTaria-activedescendant 所指元素上设置无障碍 API 获焦状态并触发获得焦点事件

5. 角色模型

本节定义了 WAI-ARIA 角色,并描述了它们的特性和属性。

角色、其特性、所支持的状态与属性,以及它们在标记中的使用规范,均视为规范性内容。

为了反映 DOM 中的内容,用户代理SHOULD将 role 属性映射到已实现的无障碍 API 中的相应值,并且当 role 属性变化时,用户代理SHOULD同步更新映射。

5.1 概念间的关系

角色模型通过以下关系,将 WAI-ARIA 的各个角色彼此关联,并与其他规范(如 HTML)中的概念建立联系。

5.1.1 父类角色

角色模型中当前子类角色所继承的角色。这种继承会使父类角色的所有状态和属性传递到子类角色。除著名且稳定的规范外,继承可限定为只继承本规范内定义的项,从而避免外部项变更影响继承的类。

5.1.2 子类角色

作为信息展示的角色子类清单,仅用于帮助阅读规范,不引入新信息。

来自其他规范的类似或相关概念的说明性信息。相关概念并不一定完全相同,彼此之间也不继承属性。因此,一个概念的定义如果发生变化,不会影响其相关概念的属性、行为或定义。

例如,进度条就类似于状态指示器。因此,progressbar 控件的相关概念包含 status。但如果 status 的定义被修改,progressbar 的定义不会受到影响。

5.1.4 基础概念

关于被视为该角色原型的对象的说明性信息。基础概念类似于类型,但不会继承限制和属性。基础概念可作为外部概念继承的替代方案。基础概念与相关概念类似,但基础概念与角色定义几乎完全相同。

例如,本文档中定义的 checkbox<input type="checkbox"> (定义于 HTML)功能和预期行为类似。因此,checkboxbaseConcept 就是[HTML] 里的 checkbox。但如果[HTML]中 checkbox 的基础定义变化,本文档里的 checkbox 定义不会受影响,因为类型之间没有真正的继承关系。

5.2 角色的特性

角色通过其特性定义和描述。特性界定了角色的结构性功能,例如该角色是什么、其背后的概念及可包含或必须包含哪些实例。对于控件,还包括基于与 HTML 表单的映射,与用户代理的交互方式。每个角色还会给出其支持的 WAI-ARIA 状态和属性。

角色定义以下特性。

5.2.1 抽象角色

可选值
布尔

抽象角色是所有其他 WAI-ARIA 角色的基础。内容作者MUST NOT(不得)使用抽象角色,因为它们不会被 API 绑定实现。用户代理MUST NOT将抽象角色映射到无障碍 API 的标准角色机制。抽象角色用于以下目的:

  1. 组织角色模型,并在已知概念上下文中赋予角色意义。
  2. 简化包含所需特性的角色添加。

5.2.2 必需状态和属性

专门为该角色及其子角色要求的状态属性。内容作者MUST(必须)为必需的状态和属性填写非空。除非undefined被明确认为是该状态或属性的有效值,内容作者MUST NOT使用undefined值。

对象从多个祖先类继承,且其中有一个祖先类规定属性为可支持,另外一个规定属性为必需,则继承得到的属性视为必需。

含有适当内隐 WAI-ARIA 语义的宿主语言属性亦可满足本项要求。

5.2.3 可支持的状态和属性

专门适用于该角色及其子角色的状态属性。内容作者MAY(可)为支持的状态和属性设置,如默认值已足够,则不必设定。用户代理MUST将该角色所有支持的状态和属性映射到无障碍 API。若状态或属性为 undefined 且该角色有默认值,用户代理SHOULD暴露默认值。

含有适当内隐 WAI-ARIA 语义的宿主语言属性亦可满足本项要求。

5.2.4 继承的状态和属性

由父类角色继承而来的角色属性的列表(信息性)。状态属性皆通过角色模型的父类角色继承,而非 DOM 树中的祖先元素继承。这些属性不会在角色上显式定义,继承会自动发生。该信息用于便于阅读本规范。所有可支持和继承的状态与属性合成该角色完整支持的状态与属性集。

5.2.5 被禁止的状态和属性

不允许在某角色上使用的状态与属性的清单。作者MUST NOT(不得)指定被禁止的状态或属性。

含有适当内隐 WAI-ARIA 语义的宿主语言属性也会禁止本节所述状态或属性。

5.2.6 允许的无障碍子角色

作为该角色无障碍子元素(简称“子项”)允许使用的角色清单。作者MUST(必须)仅为子元素指定被允许的角色。例如,具有 list 角色的元素只可以包含 listitem 角色的子项,而不能包含 option 角色的元素。

判断一个元素是否为另一个元素的子项时,用户代理MUST忽略所有 role 为 genericnone 的中间元素。

不是某元素直接子项的后代,不受“允许无障碍子角色”约束。例如 image 不是 list 的允许子项,但如果它位于 list 允许子项 listitem 下,则作为其后代是有效的。

拥有“允许无障碍子角色”的角色并不意味着反过来也成立。该表中列出的角色并不总是必须作为给定角色的子项出现。某角色应在何种上下文被包容,详见必需的无障碍父角色

拥有“允许无障碍子角色”子类角色的元素,不能满足本要求。例如 listbox 允许 optiongroup角色作为子项,虽然 grouprow 的父类,但 row 并不满足 listbox 要求的子项角色。

含有适当内隐 WAI-ARIA 语义的元素也满足本要求。

允许的无障碍子角色有效标记方式示例如下:

  1. 直接 DOM 子节点:
    <div role="listbox">
    	<div role="option">option text</div>
    </div>
  2. DOM 子节点,中间有 generic 元素:
    <div role="listbox">
    	<div>
    		<div role="option">option text</div>
    	</div>
    </div>
  3. 直接 aria-owns 关系:
    <div role="listbox" aria-owns="id1"></div>
    <div role="option" id="id1">option text</div>
  4. aria-owns 关系 + 中间 generic 元素:
    <div role="listbox" aria-owns="id1"></div>
    <div id="id1">
    	<div>
    		<div role="option">option text</div>
    	</div>
    </div>

5.2.7 必需的无障碍父角色

必需的无障碍父(parent)角色指定了该角色允许出现的容器。如果某角色有必需无障碍父角色,作者MUST确保带该角色的元素是带有必需无障碍父角色的父元素的无障碍子元素。例如,role 为 listitem 的元素仅在其父级为 list 时才有意义。

判断元素父级是否带必需角色时,用户代理MUST 忽略 role 为 genericnone 的所有元素。

拥有恰当内隐 WAI-ARIA 语义的元素亦满足本项要求。

5.2.8 可访问名称计算

可选值
以下之一:
  1. author:名称来自作者在显式标记特性中提供的值(如 aria-label 属性、aria-labelledby 属性,或宿主语言的标签机制,如 HTML 的 alttitle 属性,且 HTML title 优先级最低)。
  2. contents:名称来自元素节点的文本内容。部分角色允许同时使用 "author" 和该方式,但仅当无高优先级 "author" 特性时采用。优先级规则参见可访问名称与描述计算算法 [ACCNAME-1.2]。
  3. prohibited:该元素不允许通过作者指定名称。作者MUST NOT(不得)为元素使用 aria-labelaria-labelledby 属性。
5.2.8.1 名称计算

名称计算见可访问名称与描述规范。

5.2.8.2 描述计算

描述计算见可访问名称与描述规范。

5.2.8.3 可访问名称与描述计算

可访问名称与描述计算见可访问名称与描述规范。

5.2.8.4 支持作者自定义名称的角色
5.2.8.5 支持通过内容生成名称的角色
5.2.8.6 禁止通过名称命名的角色(禁止命名)

5.2.9 表现型子项

取值

布尔型(true | false

DOM 的后代节点为表现型。用户代理不应通过平台无障碍 API暴露本元素的后代。如果用户代理未隐藏这些后代节点,部分信息可能会被读两遍。

5.2.10 角色的隐式默认值

许多状态和属性都有默认值。有时,某个状态或属性用于特定角色时的默认值应与通常默认值不同。要求某状态或属性具有非常规默认值的角色会在“角色的隐式默认值”中说明。表达形式为 “状态或属性名称 的默认值为 新默认值”。这种角色如果作者没有显式设置该状态或属性,则采用新的默认值。

5.3 角色分类

为支持当前的用户场景,本规范将用于定义用户界面控件(如滑块、树控件等)以及页面结构(如区域、导航等)的角色划分为不同类别。请注意,部分辅助技术对带有 applicationdocument 角色的区域会提供特别的交互模式。

各角色之间关系的可视化描述可见于 ARIA 1.2 类图

角色按以下类别分类:

  1. 抽象角色
  2. 控件角色
  3. 文档结构角色
  4. 地标角色
  5. 动态区域角色
  6. 窗口角色

5.3.1 抽象角色

下列角色用于支持 WAI-ARIA 角色模型,以定义一般性角色概念。

抽象角色用于本体建设。作者不得在内容中使用抽象角色。

5.3.2 控件角色

如下角色可作为独立用户界面控件,也可以作为较大复合控件的一部分。

如下角色为复合用户界面控件,通常作为容器管理其它嵌套控件。

5.3.3 文档结构角色

下列角色用于描述页面内容的结构。文档结构通常不具交互性。

5.3.4 地标角色

下列角色为页面中的导航性地标区域。所有这些角色均继承 landmark 基类,并引用自 Role Attribute [ROLE-ATTRIBUTE]。列出这些角色,是为了明确它们属于 WAI-ARIA 角色模型。

5.3.5 动态区域角色

下列角色属于动态区域,可通过动态区域属性进行设置。

5.3.6 窗口角色

下列角色作为浏览器或应用程序中的窗口使用。

5.4 角色定义

以下为 WAI-ARIA 角色的按字母顺序列表。

抽象角色用于本体论。作者不得在内容中使用抽象角色。

alert
一种 动态区域,包含重要且通常具有时效性的信息。参见相关 alertdialogstatus
alertdialog
一种包含警告信息的对话框,初始焦点进入对话框内的元素。参见相关 alertdialog
application
一种structure,包含一个或多个可聚焦且需要用户输入的元素(如键盘或手势事件),这些输入并不遵循 widget 角色支持的标准交互模式。
article
页面中的独立组成部分,可以是文档、页面或站点中的一部分。
banner
一种landmark,主要包含站点相关内容,而非页面特定内容。
blockquote
引用自其他来源的内容部分。
button
允许用户点击或按下以触发操作的输入。参见相关 link
caption
用于指定或描述 figuregridgroupradiogrouptabletreegrid 的可见内容。
cell
表格容器中的单元格。参见相关 gridcell
checkbox
可勾选的输入,有三种可能的truefalsemixed
code
内容为代码片段的区域。
columnheader
包含列头信息的单元格。
combobox
可控制其他元素(如 listboxgrid)的input,这些元素可动态弹出,用于帮助用户设置该 input 的值。
command
执行某操作但不接收输入数据的控件类型。
comment
用于表达对其他内容反馈的内容。
complementary
一种landmark,其设计目的是补充同级或直系父级主要内容。即使与相关主内容分离,其内容仍应有意义。
composite
可包含可导航无障碍后代控件
contentinfo
包含关于父文档信息的landmark
definition
术语或概念的定义。参见相关 term
deletion
表示已删除、建议删除或对上下文内容已不相关内容的区域。参见相关 insertion
dialog
Web 应用主窗口的子窗口。对于 HTML 页面,主应用窗口为整个文档(即 body 元素)。
directory
[ARIA 1.2已弃用] 成员引用列表,如静态目录表。
document
包含内容的元素辅助技术用户可用“阅读模式”浏览此内容。
emphasis
一个或多个强调的字符。参见相关 strong
feed
可滚动的list,内含articles。滚动时可能向列表两端动态增减articles
figure
可感知的section,通常包含图形文档、图像、媒体播放器、代码片段或示例文本。figure 的部分内容被用户导航。
form
一个landmark区域,包含为实现表单功能组合而成的多个条目和对象。参见相关 search
generic
无语义含义的无名容器元素
grid
一种复合widget,包含一个或多行、每行含一个或多个单元格,其中部分或全部单元格可用如方向键的二维导航聚焦。
gridcell
gridtreegrid 中的cell
group
一组用户界面对象,不希望辅助技术将其纳入页面摘要或目录。
heading
页面区域的标题。
image
形成图片的一组元素的容器。参见同义词 img
img
形成图片的一组元素的容器。参见同义词 image
input
允许用户输入的控件的通用类型。
insertion
包含被标记为新增或建议新增内容的区域。参见相关 deletion
landmark
包含作者指定重要目的内容的可感知section,便于用户快速导航,通常会出现在页面概览。本概览可由用户代理或辅助技术动态生成。
link
指向内外部资源的交互式引用,被激活(点击)时用户代理将跳转到目标。参见相关 button
list
包含listitem元素的section。参见相关 listbox
listbox
允许用户从若干选项中选择一项或多项的控件。参见相关 comboboxlist
listitem
列表或目录中的单项。
log
一种 动态区域,新信息按有意义顺序添加,旧信息可消失。参见相关 marquee
main
包含文档主体内容的landmark
mark
用于标示或高亮内容以示参考或注释,因其在当前上下文中具有特别意义。
marquee
一种 动态区域,非核心信息频繁变化。参见相关 log
math
用于表示数学表达式的内容。
menu
为用户提供选项列表的一种控件
menubar
通常水平且始终可见的 menu 展示形式。
menuitem
menumenubar中的一个选项。
menuitemcheckbox
带可勾选状态的menuitem,可能truefalsemixed
menuitemradio
一组具有相同角色的可勾选menuitem中的单一被选项。
meter
表示已知范围内的标量数值或比例值的元素。参见相关 progressbar
navigation
包含导航性元素(通常为链接)的landmark,用于导航当前或相关文档。
none
其内置原生语义不会被映射为无障碍 API元素。参见同义词 presentation
note
内容补充主内容或为其提供附加语境的section
option
listbox中的一项。
paragraph
一个内容段落。
presentation
其内置原生语义不会被映射为无障碍 API元素。参见同义词 none
progressbar
用于显示耗时任务进度状态的元素
radio
一组具有相同角色的可选输入项,仅允许一个被选中。
radiogroup
一组radio按钮。
range
表示数值区间的元素。
region
包含作者指定重要目的内容的landmark
roletype
所有其他角色的基类角色
row
表格型容器中的一行单元格。
rowgroup
在表格容器中包含一个或多个行元素的结构。
rowheader
包含行头信息的单元格。
scrollbar
用于控制显示区域中内容滚动的图形对象,无论内容是否全部可见。
search
作为组合功能集合、整体上构成搜索区域的landmark。参见相关 formsearchbox
searchbox
用于输入搜索条件的文本框类型。参见相关 textboxsearch
section
页面上的一个可渲染结构单元。
sectionhead
用于标记或概述所属区域主题的结构。
select
允许用户在一组选项中做选择的表单控件。
separator
用于分隔和区分内容区块或菜单项组的分隔线。
slider
用户可从指定区间中选择值的输入。
spinbutton
一种range,需用户在若干离散选项中选择。
status
一种动态区域,内容为建议信息,但不重要到需要 alert。常见但非必须呈现为状态栏。
strong
表示重要、严肃或紧迫内容。参见相关 emphasis
structure
文档结构用的元素
subscript
一个或多个下标字符。参见相关 superscript
suggestion
文本内容的一条提议修改。
superscript
一个或多个上标字符。参见相关 superscript
switch
一种表示开/关状态(区别于选中/未选中)的复选框。参见相关 checkbox
tab
一组标签的分组选项,可用于选择希望呈现的内容区域。
table
包含以行和列排列数据的section。参见相关 grid
tablist
由若干tab 元素组成,引用tabpanel元素的列表。
tabpanel
承载与某tab相关资源的容器,每个tab存在于tablist中。
term
带有可选定义的单词或短语。参见相关 definition
textbox
允许自由文本输入的输入控件。
time
表示具体时点的元素。
timer
一种包含数值计数器的 动态区域,用于指示自起点经过的时间或到终点剩余的时间。
toolbar
以紧凑形式展示一组常用功能按钮或控件的集合。
tooltip
用于为某元素提供描述的上下文弹出提示。
tree
允许用户在分层集合中选一项或多项的 widget
treegrid
grid 的变体,其行可像 tree 一样展开或收起。
treeitem
tree 中的一个项目。
widget
图形用户界面(GUI)的交互组件。
window
浏览器或应用窗口。

alert role

一种动态区域,用于显示重要且通常具有时效性的信息。参见相关 alertdialogstatus

警告提示用于传达对用户可能立即重要的信息。对于音频警告,alert 为听障用户提供了无障碍的替代方案。alert 角色应应用于包含警告信息的元素上。alertstatus 角色的一种特例,会以原子方式处理为动态区域

alert 是“强制型”动态区域,意味着会立即通知辅助技术用户。如果操作系统允许,用户代理应当在创建 WAI-ARIA alert 时,通过无障碍API触发系统 alert 事件

无论是作者还是用户代理,都无需为 alert 元素设置或管理焦点,alert 同样会被正确处理。由于 alert 不要求接收焦点,作者不应要求用户关闭 alert。如果作者希望将焦点移动到提示信息,可以使用 alertdialog 代替 alert

带有 alert 角色的元素,aria-live 隐式值为 assertivearia-atomic 隐式值为 true

特性:
特性
父类角色: section
子类角色:
继承的状态和属性:
命名来源: author
角色的隐式默认值: aria-live 的默认值为 assertive
aria-atomic 的默认值为 true

alertdialog role

一种包含警告信息的对话框,初始焦点进入该对话框内的元素。参见相关 alertdialog

警告对话框用于向用户传达重要信息。alertdialog 角色 应用于包含警告信息和其它对话框内容的节点。内容作者应当确保 alertdialog 展示期间,鼠标和键盘操作只能在对话框内部进行,使对话框为模态。参见 aria-modal

alert 不同,alertdialog 可接收用户响应,例如确认用户已知晓消息。当弹窗出现时,作者应当将焦点移至对话框内的激活元素(如表单控件或确认按钮)。用户代理应当在创建 alert 时通过无障碍 API 触发系统 alert 事件(若目标无障碍 API支持)。

作者应当alertdialog 上使用 aria-describedby 指向弹窗内的警告消息元素。若未声明,辅助技术可使用其内部恢复机制确定提示内容。

特性:
特性
父类角色:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

application role

一种structure,包含一个或多个需要用户输入(如键盘或手势事件)但并不遵循 widget 角色所支持的标准交互模式的可聚焦元素。

部分用户代理辅助技术拥有浏览模式,标准输入事件(如上下箭头)被拦截用于控制阅读光标。这会导致不带 widget 角色的元素无法通过键盘或手势事件获得交互能力。

当需要创建一种不受任何WAI-ARIA widget角色支持的交互模型时,作者可以为该元素声明 application 角色。当用户进入带 application 角色的元素时,拦截标准输入事件的辅助技术应当切换为让标准输入事件直接传递给 Web 应用的模式。

例如,一个演示文稿幻灯片编辑器使用箭头键移动幻灯片上的文本框和图片。此类交互模型无对应WAI-ARIA widget角色,因此作者可以为幻灯片容器声明 role="application",用 aria-roledescription 定义为“Slide Editor”,并通过 aria-describedby 提供说明内容。

由于某些辅助技术用户仅能访问 application 内部的可聚焦元素,作者必须采用下述方法之一确保所有非装饰性的静态文本或图片可访问:

  1. 使用 aria-labelledbyaria-describedby,将内容与可聚焦元素关联。
  2. 将内容放在带 documentarticle 角色的可聚焦元素中。
  3. 焦点管理章节所述,管理无障碍后代的焦点,及时更新 aria-activedescendant 以指向包含焦点内容的元素
特性:
特性
父类角色: structure
支持的状态和属性:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

article role

页面中的一个区块,由内容组成,是文档、页面或站点的独立组成部分。

article 不是导航性地标,但可以嵌套用于表示讨论,辅助技术可利用嵌套结构帮助用户分辨讨论脉络。article 可为论坛帖、杂志/新闻文章、博客条目、用户评论等独立内容。其“独立性”体现在内容可单独分发(如被聚合)。但article元素始终关联其祖先结构,例如父元素的联系信息依然适用于 article​​。嵌套时,子 article 表示与父 article 内容相关的信息。比如,一个带评论的博客,评论可以作为主文章内嵌的 article。作者、标题、日期等元信息仅关联当前 article,不传递给嵌套 article。

当用户导航到被设为 article 的元素时,通常会拦截标准键盘事件的辅助技术应当切换到文档浏览模式,而不是将键盘事件传递给 Web 应用。有些辅助技术允许用户遍历嵌套的 article 层级。

article 出现在 feed 场景,作者可以设置 aria-posinsetaria-setsize

特性:
特性
父类角色: document
子类角色:
相关概念:
支持的状态和属性:
继承的状态和属性:
命名来源: author

blockquote role

一段引用自其他来源的内容区域。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
命名来源: author

button role

一种输入,可供用户点击或按下以触发操作。参见相关 link

按钮大多用于离散操作。规范化按钮的外观有助于用户识别这些控件为按钮,也便于工具栏内紧凑展示。

按钮支持可选属性 aria-pressed。若按钮 aria-pressed 属性非空,则该按钮为切换按钮。当 aria-pressedtrue 时按钮处于“已按下”状态;为 false 时未按下。如果未设置该属性,则为普通命令按钮。

特性:
特性
父类角色: command
基础概念: <button> in HTML
相关概念:
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author
是否要求可访问名称: True
子级表现型: True

caption role

用于命名或描述 figuregridgroupradiogrouptabletreegrid 的可见内容。

作者在使用 caption应当确保:

如果 caption 作为其所包含元素的可访问名称,作者应当为包含元素设置 aria-labelledby,指向 caption 角色元素。

<div role="radiogroup" aria-labelledby="cap">
   <div role="caption" id="cap">
     Choose your favorite fruit
   </div>
   <!-- ... -->

如果 caption 同时包含名称和描述,作者可以aria-labelledby 指向 caption 内作为名称的元素,再用 aria-describedby 指向描述性内容。

<div role="table" aria-labelledby="name" aria-describedby="desc">
   <div role="caption">
     <div id="name">Contest Entrants</div>
     <div id="desc">
       This table shows the total number of entrants (500) the
       contest accepted over the past four weeks.
     </div>
   </div>
   <!-- ... -->

如果 caption 作为长说明,或说明内容包含理解上重要的语义结构,作者可以aria-labelledby 指向 caption 内作为“名称”的元素,再用 aria-details 指向说明内容。

<div role="figure" aria-labelledby="name" aria-details="details">
  <!-- figure content here, such as a complex data viz SVG -->
   <div role="caption">
     <div id="name">Sales information for 20XX</div>
     <div id="details">
       This barchart represents the total amount of sales over the course
       of five years. <a href="...">Sales information for last year</a> can
       be reviewed, or you can overlay <button aria-pressed="false">previous year</button>
       information in this graphic.
     </div>
   </div>
   <!-- ... -->

如果 caption 只包含说明文本,没有适合作为容器元素可访问名称的文本,则可以使用 aria-labelaria-labelledby 提供可访问名称,而 caption 可以仅作为说明内容,被 aria-details 引用。

<div role="figure" aria-label="Sales information" aria-details="details">
  <!-- figure content here, such as a complex data viz SVG -->
   <div role="caption" id="details">
     This barchart represents the total amount of sales over the course
     of five years. <a href="...">Sales information for last year</a> can
     be reviewed, or you can overlay <button aria-pressed="false">previous year</button>
     information in this graphic.
   </div>
   <!-- ... -->
特性:
特性
父类角色: section
相关概念:
需要的无障碍父角色:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

cell role

表格容器中的一个单元格。参见相关 gridcell

作者必须确保带 元素role 为 cell 的元素是 rolerow 的元素的无障碍子项

特性:
特性
父类角色: section
子类角色:
基础概念: <td> in HTML
需要的无障碍父角色: row
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author

checkbox role

一个可勾选的输入,具有三种可能的truefalsemixed

aria-checked 属性表明 checkbox 的选中状态:已选中(true)、未选中(false),或一组元素中包含混合勾选与未勾选(mixed)。大多数复选框不使用 mixed 值,因此等效于布尔型复选框。

由于 HTML 原生复选框具有很强的语义,建议作者不要在 input type=checkbox 上使用 aria-checked,而应使用原生 checked 属性或 indeterminate IDL 属性分别指定“选中”或“混合”状态。

特性:
特性
父类角色: input
子类角色:
相关概念:
必需的状态和属性:
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author
是否要求可访问名称: True
子级表现型: True

code role

内容为代码片段的区域。

code 角色的主要作用是告知辅助技术内容为计算机代码,因此可能要采用特殊方式呈现,尤其是在语音合成方面。具体来说,屏幕阅读器和其它文本转语音工具应当优先使用全部标点朗读模式,确保诸如“-”等常用符号能被朗读出来。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

columnheader role

包含列标题信息的单元格。

columnheader 可用作表格或网格的列头,在饼图等数据可视化场景下也可以用于展现类似的数据关系

columnheader 和其对应列中的所有单元格之间建立结构关联。其结构等效于 HTML 中 scope 为 column 的 th 元素

作者必须确保带 元素rolecolumnheader 的元素为 row 角色元素的无障碍子项

columnheader 设置 aria-selected 状态不得导致用户代理自动将 aria-selected 状态下发到相关列下的所有单元格。作者可以根据具体应用决定是否这样联动。

columnheader 既可用于交互式网格,也可用于普通表格,但 aria-readonlyaria-required 只适用于交互式控件。因此,作者不应在从属于 tablecolumnheader 上使用这两个属性;除非元素属于 grid,用户代理不应辅助技术暴露上述属性。

由于单元格结构按行组织,没有唯一的“列容器”元素。某列其实就是各行中位于同一位置的 gridcell 集合。

: aria-disabled 用法说明

虽然目前支持 aria-disabled 属性,但将来版本计划禁止除 gridtreegrid 场景外,为 columnheader 设置该属性。

特性:
特性
父类角色:
基础概念: <th scope="col"> in HTML
需要的无障碍父角色: row
支持的状态和属性: aria-sort
继承的状态和属性:
命名来源:
  • contents
  • author
是否要求可访问名称: True

combobox role

一种input,可以控制其他元素如listboxgrid,用于动态弹出帮助用户设定input的值。

编辑者说明: ARIA 1.2 中 combobox 角色的重大变更

combobox 指南在 ARIA 1.2 里因之前模式实现的问题有重大调整。 用户代理、辅助技术和符合性校验工具的作者与开发者应认真阅读本节,充分了解变更内容。 变更说明详见 ARIA 仓库 wiki

combobox 功能上将一个具名输入框和用于辅助选择值的弹出补充元素组合在一起。 combobox 输入既可以是可编辑的单行文本框,也可以仅显示当前值的只读元素。 如果 combobox 支持文本输入且提供自动补全行为(见 aria-autocomplete),作者必须combobox 元素上设置对应行为的 aria-autocomplete 值。

通常 combobox 的初始状态为折叠。 折叠时,仅 combobox 元素和可选的弹出按钮可见。 当 combobox 展开时,则元素本身和弹出内容一同显示。 作者必须在展开时将 aria-expanded 设为 true,折叠时设为 false

作者必须确保与 combobox 关联的弹出层具有 listboxtreegriddialog 角色。 弹出层显示时,作者必须combobox 元素上用aria-controls 指向该弹出元素。

combobox 角色的元素隐式 aria-haspopup 值为 listbox。 若弹出层为其他角色,作者必须显式设定 aria-haspopup 为相应角色类型。

如果界面中有额外图标可用鼠标或触控控制弹出层显示,作者应当确保该图标的 role 为button,可聚焦但不进入 Tab 键序列,且不为 combobox 的 DOM 子元素。 为了提升键盘无障碍性,作者应当提供新焦点移动机制,实现 combobox 元素与弹出层内容的互转。 比如常见做法是 下箭头 可将焦点从输入移动到弹出层第一个可聚焦后代。 若弹出支持 aria-activedescendant,则焦点不变,仅更新 comboboxaria-activedescendant,引用弹出层内被激活项。 当弹出中某后代处于激活状态时,作者可以combobox 设置 aria-activedescendant,引用弹出层内对应项,且焦点始终留在 combobox

用户代理必须将带 combobox 角色元素的值曝露给辅助技术combobox 的值如下获取:

  • 如果 combobox 元素本身为如 HTML input 等本地宿主元素,则其值即作为组合框的值。
  • 否则,其值由后代元素内容决定,获取方式同 button 通过子内容获取名称的方式一致。
    <label id="tag_label" for="tag_combo">Tag</label>
  <input type="text" id="tag_combo"
      role="combobox" aria-autocomplete="list"
      aria-haspopup="listbox" aria-expanded="true"
      aria-controls="popup_listbox" aria-activedescendant="selected_option">
<ul role="listbox" id="popup_listbox" aria-labelledby="tag_label">
   <li role="option">Zebra</li>
   <li role="option" id="selected_option">Zoom</li>
</ul>
编辑者说明: ARIA 1.2 combobox 合规性变更

请仔细阅读。由于这些变更,依照 ARIA 1.1 combobox 规范实现的 combobox 已经不再符合规范。

本规范对 combobox 结构的要求和 ARIA 1.0、ARIA 1.1 均有不同:

  • ARIA 1.0 规范要求带 combobox 角色的输入必须是单行文本,并通过 aria-owns(而不是 aria-controls)引用弹出层。
  • ARIA 1.1 规范(未被主流辅助技术广泛支持)要求 combobox 必须为不可聚焦元素,且包含两个必须的无障碍子项——一个可聚焦 textbox 和一个由该 textbox 控制的弹出。
  • ARIA 1.2 的变更提升了与辅助技术的互通性,使作者更便于创建与原生 HTML select 更接近的 combobox 实现。

combobox 的特性和行为各异,具体实现考虑点较多。详细可参考 WAI-ARIA 实践指南中的模式设计说明。

特性:
特性
父类角色: input
相关概念:
必需的状态和属性: aria-expanded
支持的状态和属性:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True
角色隐式默认值: aria-haspopup 的默认值为 listbox

command role

一种执行操作但不接收输入数据的控件。

command抽象角色,用于本体模型。作者不得在内容中使用 commmand 角色。

特性:
特性
是否为抽象: True
父类角色: widget
子类角色:
继承的状态和属性:

comment role

评论用于表达对其它内容的反馈。

评论可用于标注任意可见内容:无论是一小段文本、其它评论,还是整个文章。作者应当按如下方式明确评论与被评内容间的关系:

  1. 如果该评论是对另一 comment 的回复:
    • 若所有上层评论都存在于 DOM 中,则每个回复 comment 都应作为其被回复 comment 的语义后代,可以是 DOM 后代元素,也可以用 aria-owns 指定。
    • 或者,如果部分或全部祖先评论不在 DOM 中(如分页评论),可用 aria-level 标明层级信息,aria-posinsetaria-setsize 可指示组内排序信息。
  2. 否则,若评论与页面其他内容相关:
    • 在被评论内容的元素上用 aria-details 指向评论 comment 元素。
    • 若同一内容下有多个评论,可为被评论内容的 aria-details 指向所有评论,或用 aria-details 指向评论的父容器。如果 aria-details 指向的不是 comment,作者应当为该容器赋予 groupregion 角色。

若作者未为 comment 显式声明 aria-levelaria-posinsetaria-setsize,用户代理必须自动推算缺失值并向辅助技术曝露。

特性:
特性
父类角色: article
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author

complementary role

一种landmark,用于补充主内容,可以作为兄弟节点或直接子节点。此类内容即使与主内容分离,也应当具有独立意义。

很多内容类型可适用此角色。如门户网站可包含演出时间、当前天气、相关新闻、待关注股票等。如果补充内容可完全脱离主内容,也可考虑更一般的角色。

辅助技术应当让用户能快速跳转带 complementary 角色的元素。 用户代理应当complementary 角色元素作为导航地标处理。 用户代理可以支持用户快速跳转到该角色元素。

特性:
特性
父类角色: landmark
相关概念:
继承的状态和属性:
命名来源: author

composite role

一种控件,可以包含可导航的无障碍后代

作者应当确保复合控件在页面整体导航系统里为一个独立的导航停靠点。当复合控件获得焦点后,作者应当为用户提供另一种导航机制,以便导航到作为该复合元素元素无障碍后代

composite抽象角色,用于语义建模。作者不得在内容中使用 composite 角色。

特性:
特性
是否为抽象: True
父类角色: widget
子类角色:
支持的状态和属性:
继承的状态和属性:

contentinfo role

一种landmark,包含关于父文档的信息。

本区域常见内容示例包括版权声明、隐私政策链接等。

辅助技术应当让用户能快速跳转到带 contentinfo 角色的元素。 用户代理应当contentinfo 元素作为导航地标进行处理。 用户代理可以支持用户快速跳转到此类元素。

作者应当避免在同一页面为多个元素指定 contentinfo 角色。

由于 documentapplication 元素可以在 DOM 中嵌套,每个DOM分支下都可以有各自的 contentinfo,只要它们关联的是不同的文档节点。这可以靠 DOM 嵌套(如 document 内嵌 document)或使用 aria-owns 属性实现。

特性:
特性
父类角色: landmark
相关概念:
继承的状态和属性:
命名来源: author

definition role

术语或概念的定义。参见相关 term

作者必须明确被定义的元素,并为其分配 term 角色。

作者不应在如表单控件等交互元素上使用 definition 角色,否则可能导致辅助技术用户无法与这些元素交互。

特性:
特性
父类角色: section
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

deletion role

删除内容用于标记被移除、建议移除,或在其伴随内容语境下已不再相关的内容。参见相关 insertion

删除通常用于对比内容的两个版本差异,或多人修订时标记建议移除的内容。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

dialog role

对话框是 Web 应用主窗口的子窗口。对于 HTML 页面,主应用窗口指整个 Web 文档,即 body 元素。

对话框通常用于提示用户输入信息或做出响应。用于打断用户流程的对话框通常为模态对话框。参见相关 alertdialog

作者必须为对话框提供可访问名称,可使用 aria-labelaria-labelledby 属性实现。

作者应当确保所有对话框(无论模态或非模态)至少包含一个可聚焦后代元素。作者应当在模态对话框显示时将焦点设置在内部元素,并应当管理模态对话框的焦点。

本角色说明中的“Web 应用”并不指 application 角色,该角色描述的是具体的辅助技术行为。

特性:
特性
父类角色: window
子类角色:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

directory role

[ARIA 1.2中已弃用] 一组群组成员的引用列表,如静态目录表。

从无障碍 API 的角度来看,directory 角色与 list 角色本质上等价。因此,使用 directory 对辅助技术用户没有额外好处。建议作者将 directory 视为已弃用,使用 list 或宿主语言等价语义代替。

directory 是静态目录表,不论是否带有链接。包括用列表(及嵌套列表)构建的目录表。动态生成的目录可考虑用 tree 角色。

特性:
特性
父类角色: list
继承的状态和属性:
命名来源: author

document role

包含内容的元素辅助技术用户可能希望以阅读模式浏览。

用户代理的焦点移到带有 document 角色的元素时,具有静态内容阅读模式的辅助技术可以切换到对应阅读模式,并拦截标准输入事件(如上下箭头),用于控制阅读光标。

由于具有阅读模式的辅助技术,默认会对除 widgetapplication 角色外的所有元素启用该模式,所以 document 角色只有在它是 widgetapplication 的可聚焦子元素时才有意义。举例来说,当一个 application 元素包含一些静态富文本,作者可为该内容元素声明 role="document" 并设置 tabindex0。当屏幕阅读器使用 Tab 键聚焦到 document 元素后,用户即可用阅读光标浏览内容。

特性:
特性
父类角色: structure
子类角色:
继承的状态和属性:
命名来源: author

emphasis role

一段或多个强调字符。参见相关 strong

emphasis 角色用于强调内容,仅当强调缺失会影响内容含义时应当使用,而不是单纯用于表现上的字体变化。

emphasis 角色不是用来表达重要性的,表达重要性应使用 strong 角色。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

feed role

一个可滚动的list,其下所有子项为article,滚动时可能会在列表两端动态添加或移除article

feed 让具备文档浏览模式的辅助技术(如屏幕阅读器)用户可以用阅读光标滚动和阅读无限加载的丰富内容流。在 feed 中,辅助技术通过切换用户代理焦点,将用户的阅读光标动作信号传递给 Web 应用,使应用能够根据浏览情况动态添加内容并调整其展示位置。同时,feed 让作者可以在有新内容添加或移除时通知辅助技术,便于辅助技术及时、平滑地响应内容变更而不打断用户阅读或降低性能。

例如,feed 可用于展示新闻流,每个article内包含文本、链接、图片、评论、分享和评论等小部件。屏幕阅读器用户在阅读或交互时,每条新闻会滚动到可见区,且根据需求动态加载新内容。

feed 是一个容器元素,其所有子元素的角色为 article。针对 feed 两端的 article 动态增删,作者应当在变动前为 feed 设置 aria-busytrue,变动完成后设为 false。作者应当避免在 feed 中间插入或删除 article。这样有助于辅助技术平滑应对内容变更。

作者应当使 feed 中每个 article 可聚焦,并确保当用户代理焦点移至 article或其后代时,应用能将其滚动入视图。例如在 HTML 中,应为每个 articletabindex="-1"tabindex="0"

辅助技术阅读光标从一个 article 移到另一个时,辅助技术应当article 设为焦点;如果焦点落在 article 的可聚焦后代,则可直接焦点于该后代。

由于要通过阅读光标滚动到另一个 article 依赖页面中存在其他 article,作者应当在焦点到达已加载内容集合两端 article 前,尝试预加载更多内容。或者,作者可以在集合两端插入一个含有如 buttonarticle,让用户主动加载更多内容。

除设置简短标签外,作者可以feedarticle 元素指定 aria-describedby,为屏幕阅读器指明导航时标签后应朗读的内容。屏幕阅读器可以在按 article 导航时同时播报标签和可访问描述,让用户能直接略过重复或次要内容。

作者应当feed 内的 article 提供键盘切换焦点的机制,便于不依赖辅助技术的用户也能用键盘导航。

feedarticle 数量为静态时,作者可以在子元素设置 aria-setsize 来说明集合大小。若总数极大、不确定或经常变化,作者可以aria-setsize 设为 -1 表示集合大小未知。

详见 WAI-ARIA Authoring Practices 获取 feed 设计模式的更多信息。

特性:
特性
父类角色: list
允许的无障碍子角色: article
继承的状态和属性:
命名来源: author

figure role

一个可感知的section,通常包含图形文档、图片、媒体播放器、代码片段或示例文本。figure 的各部分可以被用户导航。

作者应当在正文中引用 figure,但 figure 不必出现在引用位置。作者可以figure 添加 caption,其内容可作为名称、描述文本或两者。如果提供 caption 且其为 figure 的描述,作者应当aria-details 关联。

作者可以aria-label 为 figure 提供可访问名称,或用 aria-labelledby 引用页面其他文本作为其标签和访问名。

更多关于如何将 figurecaption 关联的信息,请参见 caption 角色。

辅助技术应当让用户能快速跳转 figure。用户代理可以让用户快速跳转 figure。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
命名来源: author

form role

一种landmark,其区域包含一组项目和对象,整体组合成一个表单。参见相关 search

form 可以包含原生表单控件、脚本控件和超链接的组合。建议作者优先使用原生语义创建表单控件。如果表单目的是提交搜索内容,作者应当优先用 search 角色,不用通用 form 角色。

作者必须给每个 role="form" 的元素提供简短说明,描述表单目的。如果存在可见标签,作者应当aria-labelledby 引用该标签。作者应当尽可能将标签放入标题,标题可以是标准 HTML 标题元素或者 role=heading 元素。

如果作者用脚本通过非传统 onsubmit 行为提交表单(如值变化即提交),应当提前提示用户该行为。

辅助技术应当让用户快速跳转至 form 角色元素。用户代理应当把带可访问名的 form 角色元素作为导航地标处理。用户代理可以让用户快速跳转这些元素。

特性:
特性
父类角色: landmark
基础概念: <form> in HTML
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

generic role

一个无语义、无名称的容器元素

generic 角色主要作为宿主语言中通用元素(如 HTML divspan)的隐式角色,主要面向用户代理实现。作者不应在内容中使用该角色。作者可以通过 presentationnone 移除隐式无障碍语义,或用 group 等具名容器组语义包裹后代进行分组。

presentation 角色类似,generic 元素可以为其后代指定有限无障碍状态或属性,例如 aria-live

但与 presentation 不同,当设置了允许的无障碍属性时,用户代理会通过无障碍 API正式暴露 generic 元素。否则用户代理可以直接忽略该元素。

特性:
特性
父类角色: structure
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

grid role

一个复合的 widget,包含一个或多个行的集合,每行包含一个或多个单元格,网格中的某些或所有单元格可以通过二维导航方法(例如方向箭头键)获得焦点。

grid 角色并不暗示特定的视觉呈现(例如表格呈现)。它描述了 元素之间的关系。它可以用于诸如对一组复选框或导航链接进行分组这样简单的用途,也可以用于创建功能齐全的电子表格应用程序等复杂用途。

一个 grid 的单元格元素具有 gridcell 角色。作者 MAY 可将单元格指定为行或列标题,使用 rowheadercolumnheader 角色来替代 gridcell 角色。作者 MUST 必须确保具有 gridcellcolumnheaderrowheader 角色的元素是具有 row 角色的元素的可访问性子项,而这些 row 又是具有 rowgroupgrid 角色的元素的可访问性子项。

为了实现键盘可访问性,作者 SHOULD 应按照 Managing Focus 中的描述来管理 grid 的后代的焦点。当用户使用键盘在 grid 内容中导航时,作者 SHOULD 应按如下方式设置焦点:

  • 如果某个 gridcell 包含一个单一的交互式 widget,且该控件在获得焦点时不会消费箭头键的按键,例如 checkboxbuttonlink,作者 MAY 可以将焦点设置在该单元格中包含的交互元素上。这允许包含的控件可被直接操作。
  • 否则,作者 SHOULD 应确保接收焦点的元素是 gridcellrowheadercolumnheader 元素。

如果可聚焦的 gridcell 包含下列任一项,作者 SHOULD 应提供一种切换到交互或编辑模式的机制,以便用户能够在该单元格内部导航并与其中的内容交互:

  • 需要使用方向键操作的控件,例如 comboboxradiogroup
  • 多个交互式元素
  • 可编辑内容

例如,如果电子表格中的某个单元格包含 combobox 或可编辑文本,当该单元格获得焦点时,可能会使用 Enter 键激活单元格交互或编辑模式,以便使用方向箭头键来操作包含的 comboboxtextbox。根据实现,可能再次按 EnterTabEscape 或其他键将应用切换回网格导航模式。

作者 MAY 可以使用 gridcell 显示公式的结果,该结果可能由用户编辑。例如在电子表格应用中,一个 gridcell 可能会显示由公式计算出的值,直到用户激活该 gridcell 进行编辑,此时该单元格中会出现一个 textbox,使其进入可编辑状态。

如果在具有 grid 角色的元素上设置了 aria-readonlyuser agents MUST 必须将该值传播到属于该 grid 的所有作为可访问性后代的 gridcell 元素,并在可访问性 API 中暴露该值。作者 MAY 可以覆盖单个 gridcell 元素的 aria-readonly 的传播值。

在提供单元格内容编辑功能的 grid 中,如果可聚焦的 gridcell 元素的内容不可编辑,作者 MAY 可以在该 gridcell 元素上将 aria-readonly 设置为 true。然而,不论是在 grid 还是单个单元格上指定的 aria-readonly 的值,仅表示单元格中包含的内容是否可编辑。它并不表示用于导航或操作 grid 本身的功能是否可用。

未指定的 aria-readonly 值并不意味着 gridgridcell 包含可编辑内容。例如,如果 grid 展示的是不可编辑元素的集合,例如表示日期的 link 元素集合(如日期选择器中的日期),作者就无需为 aria-readonly 指定一个值。

作者 MAY 可使用 gridcellaria-selected 属性来指示可聚焦的 gridcell 可被选择作为一个操作对象。如果 grid 允许多个 gridcell 被选择,作者 SHOULD 应在具有 grid 角色的元素上将 aria-multiselectable 设置为 true

由于 WAI-ARIA 可以增强宿主语言的元素,grid 可以重用原生表格元素和属性,例如 HTML 的 table 元素。例如,如果作者将 grid 角色应用到一个 HTML table 元素上,作者就不需要将 rowgridcell 角色应用到后代的 HTML trtd 元素,因为 user agent 会自动进行适当转换。当作者在重用原生宿主语言的表格元素并需要一个 gridcell 元素跨越多行或多列时,作者 SHOULD 应该使用相应的宿主语言属性而不是 WAI-ARIA 的 aria-rowspanaria-colspan 属性。

有关实现网格设计模式的更多细节,请参阅 WAI-ARIA Authoring Practices

特性:
特性
父类角色:
子类角色:
基础概念: <table> in HTML
允许的无障碍子角色:
支持的状态和属性:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

gridcell role

gridtreegrid中的一个cell

gridcell 可以获得焦点、可编辑、可选中。gridcell 可以通过 关系属性aria-controls 建立功能关系。

如果某gridcell应当有行头、列头或二者,且不能通过 DOM 结构自动判断,作者应当通过aria-describedby引用相应rowheadercolumnheader元素。

treegrid中,作者可以通过aria-expanded属性定义gridcell是否可展开。该属性仅作用于单个单元格,不代指容器row,两者都可以展开。主要用途为数据透视表。

作者必须确保带有gridcell角色的元素是row角色元素的无障碍子项。

特性:
特性
父类角色:
子类角色:
基础概念: <td> in HTML
需要的无障碍父角色: row
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author

group role

一组用户界面对象辅助技术通常不会在页面摘要或目录中展示这些对象。

region对比,后者会将对象组纳入目录。

作者应当groupwidget中的逻辑集合分组,如树组件中的兄弟分组。但在listbox中使用group时,必须只包含option元素。因此group的正确用法需视语境而定。

作者可以嵌套group。如果某分区足够重要需要出现在页面目录中,应当赋予region或标准地标角色。

特性:
特性
父类角色: section
子类角色:
相关概念:
支持的状态和属性:
继承的状态和属性:
命名来源: author

heading role

页面分区的标题。

为确保heading角色的元素组成逻辑大纲,作者必须使用aria-level属性指明正确的标题层级。

特性:
特性
父类角色: sectionhead
相关概念:
必需的状态和属性: aria-level
继承的状态和属性:
命名来源:
  • contents
  • author
是否要求可访问名称: True

image role

一个包含组成图片的元素集合的容器。参见同义词img

关于 ARIA 1.3 image 角色的说明。

image 角色在 ARIA 1.3 版本中被加入,作为 ARIA 1.0 的 img 角色的同义词。image 角色提升了与其它角色命名的语法一致性,其它角色命名也是完整单词或完整单词组合而成。

img role

一个包含组成图片的元素集合的容器。参见同义词image

img 可以包含标题及描述性文本,也可以包含多个图片文件,这些图片组合在一起呈现为一张整体图片。一个 img 代表文档中的一张图像,无论它是否由多个绘制对象组成。 为使带有 img 角色的元素可被感知,作者必须为该元素提供可访问名称。可通过 aria-labelaria-labelledby 属性实现。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True
子项可表现化: True

input role

一种允许用户输入的通用控件类型。

input 是一个用于本体论的抽象角色。作者不得在内容中使用 input 角色。

特性:
特性
是否为抽象: True
父类角色: widget
子类角色:
支持的状态和属性: aria-disabled
继承的状态和属性:

insertion role

插入内容用于标记为新增或建议新增的内容。参见相关 deletion

插入通常用于对比内容的两个版本差异,或多人修订时标记建议新增的内容。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

landmark role

一个可感知的section,其中内容针对特定的作者指定目的并具有足够重要性,因此用户很可能希望能便捷导航到该分区,并在页面汇总中看到。这样的页面汇总可以由用户代理或辅助技术动态生成。

landmark 是用于本体论的抽象角色,作者不得在内容中使用。

作者通过赋予内容 landmark 子类角色,并在需要时提供简短描述性标签,来指定内容用途。

带有 landmark 子类角色的元素称为 landmark 区域或导航地标区。

辅助技术应当让用户能快速导航到 landmark 区域。用户代理可以让用户快速跳转至 landmark 区域。

特性:
特性
是否为抽象: True
父类角色: section
子类角色:
继承的状态和属性:

list role

一个section,包含 listitem 元素。参见相关 listbox

列表的子元素的 role 必须为 listitem

特性:
特性
父类角色: section
子类角色:
基础概念:
  • <ol> in HTML
  • <ul> in HTML
允许的无障碍子角色: listitem
继承的状态和属性:
命名来源: author

listbox role

一种控件,允许用户从一组选项中选择一个或多个。参见相关 comboboxlist

列表内的选项是静态的,与标准的 HTML select 元素不同,可以包含图片。Listbox 的内容必须为 option,或 group 角色元素(其下必须依然为 option)。

要实现键盘可访问性,作者应当按“焦点管理”要求管理 option 后代的焦点。

listbox 角色的元素,其 aria-orientation 隐式默认值为 vertical

特性:
特性
父类角色:
相关概念:
允许的无障碍子角色:
支持的状态和属性:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True
角色隐式默认值: aria-orientation 的默认值为 vertical

listitem role

列表或目录中的一项。

作者必须确保 元素rolelistitem 时,无障碍父元素role 必须为 list

特性:
特性
父类角色: section
子类角色:
基础概念: <li> in HTML
需要的无障碍父角色:
支持的状态和属性:
继承的状态和属性:
命名来源: author

log role

一种实时区域,新信息按照有意义的顺序添加,旧信息可以消失。参见相关 marquee

示例包括聊天记录、消息历史、游戏日志或错误日志。与其他实时区域不同,本角色下新项的到达和阅读顺序之间存在明确的关系。log 中信息严格顺序添加,新的信息只会增加到末尾,不会在任意位置插入。

log 角色的元素其 aria-live 的隐式值为 polite

特性:
特性
父类角色: section
继承的状态和属性:
命名来源: author
角色隐式默认值: aria-live 的默认值为 polite

main role

一种landmark,用于包含文档的主要内容。

此区域标记与文档中心主题直接相关或对其进行扩展的内容。main role 是 “跳到主要内容”链接的非侵入性替代方案——跳转到主内容(或其它地标)的功能可由辅助技术用户代理或浏览器扩展通过快捷键或UI(如侧边栏或对话框)提供。

辅助技术应当让用户能快速跳转到 role="main" 的元素。 用户代理应当把 role="main" 的元素作为导航地标处理。 用户代理可以让用户快速跳转到 role="main" 的元素。

作者应当确保页面上最多只有一个元素被标记为 main 角色。

由于documentapplication元素在DOM中可以嵌套,每个DOM分支下都可以有各自的main,只要它们关联的是不同的文档节点。这可以通过DOM嵌套(如document内嵌document)或通过aria-owns属性实现。

特性:
特性
父类角色: landmark
相关概念:
继承的状态和属性:
命名来源: author

mark role

因内容在当前上下文中的相关性而被标记或高亮,以供参考或标注的内容。

mark 的常见用途包括:

  • 突出显示引用中特别感兴趣但原始来源未标记的文本,可类比使用荧光笔标记纸质文章段落。
  • 标明与用户当前活动相关的内容部分,例如高亮搜索出的文本匹配项。

作者不应mark 用于纯装饰性样式,如语法高亮。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

marquee role

一种实时区域,其中非必要信息频繁变化。参见相关 log

marquee 的常见用途包括股票行情滚动条、广告横幅。与 log 角色的主要不同在于:log 往往对内容变化有有序或重要的顺序结构。

marquee 角色的元素其 aria-live 隐式值为 off

特性:
特性
父类角色: section
继承的状态和属性:
命名来源: author

math role

表示数学表达式的内容。

math 角色的内容建议使用可访问格式标记,如 MathML [MathML3],或用 TeX、LaTeX 等文本表达,经原生浏览器实现或 polyfill 库转换为可访问格式。

虽然用图片表达式不是最佳方案,但网上有大量历史内容使用图片表示数学公式。作者应当为这种图片提供描述性文本,用于表达数学含义的语音描述。

原生支持MathML的浏览器可以为数学内容提供比纯文本近似更完善可访问体验。有些渲染引擎与屏幕阅读器深度集成,支持公式空间触摸探索及 Nemeth 盲文刷新输出。这类集成图片始终不能实现,即便附带纯文本近似。

截至目前,一些主流浏览器并不原生支持MathML,需用 JavaScript polyfill 兼容。创作时应优先使用原生MathML,并认真测试。如有必要,再用 polyfill 或提供文字近似的图片备选方案。

MathML 内嵌 TeX 注释示例

<!-- 注: 对于不支持 MathML 的用户代理,请使用 JavaScript polyfill 保证正确渲染。 -->
<!-- math 元素隐含 role="math" -->
<math xmlns="http://www.w3.org/1998/Math/MathML">
  <mrow>
    <mi>x</mi>
    <mo>=</mo>
    <mfrac>
      <mrow>
        <mo form="prefix"></mo>
        <mi>b</mi>
        <mo>±</mo>
        <msqrt>
          <msup>
            <mi>b</mi>
            <mn>2</mn>
          </msup>
          <mo></mo>
          <mn>4</mn>
          <mo>&#x2062;<!-- &InvisibleTimes; --></mo>
          <mi>a</mi>
          <mo>&#x2062;<!-- &InvisibleTimes; --></mo>
          <mi>c</mi>
        </msqrt>
      </mrow>
      <mrow>
        <mn>2</mn>
        <mo>&#x2062;<!-- &InvisibleTimes; --></mo>
        <mi>a</mi>
      </mrow>
    </mfrac>
  </mrow>
  <annotation encoding="TeX">
    x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}
  </annotation>
</math>

原生HTML或Polyfill DOM下MathML二次公式结果

若渲染引擎不支持原生数学格式(如MathML),作者可以使用JavaScript将内容降级为浏览器可显示格式,如下述HTML图片及纯文本替代。

<img role="math" src="..." alt="x=⟮−b±√⟮b²−4ac⟯⟯÷2a">
特性:
特性
父类角色: section
继承的状态和属性:
命名来源: author

meter role

表示在已知范围内的标量度量或分值的元素。参见相关 progressbar

作者可以设置 aria-valueminaria-valuemax,用以指明meter的最小值和最大值。否则其默认值的规则与HTML的 <input type="range"> 一致:

  • aria-valuemin 缺失或不是数值,默认为0。
  • aria-valuemax 缺失或不是数值,默认为100。

aria-valuenow 的值不得小于 aria-valuemin 或大于 aria-valuemax 的计算值。

作者不应meter 角色表示进度,应使用 progressbar 角色。

目前,WAI-ARIA 没有与HTML <meter>lowoptimumhigh属性对应的属性。这些属性的补充会在ARIA 1.3中被考虑。

特性:
特性
父类角色: range
相关概念:
必需的状态和属性: aria-valuenow
继承的状态和属性:
命名来源: author
是否要求可访问名称: True
子项可表现化: True
角色隐式默认值: aria-valuemin 的默认值为 0
aria-valuemax 的默认值为 100

none role

元素的隐式原生角色语义不会被映射到无障碍API。参见同义词 presentation

关于 ARIA 1.1 none 角色的说明。

在 ARIA 1.1 中,工作组将 none 作为 presentation 角色的同义词引入,是由于作者对“presentation”含义理解有歧义。许多人误认为 role="presentation" 等同于 aria-hidden="true",因此 role="none" 更清晰直接。

该角色适用于:当元素用以改变页面外观,但无交互、结构意义,或用来为不支持 WAI-ARIA 的旧浏览器提供可访问的降级。

示例用法:

  • 完全用于表现的元素(如占位图片、装饰图形、清除浮动div);
  • 图片位于带 img 角色的容器内且已有完整文本替代,并用 aria-labelledby 及(如需)aria-describedby 标注的场景;
  • 作为 CSS 附加钩子的元素;
  • 布局用表格及其关联行、单元格等。

对于任何带none/presentation角色且不可聚焦的元素,用户代理不得向无障碍API暴露其原生隐式语义(角色及其属性)。但必须暴露内容和所有未显式声明none/presentation角色的后代。因此,该角色导致元素自身无角色或被移出无障碍树,但不影响其中内容被暴露。

例如,以下两个标记片段对无障碍API暴露结果类似:

<!-- 1. role="none" 消除了标题元素的隐式 heading 语义,但不会影响其内容,包括内部链接。 -->
<h1 role="none"> Sample Content <a href="...">let's go!</a> </h1>

<!-- 2. span 没有隐式角色,无重要无障碍属性,仅暴露内容及其子链接。 -->
<span> Sample Content <a href="...">let's go!</a> </span>

在HTML中,<img> 元素无论图片类型都被视为整体。因此HTML上设置 role="none"role="presentation",等价于 aria-hidden="true"。如要让图片内容可访问,可用 <object><iframe> 元素或内联SVG,并按图像内容可访问原则处理。

作者不应为应用 none/presentation 角色的图片提供有意义的文本替代(如在HTML中用 alt="")。

下例中,容器 img 已由标题段落妥善标注。在该场景下,可以将 img 元素设为 none/presentation,由容器承担角色与文本替代。

<div role="img" aria-labelledby="caption">
  <img src="example.png" role="none" alt="">
  <p id="caption">A visible text caption labeling the image.</p>
</div>

下例中,锚点(HTML a 元素)作为treeitem,列表项(li)被设置为 none/presentation 以覆盖其原生语义。

<ul role="tree">
  <li role="none">
	<a role="treeitem" aria-expanded="true">An expanded tree node</a>
  </li>
  …
</ul>
表现性角色继承

none/presentation 主要用于带有默认无障碍API角色语义的元素。有些元素只有配合特定子项才语义完整,如HTML中 table 元素需有 tr(隐式 row 角色),而 tr 又需有 thtd(分别为 columnheaderrowheadercell 角色)。同样,列表需有子项。WAI-ARIA文档称此类补全语义的子项为“允许的无障碍子角色”。

如果将 none/presentation 角色显式或继承应用到带有隐式WAI-ARIA角色、且要求“允许的无障碍子角色”的元素上,则用户代理必须也为所有无显式角色声明的无障碍后代添加继承的none角色;对于原生要求特定子元素的标签,也需要为这些无显式角色的子项继承none角色。

任何带显式/继承 none/presentation 且不可聚焦的元素,用户代理必须忽略其所有特有的无障碍属性。例如在HTML中,ulol 带有 none/presentation 时,其 li 的原生意义也会被移除;同理,tabletheadtbody 等后代的结构语义也会被移除。

只有与WAI-ARIA “允许的无障碍子角色”对应的隐式语义会被移除,其它内容不受影响(包括嵌套表格、嵌套列表,除非这些元素也被设为none/presentation)。

比如,根据无障碍API,下列标记会有相同或非常接近的(generic或none)角色与内容:

<!-- 1. [role="none"] 移除了 'list' 和 'listitem' 隐式语义,不影响内容。 -->
<ul role="none">
  <li> Sample Content </li>
  <li> More Sample Content </li>
</ul>

<!-- 2. "foo" 无隐式角色,仅暴露内容。 -->
<foo>
  <foo> Sample Content </foo>
  <foo> More Sample Content </foo>
</foo>

还有其它角色(如 feed、listbox)与特定子项有此继承关系,但表格和列表最常见。

对于带显式或继承 none/presentation 角色的元素,用户代理必须将该角色继承到所有标签相关的标注元素(如tablecaption),使该label也去除原生语义。

编辑注

有关none/presentation角色冲突的解决说明已移至处理作者错误

特性:
特性
父类角色: structure
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

note role

一个section,其内容为补充主内容的额外信息或括注上下文。

note由页面或文档作者提供,不应用于反馈或建议。要实现这类用途,请查看commentsuggestion

在页面内容正常流中使用时,note会隐式与它补充的内容关联。下例展示了如何用note在页面自然阅读顺序中补充信息:

<p>... 下列结果展示了所测特性的支持情况。</p>
<div role="note">
  <p>请注意,本页发布时所有结果均准确。</p>
  <p>如发现结果有差异,欢迎告知我们!</p>
</div>
<p>...</p>

如果某个role为note的元素需要通过编程方式与其补充内容关联,作者可用如下方式关联:

  • note内容为结构化或交互内容(如链接、按钮、列表、表格等),使用aria-details
  • note为简短纯文本,使用aria-describedby
 <!-- 使用 aria-details 关联含有链接的 note -->
 ...
<button aria-details="info-note">开始使用</button>
...
<div role="note" id="info-note">
  <p>需要更多信息?</p>
  <p>请访问我们的<a href="...">产品介绍页面</a>获取所需信息。</p>
</div>
特性:
特性
父类角色: section
继承的状态和属性:
命名来源: author

option role

listbox中的一项。

作者必须确保 元素roleoption 时,是 rolelistbox 的元素,或为 group 且其本身为 rolelistbox 的无障碍子项,否则这个option可能无法被正确映射到无障碍API

在一定条件下,用户代理可以为listbox中的每个option提供aria-selected隐式值。如果提供,则必须满足以下条件:

  • listbox上的aria-multiselectablefalse或未定义。
  • 该listbox内所有option元素都没有显式声明aria-selectedaria-checked

若用户代理为option提供了隐式aria-selected值,当该option获得DOM焦点、或listbox获得焦点且通过aria-activedescendant引用该option时,该值应当true。否则,隐式值应为false

作者应当通过以下方式之一为option元素指示选中状态:

  • 单选listbox中,用aria-selected标记已选option为true,未选可选为false
  • 多选listbox中,用aria-selectedaria-checked标识选中选项为true,未选为false

除非满足全部下列极少见条件,作者不应同时指定同一listbox下的option的aria-selectedaria-checked

  • UI中aria-selected的含义与aria-checked不同且目的不同。
  • 用户界面让每个状态的含义和用途非常明确。
  • UI为控制每个状态分别提供方法。
特性:
特性
父类角色: input
子类角色:
基础概念: <option> in HTML
相关概念:
需要的无障碍父角色:
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author
是否要求可访问名称: True
子项可表现化: True

paragraph role

一段内容。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

presentation role

其隐式原生角色语义不会被映射到无障碍API元素。参见同义词 none

关于 ARIA 1.1 none 角色的说明。

ARIA 1.1 中,工作组引入 none 作为 presentation 的首选同义词,因为“presentation”一词含义容易引起误解。很多人误把 role="presentation" 理解为 aria-hidden="true",ARIA工作组认为 role="none" 更清晰。

progressbar role

用于显示耗时任务的进度状态的元素

进度条表示用户的请求已被接收,应用正在向完成所请求的操作推进。

作者可以设置 aria-valueminaria-valuemax 用于指示进度指示器的最小和最大值。否则它们的隐式值遵循HTML中 <input type="range"> 的相同规则:

  • 如果 aria-valuemin 缺失或不是数字,则默认为0。
  • 如果 aria-valuemax 缺失或不是数字,则默认为100。

作者应当aria-valuenow 提供,除非该值不可确定,此时作者应当省略 aria-valuenow 属性。当可视进度条发生更新时,作者应当同步更新该值。如果progressbar描述的是页面某区域的加载进度,作者应当aria-describedby引用进度条状态,并在该区域完成加载前,将aria-busy设置为 true。用户无法更改progressbar的值,因为它始终为只读。

辅助技术通常会将 aria-valuenow 的值渲染为该范围(由aria-valueminaria-valuemax确定)内的百分比,除非指定了aria-valuetext

特性:
特性
父类角色:
相关概念:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True
子项可表现化: True
角色隐式默认值: aria-valuemin 的默认值为 0
aria-valuemax 的默认值为 100

radio role

同组元素中只能有一个被选择的可勾选输入框(单选框)。

作者应当确保带有radio角色的元素被明确分组,以指明它们影响相同的取值。这通过把这些单选元素包裹在 radiogroup 元素中实现。如果没法让单选按钮成为 radiogroup 的 DOM 子节点,作者应当radiogroup 元素上用 aria-owns 属性声明与其子项的关系。

特性:
特性
父类角色:
相关概念:
必需的状态和属性:
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author
是否要求可访问名称: True
子项可表现化: True

radiogroup role

一组 radio 单选按钮。

radiogroup 是一种 select 列表类型,一次只能有一个选项被选中。作者应当确保同组中只能有一个单选按钮被选中。当某一项被选中时,先前被选中的项会变为未选中(其 aria-checked 属性变为 false)。

特性:
特性
父类角色: select
相关概念: list
支持的状态和属性:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

range role

表示取值范围的元素。

range 是用于本体描述的抽象角色。作者不得在内容中使用 range 角色。

特性:
特性
是否为抽象: True
父类角色: structure
子类角色:
支持的状态和属性:
继承的状态和属性:

region role

一种landmark,包含与特定作者指定目的相关并且足够重要的内容,用户很可能需要便捷跳转到该区域,或在页面摘要中看到该区域。这样的页面摘要可由用户代理或辅助技术动态生成。

作者应当仅将region角色用于那些目的不能被其它地标角色(如maincomplementarynavigation)准确描述的内容区段。

作者必须为每个采用region角色的元素提供简要标签,描述该区域内内容的用途。如有可见标签,作者应当aria-labelledby进行引用。作者应当尽量将标签放在标题中。标题可以是标准宿主语言标题元素,或是带heading角色的元素。

辅助技术应当让用户能快速跳转到role="region"的元素。 用户代理应当将具有可访问名称的role="region"元素视为导航地标用户代理可以让用户快速跳转到role="region"的元素。

特性:
特性
父类角色: landmark
相关概念:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

roletype role

所有其它角色继承的基础角色

该角色的属性描述被赋予该角色的对象的结构和功能用途。角色是可以用来理解和操作其实例的概念。

roletype 是用于本体描述的抽象角色。作者不得在内容中使用roletype角色。

特性:
特性
是否为抽象: True
子类角色:
支持的状态和属性:

row role

表格容器中的一行单元格。

行包含cellgridcell元素,用于组织tablegridtreegrid

row角色可用于tablegridtreegrid,但aria-expandedaria-posinsetaria-setsizearia-level等语义仅适用于交互式treegrid的层级结构。因此,作者不得把这些属性用于属于tablegrid的row上,用户代理不应向辅助技术暴露这些属性,除非该row属于treegrid。

作者必须确保role为row的元素为tablegridrowgrouptreegrid的无障碍子项。

: 关于 aria-disabled 使用

目前aria-disabled可用于row角色,未来版本计划仅允许在grid或treegrid上下文中的row元素使用该属性。

特性:
特性
父类角色:
基础概念: <tr> in HTML
需要的无障碍父角色:
允许的无障碍子角色:
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author

rowgroup role

表格容器中包含一个或多个行元素的结构。

rowgroup 角色通过其role为row的无障碍子项建立关系。它在结构上等同于HTML表格元素中的theadtfoottbody

作者必须确保role为rowgroup的元素为gridtabletreegrid的无障碍子项。

rowgroup角色部分用于支持HTML中的角色对称,也允许为带显式presentation角色的HTML表格元素传播表现继承。

该角色不区分不同行组类型(如thead与tbody),但在WAI-ARIA 2.0中已提出相关问题。

特性:
特性
父类角色: structure
基础概念: <tbody><tfoot><thead> in HTML
需要的无障碍父角色:
允许的无障碍子角色: row
继承的状态和属性:
命名来源: author

rowheader role

包含某一行标题信息的单元格。

rowheader 角色可用来标识在tablegridtreegrid中作为行标题的单元格。rowheader会在本单元格与相同行的所有单元格间建立一种关系。这和在HTML的th元素上设置scope="row"在结构上是等效的。

作者必须确保role="rowheader"元素row角色元素的无障碍子项。

在rowheader上应用aria-selected状态时,不得让用户代理自动将aria-selected状态传播到对应行的所有单元格。但作者可以根据具体需要选择按此方式设置选中状态。

虽然rowheader角色可以用于交互式网格和非交互式表格,但aria-expandedaria-readonlyaria-required只适用于交互式元素。因此,作者不应在属于table的rowheader上使用这些属性,除非rowheader属于gridtreegrid,用户代理不应向辅助技术暴露这些属性。

:关于 aria-disabled 的使用

虽然aria-disabled目前支持用于rowheader角色,但工作组计划将来仅允许其用于属于gridtreegrid上下文的rowheader元素。

特性:
特性
父类角色:
基础概念: <th scope="row"> in HTML
需要的无障碍父角色: row
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author
是否要求可访问名称: True

scrollbar role

控制内容在可视区域内滚动的图形对象,无论内容是否完全显示在可视区域内。

滚动条会通过其大小和滑块(thumb)在可见范围内的相对位置,显示当前取值及可用值的范围。其方向(orientation)表示滚动条本身的方向和它控制的可视区域的滚动效果。通常可以通过方向键(如上下箭头)增加或减少当前值。

作者必须在滚动条元素上设置aria-controls,用于引用它所控制的可滚动区域。

作者可以设置aria-valueminaria-valuemax,指明滑块的最小和最大位置,否则他们的隐式值同HTML中<input type="range">

  • 如果aria-valuemin缺失或不是数字,则默认为0。
  • 如果aria-valuemax缺失或不是数字,则默认为100。

作者必须设置aria-valuenow,用于指示当前滑块位置。如果aria-valuenow缺失或无效,浏览器可以执行作者状态属性错误处理章节所述的修复,与HTML的<input type="range">修复规则相同。

role为scrollbar的元素,其aria-orientation默认值为vertical

辅助技术通常会将aria-valuenow的数值渲染为aria-valueminaria-valuemax之间的百分比,除非指定了aria-valuetext。因此最好合理设置aria-valueminaria-valuemaxaria-valuenow的值。

特性:
特性
父类角色:
必需的状态与属性:
支持的状态和属性:
继承的状态和属性:
命名来源: author
子项可表现化: True
角色隐式默认值: aria-orientation 的默认值为 vertical
aria-valuemin 的默认值为 0
aria-valuemax 的默认值为 100

section role

页面中可渲染的结构化内容单元。

section 是用于本体论(ontology)的抽象角色。作者不得在内容中使用 section 角色。

特性:
特性
是否为抽象: True
父类角色: structure
子类角色:
继承的状态和属性:

sectionhead role

用于标记或概述其相关区块主题的结构体。

sectionhead 是用于本体论的抽象角色。作者不得在内容中使用 sectionhead 角色。

特性:
特性
是否为抽象: True
父类角色: structure
子类角色:
继承的状态和属性:

select role

允许用户从一组选项中进行选择的表单控件。

select 是用于本体论的抽象角色。作者不得在内容中使用 select 角色。

特性:
特性
是否为抽象: True
父类角色:
子类角色:
支持的状态和属性: aria-orientation
继承的状态和属性:

separator role

用于分隔和区分内容区段或菜单项组的分隔符。

separator 有两种类型:一种是作为仅提供视觉边界的静态structure,另一种是可聚焦、可交互且可移动的widget。若 separator 不可聚焦,则对辅助技术呈现为静态结构元素。例如,静态 separator 可用于菜单内视觉分组区域的分割线,也可用作页面区块之间的水平线。

作者可以separator 设为可聚焦,从而创建一个widget,不仅提供两个内容区的视觉边界,还可以让用户通过拖动 separator 改变区块大小。可变 separator 可以在范围内连续移动,固定 separator 一般只支持两个位置,通常用于切换某一区块展开/折叠。

如果 separator 可聚焦,作者必须aria-valuenow 设置为反映当前 separator 位置的数字,并在变化时更新该值。作者应当设置 aria-valuemin(若不为 0)和 aria-valuemax(若不为 100)。如缺失或非数字,这些属性有隐式默认值:

  • aria-valuemin 的默认值为 0
  • aria-valuemax 的默认值为 100

若应用中包含多个可聚焦 separator,作者应当为每个 separator 提供可访问名称。

separator 角色的元素其 aria-orientation 默认值为 horizontal

特性:
特性
父类角色:
相关概念:
必需的状态和属性: aria-valuenow(可聚焦时)
支持的状态和属性:
继承的状态和属性:
命名来源: author
子项可表现化: True
角色隐式默认值: aria-orientation 的默认值为 horizontal
aria-valuemin 的默认值为 0
aria-valuemax 的默认值为 100

slider role

用户可在指定范围内选择值的输入控件。

滑块通过其长度和滑块按钮的位置,表示当前取值和所有可选取值的范围。通常可以通过方向键(如方向箭头)增加或减少当前值。

作者可以设置aria-valueminaria-valuemax属性,否则其隐式取值与HTML中的<input type="range">一致:

  • aria-valuemin缺失或非数字,默认值为0。
  • aria-valuemax缺失或非数字,默认值为100。

作者必须设置aria-valuenow属性。如果缺失或值异常,浏览器可以采用状态属性错误处理章节中的修复技巧,与HTML <input type="range">相同。

slider角色的元素,其aria-orientation的默认值为horizontal

特性:
特性
父类角色:
必需的状态和属性:
支持的状态和属性:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True
子项可表现化: True
角色隐式默认值: aria-orientation 的默认值为 horizontal
aria-valuemin 的默认值为 0
aria-valuemax 的默认值为 100

spinbutton role

一种range,要求用户从离散选项中选择。

spinbutton 通常允许用户通过激活加减按钮,在允许的值集合中进行增减。一些实现将其值展示在文本框内,既允许编辑和输入,同时通常会限制输入,防止无效值。

虽然spinbutton外观类似多数select的表现,但对于已知数值范围(尤其是较大范围)推荐使用spinbutton而不是离散选项的select。例如,用spinbutton表示1到1000000的范围就比用select控件高效很多。

作者可以创建带无障碍子项的spinbutton,但必须仅限于一个textbox和/或2个button。或者也可为文本输入直接应用spinbutton角色,并创建按钮作为兄弟节点实现增减功能。

为实现键盘可达,作者应当焦点管理所述管理所有该角色实例的后代焦点。spinbutton获得焦点时,应当优先聚焦textbox元素(如有),否则聚焦spinbutton本身。作者还应当确保键盘上上下箭头可用于加减,且加减button元素不能进入主导航序(如HTML的Tab序)。

作者应当spinbutton有值时设置aria-valuenow属性;如有最小值应当设置aria-valuemin,如有最大值应当设置aria-valuemax

特性:
特性
父类角色:
支持的状态和属性:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True
角色隐式默认值: aria-valuemin 默认为没有最小值。
aria-valuemax 默认为没有最大值。
aria-valuenow 默认为没有当前值。

status role

一种实时区域,其内容用于为用户提供建议性信息,但重要性不足以使用alert,通常(但不一定)呈现为状态栏。

作者应当确保role为status的元素因状态变化不会获得焦点。

status是一种实时区域。如果页面其他部分控制status区的内容,作者应当aria-controls属性显式标明这种关系

辅助技术可以为渲染status预留盲文显示器的部分单元。

status角色的元素,aria-live隐式值为politearia-atomic隐式值为true

特性:
特性
父类角色: section
子类角色:
相关概念:
继承的状态和属性:
命名来源: author
角色隐式默认值: aria-live 的默认值为 polite
aria-atomic 的默认值为 true

strong role

重要、严肃或紧急的内容。参见相关emphasis

strong角色用于传达内容的高度重要性、严肃性或紧急性。它不是用于传达那些对内容意义不重要的排版变化。作者应当仅在缺少strong角色会改变内容含义时使用strong。

strong角色并非用于表达强调或语气,应使用emphasis角色。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

structure role

一个文档结构上的元素

用于文档结构的角色,支持动态网页内容无障碍,通过帮助辅助技术区分活动内容与静态文档内容。结构角色本身并非都直接映射到无障碍API,但会用于创建widget角色、或辅助内容自适应以便辅助技术使用。

structure 是用于本体论的抽象角色。作者不得在内容中使用 structure 角色。

特性:
特性
是否为抽象: True
父类角色: roletype
子类角色:
继承的状态和属性:

subscript role

一个或多个下标字符。参见相关superscript

subscript 角色仅应用于具有特定含义的排版规范,不能仅为美观而用。一般来说,作者应当仅在缺少下标会改变内容含义时使用该角色。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

suggestion role

对内容的单项变更建议。

比如在一个支持多人协作的编辑系统中,一个用户可以提出变更建议,另一个用户负责接受或拒绝该建议。

作者必须确保suggestion要么仅包含一个insertion子项,要么仅包含一个deletion子项,或者包含一个insertion和一个deletion子项,共两个子项。作者必须确保suggestion不包含除这两类外的其它子项。

作者可以使用aria-detailsaria-description,将suggestion关联有评论、作者信息、时间戳等相关内容。

<p>
  The best pet is a
  <span role="suggestion">
    <span role="deletion">cat</span>
    <span role="insertion">dog</span>
  </span>
</p>

当建议被接受后,作者应当移除suggestion角色,表示建议修订已采纳。之后,其子项insertiondeletion既可以保留以记录历史,也可以用最终内容替换。

特性:
特性
父类角色: section
允许的无障碍子角色:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

superscript role

一个或多个上标字符。参见相关superscript

superscript 角色仅应用于具有特定含义的排版规范,不能仅为美观而用。一般来说,作者应当仅在缺少上标会改变内容含义时使用该角色。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

switch role

一种表示开/关状态的复选框类型,区别于勾选/未勾选。参见相关 checkbox

aria-checked 属性用于指示 switch 当前是开(true)还是关(false)。该角色下 mixed 为无效值,用户代理必须mixed 视作 false

switch 提供的功能与 checkbox 和切换 button 类似,但允许辅助技术与屏幕外观相一致地呈现该组件。

特性:
特性
父类角色: checkbox
相关概念:
必需的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author
是否要求可访问名称: True
子项可表现化: True

tab role

用于分组标签,为用户切换内容区域提供机制的标签。

tabpanel或其内容获得焦点,该tab即为tablist当前激活的标签,详见焦点管理tablist通常紧邻一组tabpanel元素(通常放在它们之前)。详细Tab组件设计模式实现请参见 WAI-ARIA Authoring Practices

作者必须确保role为tab的元素为role tablist的无障碍子项。

作者应当确保当前激活标签关联的tabpanel区块对用户是可感知的。

对于单选tablist,作者应当将未选中的tabpanel对所有用户隐藏;对于可多选tablist,作者应当确保每个可见tabpanel关联的tab,其aria-expandedtrue,其它被隐藏tabpanel对应tabaria-expandedfalse

作者应当确保已选中的tab的aria-selected属性为true,未选中的tab为false,且当前选中tab有视觉识别。

在某些条件下,UA可以为tablist下每个tab的aria-selected提供隐式值,需满足以下两点:

  • tablist的aria-multiselectablefalse或未定义
  • tablist内所有tab都未显式声明aria-selectedaria-expanded
特性:
特性
父类角色:
所需的无障碍父角色: tablist
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author
是否要求可访问名称: True
子项可表现化: True
角色隐式默认值: aria-selected默认值为false

table role

包含以行和列排布的数据的section。参见相关 grid

table角色适用于非交互式的表格容器。如果表格本身具有选中状态、提供二维导航,或者允许用户重排、操作内容或改变显示,作者应当改用gridtreegrid

作者应当尽量优先使用宿主语言的原生表格语义,例如HTML的<table>元素。

特性:
特性
父类角色: section
子类角色:
基础概念: <table> in HTML
允许的无障碍子角色:
支持的状态和属性:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

tablist role

一组 tab 元素,分别对应 tabpanel 元素。

为实现键盘可达,作者应当按照焦点管理规范管理所有该role实例的后代焦点。

对于单选tablist,作者应当将未选中的tabpanel对所有用户隐藏。对于可多选tablist,作者应当确保每个可见tabpanel关联的tabaria-expandedtrue,剩余隐藏tabpanel的tab的aria-expandedfalse

tablist元素通常紧邻且位于一系列tabpanel元素的前面。详细Tab组件设计模式实现请参见 WAI-ARIA Authoring Practices

tablist角色的元素,其aria-orientation默认值为horizontal

特性:
特性
父类角色:
允许的无障碍子角色: tab
支持的状态和属性:
继承的状态和属性:
命名来源: author
角色隐式默认值: aria-orientation默认值为horizontal

tabpanel role

一个用于存放与某个 tab 关联资源的容器,每个 tab 都被包含在tablist中。

作者应当tabpanel 元素与其 tab 关联,可通过在 tab 上用 aria-controls 指向该 tabpanel ,或在 tabpanel 上用 aria-labelledby 指向 tab。

tablist 元素通常紧邻并排在一系列 tabpanel 元素之前。Tab组件的设计模式详情参见 WAI-ARIA Authoring Practices

特性:
特性
父类角色: section
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

term role

带有可选定义的词语或短语。参见相关 definition

term 角色用于显式识别被作者已提供定义或期待用户提供定义的词语或短语。如果已有 definition,或有表单控件可录入定义,作者应当aria-details 指向对应元素。

作者不应在链接等交互元素上用 term 角色,否则可能会影响 辅助技术 用户正常交互。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

textbox role

可输入自由文本的输入控件类型。

aria-multiline属性为true,该widget支持输入内容换行,与HTML的textarea一致。否则为单行文本框。推荐用于宿主语言无原生文本输入或需用其它元素模拟文本输入场景。

在大多数用户代理中,HTML 单行和多行文本字段在按ENTERRETURN时表现不同。单行<input type="text">通常是提交表单,多行<textarea>则是插入换行。WAI-ARIA textbox角色通过aria-multiline属性区分这两类,编写表单时需特别注意。

特性:
特性
父类角色: input
子类角色:
相关概念:
支持的状态和属性:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

time role

表示具体时间点的元素。

目前WAI-ARIA没有与HTML的time元素datetime属性对应的属性,后续ARIA 1.3标准将会考虑补充。

作者应当保证文本内容为日期/时间格式字符串,或在role为time的元素上加即将支持的datetime类属性。

特性:
特性
父类角色: section
相关概念:
继承的状态和属性:
禁止的状态和属性:
命名来源: prohibited

timer role

一种实时区域,包含一个数值计数器,用于表示从起点经过的时间,或到终点剩余的时间。

timer 对象的文本内容指示当前时间数值,并会随着计数变化而更新。timer的数值不一定可被机器解析,但作者应当在固定间隔刷新文本内容,除非定时器已暂停或到达终点。

角色为 timer 的元素,其 aria-live 隐式值为 off

特性:
特性
父类角色: status
继承的状态和属性:
命名来源: author
角色隐式默认值: aria-live 的默认值为 off

toolbar role

常用功能按钮或控件的集合,并以紧凑的视觉形式展现。

工具栏通常是menubar中功能的子集,旨在降低用户操作这些功能的难度。当应用中有多个工具栏时,作者必须分别为每个工具栏提供标签。

作者可以焦点管理的规范,管理所有该角色实例的后代焦点。

角色为 toolbar 的元素,aria-orientation 的默认值为 horizontal

特性:
特性
父类角色: group
相关概念:
支持的状态和属性: aria-orientation
继承的状态和属性:
命名来源: author
角色隐式默认值: aria-orientation 的默认值为 horizontal

tooltip role

为元素显示描述信息的上下文弹窗。

tooltip 通常会在短暂延迟后因为鼠标悬浮或无障碍父级获得键盘焦点而显示。WAI-ARIA 的 tooltip 是对用户代理默认提示的补充。

典型的 tooltip 延迟一般为 1~5 秒。

作者应当确保带 tooltip 角色的元素在显示前或显示时已被 aria-describedby 正确引用。

特性:
特性
父类角色: section
继承的状态和属性:
命名来源:
  • contents
  • author

tree role

允许用户从分层组织的集合中选择一个或多个项目的widget

为实现键盘可达,作者应当按照焦点管理规范,管理所有该角色实例的后代焦点。

角色为 tree 的元素,aria-orientation 的默认值为 vertical

特性:
特性
父类角色: select
子类角色:
允许的无障碍子角色:
支持的状态和属性:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True
角色隐式默认值: aria-orientation 的默认值为 vertical

treegrid role

一种grid,其行可以像 tree 那样展开和折叠。

如果在带有 treegrid 角色的元素上设置了 aria-readonly用户代理必须将该属性值传递给所有作为该 treegrid gridcell无障碍后代,并在无障碍 API 中公开。作者可以为某个具体 gridcell 覆盖继承下来的 aria-readonly 值。

aria-readonly 应用于可聚焦的 gridcell 时,表示该 gridcell 是否可编辑。aria-readonly 仅表示内容编辑性,并不代表对整个 treegrid 的操作权限。

在支持内容编辑的 treegrid 中,若某个可聚焦 gridcell 不可编辑,作者可以将该 gridcellaria-readonly 设为 true。但如果 treegrid 内部仅包含不支持 aria-readonly 的元素,例如仅由 link 组成,则可以无需指定 aria-readonly

为实现键盘可达,作者应当管理本角色所有实例的后代焦点,具体见焦点管理

特性:
特性
父类角色:
允许的无障碍子角色:
继承的状态和属性:
命名来源: author
是否要求可访问名称: True

treeitem role

tree 内的一个项目。

treeitem 元素可包含一个可展开/折叠的子级分组。可展开的 treeitem 需包裹在带 group 角色的元素中。

作者必须确保带 treeitem 角色的元素tree 或作为 treeitem无障碍子项group 的无障碍子项。

在特定条件下,UA可以tree 内每个 treeitemaria-selected 提供隐式值,且应满足以下条件:

如果 UA 对 treeitem 提供了隐式 aria-selected 值,有以下规则:treeitem 获得 DOM 焦点,或 tree 获得 DOM 焦点且 treeitem 被 aria-activedescendant 引用,则建议为 true,否则建议为 false

作者可以aria-selectedaria-checked 表示树项目的选中状态。一些界面单选树用 aria-selected,多选树用 aria-checked。作者不应在同一 tree 包含的 treeitem 同时指定 aria-selectedaria-checked,除非满足以下极少发生的全部条件:

  • 界面中 aria-selectedaria-checked 含义完全不同。
  • 界面清楚区分了二者的含义。
  • 用户可以分别更改两种状态。
特性:
特性
父类角色:
所需无障碍父角色:
支持的状态和属性:
继承的状态和属性:
命名来源:
  • contents
  • author
是否要求可访问名称: True

widget role

图形用户界面(GUI)中的交互组件。

widget 是用户可交互的离散界面对象。widget 角色可映射到无障碍API的标准特性。当用户导航到任一 widget 非抽象子类角色元素时,通常拦截标准键盘事件的辅助技术设备应当切换为应用模式,将键盘事件传给网页应用。这样能提示一些辅助技术从普通浏览模式切换到更适合Web应用交互的模式;有些用户代理的浏览导航模式下,方向键如上下键会用于浏览文档,阻止网页使用这些按键。

widget 是用于本体论的抽象角色。作者不得在内容中使用 widget 角色。

特性:
特性
是否为抽象: True
父类角色: roletype
子类角色:
继承的状态和属性:

window role

浏览器或应用窗口。

带有本角色元素在图形用户界面(GUI)上下文中呈现窗口行为,无论是否为操作系统原生窗口或仅为页面样式模拟窗口。

window 是用于本体论的抽象角色。作者不得在内容中使用 window 角色。

本角色描述所指的“application”并不等同于 application 角色,其后者指代特定的辅助技术行为。

特性:
特性
是否为抽象: True
父类角色: roletype
子类角色:
支持的状态和属性: aria-modal
继承的状态和属性:

6. 支持的状态和属性

6.1 状态与属性的区别说明

术语“状态”和“属性”指的是类似的特性。二者都为对象提供特定信息,并且都是角色本质定义的一部分。在本文中,状态和属性都作为带有 aria 前缀的标记属性进行处理。然而,为了阐明其含义上的细微差异,概念上保持两者的区别。一个主要区别在于,属性(例如aria-labelledby)的通常比状态(例如aria-checked)的值在应用生命周期内更不容易发生变化,而状态值可能因用户交互而经常变化。请注意,变化频率的差异并不是硬性规定;有些属性(如aria-valuetext)预期也会发生频繁变化。由于状态与属性之间的区分对大多数网页内容作者影响很小,本规范在可能的情况下,将“状态”和“属性”统称为“属性”。详情请参阅状态属性的定义。

6.2 状态和属性的特性

状态和属性具有以下各节所描述的特性。

关于本技术或其他语言中与此状态属性对应特性的建议性信息。虽然对应关系可能并不完全一致,但有助于理解该状态或属性的设计意图。

6.2.2 用于角色中

关于使用该角色中的状态属性的建议性信息。提供这些信息是为了帮助理解状态或属性的正确用法。若状态或属性被用于未被列出的其他角色上,则这种用法是不被定义的。

6.2.3 继承到角色中

关于角色从祖先角色继承该状态属性的建议性信息。

6.2.4

状态属性的值类型。可选类型如下:

true/false
值可以是truefalse。除非另行说明,此类型的默认值为false
tristate
值可以是truefalsemixedundefined。除非另行说明,默认值为undefined
true/false/undefined
值可以是truefalseundefined(不适用)。除非另行说明,默认值为undefined。例如, aria-expanded设为false表示当前未展开,设为undefined表示元素不可展开。
ID reference
引用同一文档中其他元素的ID
ID reference list
由一个或多个ID引用组成的列表。
integer
无小数部分的数值。
number
任意实数值。
string
不受限制的取值类型。
token
被允许值集合之一。每个属性的默认值在属性值章节中的“值”表中定义。
token list
一个或多个标记(token)组成的列表。

这些为状态和属性的通用类型,但不定义具体表示方式。关于这些值在宿主语言中的表达和处理方式,详见状态和属性属性处理章节。

6.3 ARIA 属性

6.3.1 多值属性值

当ARIA属性定义包含一个列出允许的的表时,该属性为多值可空属性。表中的每个值都是该属性的关键字,并映射为相同名称的状态。

6.3.2 ARIA属性的IDL反射

所有ARIA属性在IDL中都作为可空 DOMString属性进行反射。包括类布尔类型的true/false类型和所有其他ARIA属性。

ARIA属性值表中的默认值不能 反射为IDL的缺失值默认无效值默认。 获取属性时,如果未设置ARIA属性,则返回null。ARIA属性在获取时不会被校验。 如果ARIA值无效,则获取时返回设置的原始字符串,不会返回无效值默认。

6.3.3 多值ARIA属性的操作系统辅助技术API映射

与IDL反射不同,操作系统辅助技术API对ARIA属性的映射可以有默认值。 ARIA值表中定义的任何默认值,都会如5.2.3 支持的状态和属性核心辅助技术API映射 1.1中所述暴露给操作系统辅助技术API。

6.3.4 ARIA可空DOMString属性

A. WAI-ARIA值类型与语言映射所述, 属性被包含进宿主语言,并且WAI-ARIA类型的表示语法由宿主语言决定。

以下算法应用于HTML中的ARIA可空DOMString属性:

获取时,如果相应的内容属性不存在,则IDL属性返回null,否则,IDL属性会以透明、区分大小写的方式获取值。设置时,如果新值为null,则内容属性被移除,否则内容属性被设置为指定的新值,并保持透明、区分大小写。

注:自ARIA 1.2起,所有通过IDL暴露的ARIA属性都被定义为可空DOMString,这与所有主流渲染引擎当前的实现一致。本规范的更改不会影响已有实现,仅反映了Web引擎的实际现状。 但在未来的草案中,ARIA工作组计划将若干ARIA属性改为不可空DOMString,并寻求实现支持。所提议变更将使ARIA与HTML中列举属性的使用方式保持一致。

6.3.4.1 属性用法示例

本节为非规范性内容。

6.4 可翻译属性

HTML规范规定,其他规范可以定义可翻译属性。每个属性值的语言和书写方向与语言书写方向属性对应元素一致。

为了辅助技术用户能够理解,以下状态属性的值属于可翻译属性,页面本地化时应进行翻译:

6.5 全局状态和属性

有些状态属性适用于所有宿主语言元素,无论是否应用了角色。下列全局状态和属性被所有角色及所有基础标记元素支持,除非明确禁止。若某角色禁止使用某些全局状态或属性,这些状态或属性会在定义角色的章节的特性表中列为禁止。

6.6 WAI-ARIA状态和属性的分类体系

状态和属性按如下方式分类:

  1. 组件属性
  2. 实时区域属性
  3. 拖放属性
  4. 关系属性

6.6.1 组件属性

本节包含特定于常见用户界面元素属性,这些元素出现在GUI系统或富互联网应用中,可接收用户输入并处理用户操作。这些属性用于支持组件角色

组件属性可能会被用户代理映射为平台辅助功能API状态,供辅助技术访问,也可以直接从DOM中访问。

6.6.2 实时区域属性

本节包含富互联网应用中实时区域属性。这些属性可以应用于任何元素。这些属性旨在表明内容可能在元素未获得焦点时发生变化,并向辅助技术提供如何处理这些内容更新的信息。有些角色aria-live属性指定了特定的默认值。实时区域的一个例子是用于显示股票报价动态更新的滚动条区域。用户代理可以忽略由用户直接操作实时区域内部元素(例如编辑文本字段值)所触发的变化。

6.6.3 拖放属性

本节列出了关于拖放界面元素(如可拖动元素及其放置目标)的相关属性。放置目标的信息将由作者以可视化方式呈现,并通过其他方式提供给辅助技术

6.6.4 关系属性

本节列出了无法从文档结构中直接得出的,指示关系或联系的属性,用于不同元素之间的关联。

6.7 状态变化通知

用户代理必须为辅助技术提供一种在状态发生变化时得到通知的方式,可以通过DOM属性变化事件或平台辅助功能API事件实现。

6.8 状态和属性的定义(所有 aria-* 属性)

下方按字母顺序列出了供富互联网应用作者使用的 WAI-ARIA 状态属性。每个 WAI-ARIA 状态和 属性的详细定义,请见本紧凑列表后续内容。

aria-activedescendant
标识DOM 焦点位于 composite 组件、comboboxtextboxgroupapplication 时当前活动的元素。
aria-atomic
指示辅助技术是否会根据 aria-relevant 属性定义的变更通知,呈现整个变更区域还是仅呈现部分内容。
aria-autocomplete
指示输入文本时是否会触发一个或多个对用户意图值的预测显示于 comboboxsearchboxtextbox,以及如果存在预测时这些预测应如何展示。
aria-braillelabel
定义给当前元素的字符串标签,旨在被转换成盲文。参见相关的 aria-label
aria-brailleroledescription
定义元素角色的可读、作者本地化的简短描述,旨在被转换成盲文。参见相关的 aria-roledescription
aria-busy
指示元素正在被修改,辅助技术可在修改完成后再将其暴露给用户。
aria-checked
指示复选框、单选按钮及其他组件当前“选中”状态。参见相关的 aria-pressedaria-selected
aria-colcount
定义一个 tablegridtreegrid 的总列数。参见相关的 aria-colindex
aria-colindex
定义某个 元素tablegridtreegrid 内的列索引或位置。参见相关的 aria-colindextextaria-colcountaria-colspan
aria-colindextext
定义 aria-colindex 的可读文本替代。参见相关的 aria-rowindextext
aria-colspan
定义一个单元格或 gridcell 在 tablegridtreegrid 内跨越的列数。参见相关的 aria-colindexaria-rowspan
aria-controls
标识当前元素控制其内容或存在的 元素(或若干元素)。参见相关的 aria-owns
aria-current
指示在某容器或相关元素集合内表示当前项的 元素
aria-describedby
标识对象进行描述的 元素(或若干元素)。参见相关的 aria-labelledbyaria-description
aria-description
定义描述或注释当前元素的字符串值。参见相关的 aria-describedby
aria-details
标识提供与 对象相关的更多信息的 元素(或若干元素)。参见相关的 aria-describedby
aria-disabled
指示元素可感知的但处于禁用状态,因此不可编辑或以其他方式可操作。参见相关的 aria-hiddenaria-readonly
aria-dropeffect
[ARIA 1.1 已废弃] 指示拖拽对象释放到放置目标时可执行的功能。
aria-errormessage
标识对象提供错误信息的 元素(或若干元素)。参见相关的 aria-invalidaria-describedby
aria-expanded
指示作为该元素辅助技术子级或受控分组元素是否已展开或折叠。
aria-flowto
标识内容可任选顺序阅读时的下一个 元素(或若干元素),允许辅助技术覆盖按文档源码顺序阅读的默认行为。
aria-grabbed
[ARIA 1.1 已废弃] 指示拖放操作中元素的“已抓取”状态
aria-haspopup
指示可由某元素触发的交互式弹出元素(如菜单或对话框)的可用性与类型。
aria-hidden
指示元素是否会暴露给辅助功能 API。参见相关的 aria-disabled
aria-invalid
指示输入的值不符合应用预期的格式。参见相关的 aria-errormessage
aria-keyshortcuts
定义作者实现的可用于激活或聚焦元素的键盘快捷键。
aria-label
定义对当前元素的字符串标签。参见相关的 aria-labelledby
aria-labelledby
标识为当前元素提供标签的 元素(或若干元素)。参见相关的 aria-labelaria-describedby
aria-level
定义某个 元素 在结构中的层级。
aria-live
指示某个元素将被更新,并描述用户代理辅助技术和用户可期望从实时区域收到的更新类型。
aria-modal
指示某个 元素在显示时是否为模态。
aria-multiline
指示文本框是否接受多行输入还是仅接受单行输入。
aria-multiselectable
指示用户能否从可选子项中选择一个以上项。
aria-orientation
指示元素的方向(水平、垂直或未知/不明确)。
aria-owns
标识DOM 层次结构无法表示父/子关系时,用于定义视觉、功能或上下文父/子关系的 元素(或若干元素)。参见相关的 aria-controls
aria-placeholder
定义在控件没有值时用于辅助用户输入的简短提示(单词或短语)。提示可以是示例值或期望格式的简要描述。
aria-posinset
定义某个 元素在当前 listitems 或 treeitems 集合中的编号或位置。如果集合中的所有元素都出现在 DOM 中,则不必设置。参见相关的 aria-setsize
aria-pressed
指示切换按钮当前“按下”状态。参见相关的 aria-checkedaria-selected
aria-readonly
指示该 元素不可编辑,但可以可操作。参见相关的 aria-disabled
aria-relevant
指示当实时区域中的 辅助功能树被修改时,用户代理将触发哪些通知。参见相关的 aria-atomic
aria-required
指示在表单提交前,该 元素需用户输入。
aria-roledescription
定义某个 角色的可读、作者本地化描述。
aria-rowcount
定义 tablegridtreegrid 的总行数。参见相关的 aria-rowindex
aria-rowindex
定义某个 元素tablegridtreegrid 内的行索引或位置。参见相关的 aria-rowindextextaria-rowcountaria-rowspan
aria-rowindextext
定义 aria-rowindex 的可读文本替代。参见相关的 aria-colindextext
aria-rowspan
定义一个单元格或 gridcell 在 tablegridtreegrid 内跨越的行数。参见相关的 aria-rowindexaria-colspan
aria-selected
指示各种组件当前“选中”状态。参见相关的 aria-checkedaria-pressed
aria-setsize
定义当前 listitems 或 treeitems 集合中的项数。如果集合全部出现在 DOM 中,则不必设置。参见相关的 aria-posinset
aria-sort
指示表格或网格中的项目是否按升序或降序排列。
aria-valuemax
定义区间组件的允许最大值。
aria-valuemin
定义区间组件的允许最小值。
aria-valuenow
定义区间组件的当前值。参见相关的 aria-valuetext
aria-valuetext
定义区间组件aria-valuenow 可读文本替代。

aria-activedescendant 属性

标识DOM 焦点处于 composite 组件、comboboxtextboxgroupapplication 时当前处于活动状态的元素。

aria-activedescendant 属性为交互式元素(如菜单、网格和工具栏)中可能包含多个可聚焦子项的容器,提供了一种可替代的焦点管理方式。作者可以不在 DOM 中移动焦点到各个可访问后代,而是将 DOM 焦点设置到支持 aria-activedescendant 的容器元素,然后通过 aria-activedescendant 指向当前活动的元素。

作者必须保证当在具有 DOM 焦点的元素上设置 aria-activedescendant 时,满足以下两组条件之一:

  1. aria-activedescendant 的值指向某可访问后代
  2. DOM 焦点的元素是 comboboxtextboxsearchbox,其 aria-controls 指向了一个支持 aria-activedescendant 的元素,且 aria-activedescendant 的取值指向此受控元素的某可访问后代。 例如,在combobox中,焦点可保留在 combobox,而其 aria-activedescendant 指向该组件所控制的弹出 listbox 的某个后代。

作者应该确保当前活动后代在获得焦点时处于可见范围并(自动)滚动至可见。

特性:
特性
相关概念:
用于角色:
可继承到的角色:
值: ID 引用

aria-atomic 属性

指示辅助技术会根据 aria-relevant 属性定义的变更通知,呈现全部还是部分变更区域内容。

无障碍APIsDocument Object Model [DOM] 都会通过事件让辅助技术知晓文档哪些区域发生了变化。

实时区域内容变化时,用户代理应该检查发生变化的 元素并向上遍历祖先,查找第一个设置了 aria-atomic 的元素,按下述情况应用相应行为。

  1. 如果所有祖先都未显式设置 aria-atomic,则默认 aria-atomicfalse,辅助技术仅呈现变更节点。
  2. 如果 aria-atomic 明确设置为 false,辅助技术会停止向上查找,仅呈现变更节点。
  3. 如果 aria-atomic 明确设置为 true,辅助技术会呈现该元素的全部内容,包括作者定义的实时区域标签(如存在)。

aria-atomictrue 时,辅助技术可以合并多个变更,一次性呈现整个区域。

特性:
特性
用于角色: 所有基础标记元素
值: true/false
取值说明:
描述
false 辅助技术只会呈现发生变化的单个节点或节点集合。
true 辅助技术会将整个变更区域作为整体(含作者自定义标签,如有)一起呈现。

aria-autocomplete 属性

指示输入文字时,是否会为 comboboxsearchboxtextbox 提供一个或多个用户意图值的预测,并指定这些预测展示方式。

aria-autocomplete 属性描述 textboxsearchboxcombobox 在动态帮助用户补全文本输入时采用的交互模型。其区分两种模式:内联模式 (aria-autocomplete="inline"),在文本输入内显示补全建议,以及列表模式 (aria-autocomplete="list"),在输入旁弹出显示候选值集合。输入也可以同时支持这两种模式 (aria-autocomplete="both")。

aria-autocomplete 属性仅用于描述输入元素的补全行为。若输入元素提供一组与用户当前输入无关的候选项,则作者应该省略 aria-autocomplete 或设置为 none。例如,一个 aria-autocompletenone 的 combobox 是一个搜索框,仅列出最近使用过的5条,无论用户输入内容如何都不筛选。支持此属性的角色,其 aria-autocomplete 默认值为 none

当用户在输入中键入时,内联建议会动态出现在光标之后,且当用户通过离开输入框等操作时,建议的文本会作为输入值被采纳。当元素设置为 inlineboth 时,作者应该确保自动补齐的文本以选中文本形式呈现,使辅助技术可区分用户输入与自动建议,用户也能轻松删除或覆盖建议。

若元素设置 aria-autocompletelistboth,作者必须同时满足以下两点:

  1. 元素的 aria-controls 属性的值指向包含建议集合的元素。
  2. 元素的 aria-haspopup 属性值与建议集合容器的角色一致。

有些列表补全需要用户主动操作,如用键盘向下箭头或鼠标点击以选中建议,此时作者可以通过 aria-activedescendant、或者直接转移 DOM 焦点到建议项来管理焦点。但部分实现会自动选中一个建议值,当输入框失焦时(如按 Tab 或点击其它区域)自动采纳此项。如果为 listboth 且存在自动选中,作者必须还需确保:

  1. 候选建议集合显示在一个支持 aria-activedescendant 的元素中。
  2. 输入框的 aria-activedescendant 动态指向选中项(详见该属性定义)。
  3. 建议显示时,DOM 焦点保持在文本输入上。

aria-autocomplete 并不用于说明是否有补全建议,作者不应通过动态更改其值来表达建议的存在。对于 listboth,作者应该aria-expanded 表示建议集合的显示状态。

特性:
特性
用于角色:
可继承到的角色:
值: token
取值说明:
说明
inline 当用户输入时,建议补全文字可动态插入在光标之后。
list 当用户输入时,会显示包含补全候选值集合的元素。
both 当用户输入时,既会有候选集合被显示,同时集合中某一项会自动选中,其补全文字出现在输入光标之后。
none (默认) 当用户输入时,不显示任何自动补全建议。

aria-braillelabel 属性

定义一个用于为当前元素打标签的字符串值,该标签旨在被转换为盲文。参见相关 aria-label

aria-braillelabel 的目的是类似 aria-label,为用户提供对象的可识别盲文名称。

aria-braillelabel 属性让作者可以覆盖辅助技术对元素可访问名称在盲文中的本地化和表达。因此不恰当使用 aria-braillelabel 可能影响用户在盲文界面的理解。作者应该仅在界面名称转换成盲文后并非期望体验时使用该属性。

使用 aria-braillelabel 时,作者还应确保:

  1. 元素本身具有有效可访问名称。
  2. aria-braillelabel 的值非空且不全是空白字符
  3. aria-braillelabel 的值不包含 Unicode 盲文图案中的字符,或仅由 Unicode 盲文图案字符组成,且值不可只由盲文空点(dots-0)组成。
  4. aria-braillelabel 的值不应与元素的可访问名称完全相同。

作者禁止在具有显式或隐式禁止 aria-braillelabelWAI-ARIA 角色元素上指定 aria-braillelabel

支持盲文的辅助技术可以自动将可访问名称转换为盲文,并可根据用户偏好定制输出。通常仅使用可访问名称(例如直接内容或 aria-label)即能提供最优体验强烈不建议aria-braillelabel 复制 aria-label。仅当可访问名无法提供理想盲文效果时才需此属性,也即需要针对性盲文描述。请特别注意,使用 aria-braillelabel 时,作者需自行负责本地化其值以与文档语言对齐,且需在产品文档等明确告知用户(尤其当值为 Unicode 盲文时)。否则辅助技术会直接原样输出,无任何翻译,强烈不建议aria-braillelabel 中使用 Unicode 盲文图案。

辅助技术应该在以盲文呈现元素可访问名称时使用 aria-braillelabel,但不应变更其它行为。例如,提供语音输出的辅助技术使用可访问名称。

辅助技术应该如下暴露 aria-braillelabel

  1. aria-braillelabel 不含 Unicode 盲文图案字符,则按用户翻译表转换。
  2. 否则直接原样输出。

下例展示 aria-braillelabel 用于自定义按钮盲文名称:

<button aria-braillelabel="****">
  <img alt="4 stars" src="images/stars.jpg">
</button>

在上述例子中,盲文设备将展示 Braille“btn ****”,而不是冗长的“btn gra 4 stars”。

特性:
特性
用于角色: 基础标记所有元素,但以下角色除外:captioncodedefinitiondeletionemphasisgenericinsertionmarknoneparagraphstrongsubscriptsuggestionsuperscripttermtime
值: string

aria-brailleroledescription 属性

定义某个 角色 的易读、作者本地化的缩写描述,用于被转换为盲文。参见相关 aria-roledescription

部分辅助技术如屏幕阅读器,会以用户体验的一部分展示元素的角色。这些辅助技术通常会本地化角色名,并可能定制其展示。用户依赖这些角色名的呈现(如“区域”、“按钮”或“滑块”),以理解元素用途,并知晓若为组件该如何交互。

aria-brailleroledescription 属性让作者可以覆盖辅助技术在盲文中本地化和表达角色名的方式。因此,错误地使用 aria-brailleroledescription 可能会影响用户在盲文界面理解或操作元素的能力。作者应该仅当需要对非交互式容器角色(比如 groupregion)作解释时,或为组件在盲文上下文中提供更具体描述时才使用该属性。

作者禁止在未同时提供 aria-roledescription 时使用 aria-brailleroledescription。同样,作者禁止在明示或隐式禁止 aria-brailleroledescriptionWAI-ARIA 角色元素上指定 aria-brailleroledescription

通常,aria-brailleroledescription 只适用于很少数情况下 aria-roledescription 在盲文渲染时过于冗长。

使用 aria-brailleroledescription 时,作者还应确保:

  1. 应用 aria-brailleroledescription 的元素拥有有效的 WAI-ARIA 角色或有隐式 WAI-ARIA 语义。
  2. aria-brailleroledescription 的值非空且不全为空白字符
  3. aria-brailleroledescription 的值不包含 Unicode 盲文图案中的字符,或只由其组成;不得仅为盲文空点(dots-0)。
  4. 该值不应和元素的 WAI-ARIA aria-roledescription、WAI-ARIA role 或隐式角色语义完全一致。

带盲文支持的辅助技术可将 aria-roledescription 内容转换为盲文,也能根据用户偏好进行定制输出。仅用 aria-roledescription 几乎总是最佳体验,强烈不建议aria-brailleroledescription 复制 aria-roledescription。只有在 aria-roledescription 不能提供理想盲文表达(如专用盲文描述和文本转盲文相差很大时)才建议用该属性。特别注意:用 aria-brailleroledescription 时,作者需独立本地化其值,使其和文档语言一致,并通过产品文档等方式明确传达该用途。若值为 Unicode 盲文图案,辅助技术会直接传递而不做进一步转译,强烈不建议在此属性中用 Unicode 盲文图案。

若存在以下任一情况,用户代理禁止暴露该属性:

  1. aria-brailleroledescription 的值为空或仅包含空白,包括常规空白字符及盲文空点(U+2800)。
  2. 应用该属性的元素处于明示或隐式禁止 aria-brailleroledescription 的 WAI-ARIA 角色下。
  3. 应用该属性的元素未设置有效的 WAI-ARIA aria-roledescription

辅助技术应该在用盲文展示角色时采用该属性值,但不应基于此值影响其他功能。例如,导航到下一个regionbutton的功能同样适用于带有该属性的元素。

辅助技术应该如下注明 aria-brailleroledescription 属性:

  1. 若值不含 Unicode 盲文图案字符,则根据用户翻译表进行翻译。
  2. 否则,直接原样传递给用户,不做转译。

下列两个示例展示了 aria-brailleroledescription 用于缩写 Web 演示文稿中重复非交互“slide”容器角色的写法。

<div role="article" aria-roledescription="slide" aria-brailleroledescription="sld" id="slide" aria-labelledby="slideheading">
<h1 id="slideheading">Quarterly Report</h1>
<!-- remaining slide contents -->
</div>
<article aria-roledescription="slide" aria-brailleroledescription="sld" id="slide" aria-labelledby="slideheading">
<h1 id="slideheading">Quarterly Report</h1>
<!-- remaining slide contents -->
</div>

如上例,盲文屏幕阅读器用户会读到“sld Quarterly Report”,而不是冗长的“slide Quarterly Report”。

特性:
特性
用于角色: 基础标记的全部元素,除了generic
值: string

aria-busy 状态

指示某元素正在被修改,辅助技术可等到修改完成后再将其暴露给用户。

所有元素 aria-busy 的默认值为 false。当某元素 aria-busytrue 时,辅助技术可忽略该元素下作为可访问后代的内容变更,并在 aria-busy 变回 false 时,将整个变更作为一次性原子更新处理。

如果需要在某个已渲染的容器中执行多次增改或移除操作,作者可以在首次变更前将容器的 aria-busy 设为 true,变更完成后再设为 false。比如,若需将对实时区域的多项更改作为一条语音播报,作者可以在全部更改期间设为 true,待就绪再设为 false

feed 角色元素被标记为 busy,辅助技术可推迟其内部内容的变更渲染,但用户在 article 中阅读期间的用户发起变更除外。

若渲染的 widget 内容更改会导致在脚本执行期间修改允许的辅助技术子角色状态,作者可以在更新期间将该 widget 标记为 busy。例如,树型网格若需对多个不连续分支同时更新,可以在修改期间将树整体标记为 busy,而不用每次修改都整体重建树。

特性:
特性
用于角色: 基础标记全部元素
值: true/false
取值说明:
说明
false (默认): 元素预期不会有需要更新的内容。
true 元素正在被更新。

aria-checked 状态

指示复选框、单选框及其他组件当前“选中”状态。参见相关 aria-pressedaria-selected

aria-checked 属性 用于指示 元素是已选中(true)、未选中(false),还是表示包含多个勾选与未勾选项的混合态(mixed)。大多数输入控件只支持 truefalse,但部分三态控件如checkboxmenuitemcheckbox等支持 mixed

mixed 取值支持 radiomenuitemradioswitch 或其继承元素,用户代理必须将其视为 false

关于三态输入中 mixed 用法,可参见 WAI-ARIA 作者实践

特性:
特性
用于角色:
可继承到的角色:
值: tristate
取值说明:
说明
false 元素支持勾选但当前未勾选。
mixed 用于三态复选框或菜单项复选框,表示混合状态。
true 元素处于勾选状态。
undefined (默认) 元素不支持勾选。

aria-colcount 属性

定义tablegridtreegrid 的总列数。参见相关 aria-colindex

如果所有列都出现在 DOM 中,则无需设置该属性,因为 用户代理可自动计算总列数。若某时刻 DOM 中仅渲染部分列,则需用此属性明确全表总列数。

作者必须aria-colcount 设为等于表全部列数的整数。若总列数未知,作者必须将其设为 -1,表示用户代理不应计算该值。

下例为用户仅看见第2、3、4及9列的16列表格网格:

<div role="grid" aria-colcount="16">
  <div role="rowgroup">
    <div role="row">
      <span role="columnheader" aria-colindex="2">First Name</span>
      <span role="columnheader" aria-colindex="3">Last Name</span>
      <span role="columnheader" aria-colindex="4">Company</span>
      <span role="columnheader" aria-colindex="9">Phone</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row">
      <span role="gridcell" aria-colindex="2">Fred</span>
      <span role="gridcell" aria-colindex="3">Jackson</span>
      <span role="gridcell" aria-colindex="4">Acme, Inc.</span>
      <span role="gridcell" aria-colindex="9">555-1234</span>
    </div>
    <div role="row">
      <span role="gridcell" aria-colindex="2">Sara</span>
      <span role="gridcell" aria-colindex="3">James</span>
      <span role="gridcell" aria-colindex="4">Acme, Inc.</span>
      <span role="gridcell" aria-colindex="9">555-1235</span>
    </div></div>
</div>
特性:
特性
用于角色:
可继承到的角色:
值: integer

aria-colindex 属性

定义元素tablegridtreegrid 总列数下的列索引或位置。参见相关 aria-colindextextaria-colcountaria-colspan

如果所有列都在 DOM 中,则无需设置该属性用户代理会自动计算每个单元格或gridcell的列索引。但如果 DOM 中只有部分列已渲染,则该属性可用于明确指定单元格或gridcell在完整表格中的列编号。

作者必须aria-colindex设为大于等于1的整数,且大于同一行内前一元素的 aria-colindex,小于等于完整表的总列数。对于跨多列的单元格或gridcell,作者必须将值设为起始列号。

如果 DOM 中整体列集合连续,且无单元格跨多行或多列,则作者可以在每一行设置 aria-colindex,其值为该集合中第一列的索引。否则,作者在每一行所有辅助技术子元素上单独设置 aria-colindex

下列示例为16列网格,用户实际看到第2~5列,因为集合连续,可将 aria-colindex 设置在每一行。

<div role="grid" aria-colcount="16">
  <div role="rowgroup">
    <div role="row" aria-colindex="2">
      <span role="columnheader">First Name</span>
      <span role="columnheader">Last Name</span>
      <span role="columnheader">Company</span>
      <span role="columnheader">Address</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row" aria-colindex="2">
      <span role="gridcell">Fred</span>
      <span role="gridcell">Jackson</span>
      <span role="gridcell">Acme, Inc.</span>
      <span role="gridcell">123 Broad St.</span>
    </div>
    <div role="row" aria-colindex="2">
      <span role="gridcell">Sara</span>
      <span role="gridcell">James</span>
      <span role="gridcell">Acme, Inc.</span>
      <span role="gridcell">123 Broad St.</span>
    </div></div>
</div>

下例同样为16列网格,显示第2~5列,但有单元格跨多行。因此须为每一行每个辅助技术子元素单独设置 aria-colindex

<div role="grid" aria-colcount="16">
  <div role="rowgroup">
    <div role="row">
      <span role="columnheader" aria-colindex="2">First Name</span>
      <span role="columnheader" aria-colindex="3">Last Name</span>
      <span role="columnheader" aria-colindex="4">Company</span>
      <span role="columnheader" aria-colindex="5">Address</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row">
      <span role="gridcell" aria-colindex="2">Fred</span>
      <span role="gridcell" aria-colindex="3">Jackson</span>
      <span role="gridcell" aria-colindex="4" aria-rowspan="2">Acme, Inc.</span>
      <span role="gridcell" aria-colindex="5" aria-rowspan="2">123 Broad St.</span>
    </div>
    <div role="row">
      <span role="gridcell" aria-colindex="2">Sara</span>
      <span role="gridcell" aria-colindex="3">James</span>
    </div></div>
</div>

下例为16列网格,用户实际看到第2、3、4、9列,因为集合不连续,须为每行所有辅助技术子元素单独设置 aria-colindex

<div role="grid" aria-colcount="16">
  <div role="rowgroup">
    <div role="row">
      <span role="columnheader" aria-colindex="2">First Name</span>
      <span role="columnheader" aria-colindex="3">Last Name</span>
      <span role="columnheader" aria-colindex="4">Company</span>
      <span role="columnheader" aria-colindex="9">Phone</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row">
      <span role="gridcell" aria-colindex="2">Fred</span>
      <span role="gridcell" aria-colindex="3">Jackson</span>
      <span role="gridcell" aria-colindex="4">Acme, Inc.</span>
      <span role="gridcell" aria-colindex="9">555-1234</span>
    </div>
    <div role="row">
      <span role="gridcell" aria-colindex="2">Sara</span>
      <span role="gridcell" aria-colindex="3">James</span>
      <span role="gridcell" aria-colindex="4">Acme, Inc.</span>
      <span role="gridcell" aria-colindex="9">555-1235</span>
    </div></div>
</div>
特性:
特性
用于角色:
可继承到的角色:
值: integer

aria-colindextext 属性

定义aria-colindex 的可读文本替代。参见相关 aria-rowindextext

仅当指定或计算的 aria-colindex 的数值本身无实际意义或不能体现界面显示索引(如电子表格、棋盘)时,作者使用 aria-colindextext

作者不应aria-colindextext 代替 aria-colindex,因为部分辅助技术依赖数值列索引以追踪用户位置或为表格导航提供支持。

aria-colindex 不同, aria-colindextext 不是 row 支持的属性,因为用户代理无法可靠计算 aria-colindextext 以便暴露给 cellgridcell

特性:
特性
用于角色:
可继承到的角色:
值: string

aria-colspan 属性

定义某个单元格或gridcell在 tablegridtreegrid 中跨越的列数。参见相关 aria-colindexaria-rowspan

属性适用于不在原生table内的单元格及gridcell。如定义原生table的列跨度,作者优先使用宿主语言自身的属性。若在宿主语言已提供等价属性时仍用 aria-colspan用户代理必须忽略其值,而将宿主语言属性值暴露给辅助技术

作者必须aria-colspan设为大于等于1且小于会导致单元格覆盖本行下一个单元格的整数。

特性:
特性
用于角色:
可继承到的角色:
值: integer

aria-controls 属性

标识被当前元素控制内容或存在的元素(或若干元素)。参见相关 aria-owns

例如:

  • 目录树状视图可以控制邻近文档面板的内容。
  • 复选框组可以控制哪些商品价格在表格或图中实时追踪。
  • 标签(tab)控制其关联面板的显示。
特性:
特性
用于角色: 基础标记全部元素
值: ID reference list

aria-current 状态

指示在一组或容器内,表示当前项的元素

aria-current属性为token类型。若取值不在规定的允许列表内,辅助技术当作 true。若属性缺失、值为空字符串或 undefined,则默认 false,用户代理和辅助技术不得暴露该aria-current状态

该属性用于一组相关元素中,标记当前项在视觉上被高亮。例如:

  • page token 用于指示当前页。
  • step token 用于指示当前步骤。
  • location token 用于指示流程图等内部当前组件。
  • date token 用于指示日历当前日期。
  • time token 用于指示时间表等中的当前时间。

作者仅标记一组中的一个元素为当前(aria-current)。

作者不应在语义与 aria-selected 相同的小组件上用本属性替换 aria-selected。如 tablist 中,aria-selected 用于 tab 来指示当前显示的 tabpanel

部分小组件兼容 aria-selected 时,“current”和“selected”语义可并存。例如,导航 tree 中,aria-current="page" 指示当前页,而 aria-selected="true" 指示若激活后将显示哪一页。此外,同一树可通过上下文菜单实现批量操作(如“删除”“移动”)。

特性:
特性
用于角色: 基础标记全部元素
值: token
取值说明:
说明
page 表示一组页面中的当前页。
step 表示流程中的当前步骤。
location 表示环境或上下文中的当前位置。
date 表示日期集合中的当前日期。
time 表示时间集合中的当前时间。
true 表示集合中的当前项。
false (默认) 表示集合中非当前项。

aria-describedby 属性

标识元素(或若干元素)描述对象的内容。参见相关 aria-labelledbyaria-description

aria-labelledby 属性与 aria-describedby 类似,二者均引用其他元素,用于计算文本替代(分别为可访问名称和描述)。名称以简要为佳,描述可简短也可详尽。

aria-describedby 引用的一组或多个元素共同组成完整描述。需要可引多个元素 ID,或用ID包裹一组元素(如多个段落)。

特性:
特性
相关概念:
用于角色: 基础标记全部元素
值: ID reference list

aria-description 属性

定义用于描述或注释当前元素的字符串值。参见相关 aria-describedby

aria-description 属性与 aria-label 类似,二者都为元素提供一个简单的字符串(分别为可访问描述和名称)。不同于可访问名称通常尽量简明,描述可根据需要更详细。

aria-description 的作用与 aria-describedby 相同,为用户提供对象的补充描述文本。最常见的辅助功能API映射是 accessible description 属性。用户代理在计算 accessible description 属性时,必须优先考虑 aria-describedby,其次才是 aria-description

当提供可见描述不是期望用户体验时,作者可以使用 aria-description 设置元素的可访问描述。但如果描述文本已在 DOM 中,作者不应使用 aria-description,而应:

  • 当相关描述或注释元素只包含简短描述,适合以字符串直接体验,而无需用户逐一浏览时,作者aria-describedby
  • 当相关描述或注释元素包含丰富语义或结构,或内容较多,不宜平铺为一段字符串时,作者aria-details。这样可让辅助技术用户浏览结构化内容,更便捷地理解结构,或分片体验信息。
特性:
特性
相关概念:
用于角色: 基础标记全部元素
值: string

aria-details 属性

标识对象提供附加信息的元素(或若干元素)。参见相关 aria-describedby

aria-details 用于引用比 aria-describedby 提供的信息更详细的元素。设置了 aria-details 可让辅助技术 让用户知晓有扩展信息可用,并跳转至其内容。作者确保 aria-details 所引用的元素对所有用户都可见。

辅助技术可以利用 aria-details 所引用元素的角色,帮助用户理解与该元素相关的信息类型。作者可以如下表达细节类型:

  • 注释:aria-details 指向 role 为 comment 的元素。
  • 定义:aria-details 应用于 role 为 term 的元素,并指向 role 为 definition 的元素。
  • 图注:aria-details 应用于 role 为 figure 的元素,并指向 role 为 caption 的元素,或 caption 内的某元素。
  • 脚注:aria-details 指向 role 为 doc-footnote 的元素。该角色在 [DPUB-ARIA-1.0] 中定义。
  • 尾注:aria-details 指向 role 为 doc-endnote 的元素,定义同上。
  • 描述或通用注释:aria-details 指向其他任意角色元素。

不同于 aria-describedby 所引用的元素,aria-details 所引用的内容不会作为可访问描述计算而被扁平化为字符串。这可避免信息丢失或让扩展信息更易理解,尤其适用于无法简单转换为字符串的信息。

aria-details 可引用多个元素。例如文档编辑器中的段落可能与多个彼此无关的注释关联。若用户代理使用的辅助功能API 不支持暴露多重描述关系,用户代理只暴露对 aria-details 引用的第一个元素的关联。

元素可同时存在 aria-detailsaria-describedbyaria-description。如果辅助功能API不支持多重描述,且元素同时有 aria-detailsaria-describedby,则用户代理暴露 aria-details 关联及从 aria-describedby 计算的描述字符串。

aria-details 常用于数字出版领域,如书籍中需要结构化标记或嵌入其它技术以提供插图内容的扩展描述。如下例所示:

<!-- Provision of an extended description -->
<img src="pythagorean.jpg" alt="Pythagorean Theorem" aria-details="det">
<details id="det">
  <summary>Example</summary>
  <p>
    The Pythagorean Theorem is a relationship in Euclidean Geometry between the three sides of
    a right triangle, where the square of the hypotenuse is the sum of the squares of the two
    opposing sides.
  </p>
  <p>
    The following drawing illustrates an application of the Pythagorean Theorem when used to
    construct a skateboard ramp.
  </p>
  <object data="skatebd-ramp.svg"  type="image/svg+xml"></object>
  <p>
    In this example you will notice a skateboard ramp with a base and vertical board whose width
    is the width of the ramp. To compute how long the ramp must be, simply calculate the
    base length, square it, sum it with the square of the height of the ramp, and take the
    square root of the sum.
  </p>
</details>

或,aria-details 也可指向提供扩展描述的网页链接,如下所示:

<!-- Provision of an extended description -->
<img src="pythagorean.jpg" alt="Pythagorean Theorem" aria-details="det">
<p>
  See an <a href="http://foo.com/pt.html" id="det">Application of the Pythagorean Theorem</a>.
</p>
特性:
特性
用于角色: 基础标记全部元素
值: ID reference list

aria-disabled 状态

指示元素可感知但处于禁用状态,因此无法编辑或以其他方式可操作。参见相关 aria-hiddenaria-readonly

例如,单选框组中无关的选项可被禁用。被禁用的元素通常不会获得焦点。有些禁用元素,程序可能不允许导航到其下级。除设置 aria-disabled 外,作者改变其外观(如灰显)以体现禁用。

禁用状态适用于设置了 aria-disabled 的元素本身及其所有可聚焦的后代。

虽然 aria-disabled 配合脚本可让 role 为 link 的元素被禁用,但对宿主语言原生控件,可能难以完全禁用。建议不要对宿主语言本身不能禁止的元素用 aria-disabled。

: 在 columnheader、rowheader 与 row 上的用法

目前 aria-disabled 可用于 columnheaderrowheaderrow,但将来仅当其处于 gridtreegrid 环境下才允许。

本状态在 ARIA 1.2 中已作为全局状态弃用,后续版本仅允许在特定支持该特性的角色上使用。

特性:
特性
用于角色:
可继承到的角色:
值: true/false
取值说明:
说明
false (默认) 元素处于启用状态。
true 该元素及其所有可聚焦后代均被禁用,用户无法更改其值。

aria-flowto 属性

标识内容的备用阅读顺序中的下一个元素(或多个元素),允许辅助技术根据用户意愿覆盖默认文档源码顺序的阅读。

aria-flowto 只含一个ID引用时,辅助技术可在用户请求时绕过默认文档顺序,直接跳转到目标对象。若含有多个ID引用,则辅助技术应该将这些目标元素展现为可选路径。

不管含有一个还是多个ID引用,用户代理或辅助技术应该让用户可选择跳转到任意目标元素。路径名可由 aria-flowto 属性所指目标元素的名称确定。辅助功能API可提供命名路径关系

特性:
特性
用于角色: 基础标记全部元素
值: ID引用列表

aria-grabbed 状态

[ARIA 1.1已废弃] 指示拖放操作中元素的“已抓取”状态

预计 aria-grabbed 状态将被未来的WAI-ARIA新特性取代,建议将 aria-grabbed 视为废弃

aria-grabbed 设为 true 指明元素已被选中并准备拖拽。设为 false 表明该元素可被拖拽但当前未抓取。若未指定或设为 undefined(默认),则该元素不可被拖拽。

aria-grabbed 设为 true 时,作者应该更新所有候选放置目标的 aria-dropeffect 属性。当元素未抓取时(值为 falseundefined 或属性被移除),作者应该将相关放置目标的 aria-dropeffect 属性恢复为 none

特性:
特性
用于角色: 基础标记全部元素
值: true/false/undefined
取值说明:
说明
false 表示该元素支持被拖拽。
true 表示该元素已被“抓取”准备拖拽。
undefined (默认) 表示该元素不支持被拖拽。

aria-haspopup 属性

指示某元素可触发的交互式弹出元素(如菜单或对话框)的可用性和类型。

弹出元素通常以上方覆盖其他内容的形式出现。作者必须确保作为弹出内容容器的元素角色为 menulistboxtreegriddialog,且 aria-haspopup 的值与弹出容器的角色一致。

为了让弹出元素支持键盘访问,作者应该确保可触发弹窗的元素可聚焦、存在键盘方式触发弹窗,并且弹窗元素按焦点管理规范管理其全部后代的焦点。

aria-haspopup 是token类型。用户代理必须将任何非允许值(包含空字符串)视为 false。为兼容ARIA 1.0内容,用户代理必须aria-haspopuptrue 时等同于 menu

辅助技术和用户代理不应在属性值为 false 时暴露该属性。

此处的弹出元素并不包括 tooltip

仅当元素有可视指示将弹出内容时,aria-haspopup 最相关。例如许多下三角、箭头、…等符号已成弹窗标准视觉指示。若功能差异视觉上需区别,一般也应通过辅助技术传递。若没有视觉指示可弹出,建议考虑是否需用 aria-haspopup,不必要时应避免。

该属性将在ARIA 1.2后续作为全局属性废弃,未来只允许在明确支持的角色上使用。

特性:
特性
相关概念:
用于角色:
可继承到的角色:
值: token
取值说明:
说明
false (默认) 表示该元素没有弹出内容。
true 表示弹出内容为 menu
menu 表示弹出内容为 menu
listbox 表示弹出内容为 listbox
tree 表示弹出内容为 tree
grid 表示弹出内容为 grid
dialog 表示弹出内容为 dialog

aria-hidden 状态

指示元素是否会暴露给辅助功能API。参见相关 aria-disabled

用户代理根据元素是否被渲染来判定其隐藏状态,渲染通常由CSS控制,例如 display: none 元素不会被渲染。若某元素或其任一祖先未被渲染,或其 aria-hidden 属性为 true,则也视为隐藏

作者可以慎重地用 aria-hidden 来让屏幕可见内容不被辅助技术读取,仅当隐藏内容确实能提升无障碍体验(如去除冗余),且必须确保辅助技术能获取等价的意义和功能。

当把可见内容对辅助技术隐藏时,需考虑各种残障情况。例如有视力正常但运动障碍的用户用语音技术操作视觉界面,若作者把“前往结算”的可见链接隐藏,仅暴露“立即结账”,可能导致语音控制无法选中真实可见的界面元素。类似问题也会影响屏幕阅读器,例如电话辅助人员让盲人用户查找"Go to checkout"链接,但屏幕阅读器无法通过内容搜索快速找到。

当前 aria-hidden="false" 在不同浏览器中实现不一致。未来可用性改进前,请小心测试,不要过度依赖。

特性:
特性
用于角色: 基础标记全部元素
值: true/false/undefined
取值说明:
说明
false 元素如同被渲染一样暴露于辅助功能API。
true 元素被隐藏于辅助功能API。
undefined (默认) 元素的隐藏状态由用户代理根据其是否被渲染判断。

aria-invalid 状态

指示用户输入的值未符合应用期望的格式。参见相关 aria-errormessage

若值被判定为无效或超出范围,应用作者将该属性设为 true用户代理提醒用户出错。应用作者若可能给出修正建议。

当用户提交数据涉及 aria-requiredtrue 的字段时,作者可以aria-invalid 提示有错。但在用户未尝试提交前,仅因未输入数据,不应给必填组件加该属性。

为兼容后续扩展, aria-invalid 是 token 类型。对未在允许值列表内的值,用户代理必须true 处理。缺省、值为 false或空字符串时,默认值为false

本状态自 ARIA 1.2 起作为全局状态废弃,未来仅允许用于明确支持该特性的角色。

特性:
特性
用于角色:
可继承到的角色:
值: token
取值说明:
说明
grammar 检测到语法错误。
false (默认) 当前无检测到错误。
spelling 检测到拼写错误。
true 用户输入的值未通过校验。

aria-keyshortcuts 属性

定义作者实现的用于激活或聚焦元素的键盘快捷键。

aria-keyshortcuts 属性值是用空格分隔的快捷键列表,可用于激活命令或文本框控件。快捷键中的键表示物理按键,而不是所产生的字符。每个快捷键由一个或多个token通过加号("+")表示,包含零个或多个修饰键和唯一一个要同时按下的非修饰键。

作者必须严格按 UI Events KeyboardEvent key Values 规范,如"Alt"、"Control"、"Shift"、"Meta"、"AltGraph"。注意Meta为苹果键盘Command键,Alt为Option键。

合法的非修饰键名包括任意可打印字符(如"A"、"B"、"1"、"2"),“Plus”代表加号,“Space”代表空格键,以及 UI Events KeyboardEvent key Values 中定义的其它键,如"Enter"、"Tab"、"ArrowRight"、"PageDown"、"Escape"、“F1”等。"Space"用以区分空格键,因该规范中空格为' '会被当做空白字符处理。

作者必须将所有修饰键放在快捷键前部,所需非修饰键放最后。修饰键顺序无关,例如 "Alt+Shift+T" 与 "Shift+Alt+T" 等效,但 "T+Shift+Alt" 非法,“Alt”自身亦非法(必须有一个非修饰键)。

指定字母键时,大小写不敏感。如 "a" 和 "A" 等价。

实现快捷键时,应考虑目标键盘类型和布局,避免误用。例如在法语键盘,输入数字常需先按Control,"Control+2" 映射结果易歧义。

为避免冲突,大多键盘建议只用ASCII字母,不使用数字与常用标点;若字符依赖修饰键,必须写源码按键而非结果。比如美式键盘上的“%”为"Shift+5",“Shift+5”才对,不可直接写"%"或"Shift+%",而部分国际键盘上直接有“%”键则另当别论。

若键在宿主语言非法或导致字符串提前结束,可用转义序列。例如HTML中的单引号可用 &#39; 表示。

有效快捷键示例:

  • "A"
  • "Shift+Space"
  • "Control+Alt+."
  • "Control+Shift+&#39;"
  • "Alt+Shift+P Control+F"
  • "Meta+C Meta+Shift+C"

用户代理不得因该属性改变键盘行为。作者必须在脚本中处理键盘事件实现功能,该属性仅用于辅助技术将快捷键信息暴露给用户。

作者为所有用户提供便捷发现快捷键的方式,如悬浮提示,并必须保证应用于禁用元素的快捷键无效。

作者避免与操作系统、浏览器或辅助技术的快捷键冲突,并合理考虑上下文和生效条件。更多建议见 WAI-ARIA 作者实践

作者考虑快捷键在各语言、物理键盘上的适用性及本地化。

特性:
特性
相关概念:
用于角色: 基础标记全部元素
值: 字符串

aria-label 属性

定义为当前元素提供标签的字符串值。参见相关 aria-labelledby

aria-label 的作用与 aria-labelledby 相同。它为用户提供对象的可识别名称。最常见的无障碍API映射为 accessible name 属性。

大多数宿主语言会提供可用于为元素命名的属性(如HTML的 title 属性),但这通常会弹出浏览器提示。在希望DOM内容或提示框不出现时,作者可以aria-label 直接为元素设置可访问名称(前提是该元素未禁止使用该属性)。如果标签文本已存在于DOM(即通常为可见文本内容),作者优先用 aria-labelledby不应aria-label。某些情况下元素名称无法从DOM可编程获得,或引用DOM内容不是理想体验。作者禁止对明示或隐式禁止 aria-label 的 WAI-ARIA角色使用此属性。按照可访问名称和描述计算的规范,用户代理在计算可访问名称属性时应优先使用aria-labelledby,其次才是 aria-label

特性:
特性
用于角色: 基础标记的所有元素,以下角色除外: captioncodedefinitiondeletionemphasisgenericinsertionmarknoneparagraphstrongsubscriptsuggestionsuperscripttermtime
值: string

aria-labelledby 属性

标识为当前元素提供标签的元素(或多个元素)。参见相关 aria-labelaria-describedby

aria-labelledby 的作用与 aria-label 相同,为用户提供对象可识别名称。最常见的无障碍API映射为 accessible name 属性。

若界面无法有可视标签,作者使用 aria-label不应aria-labelledby。作者禁止对明示或隐式禁止 aria-labelledby 的WAI-ARIA角色元素指定该属性。参照可访问名称和描述计算规范,用户代理在计算可访问名称属性时应优先用aria-labelledby,其次才是 aria-label

aria-labelledby 属性与 aria-describedby 类似,均通过引用其他元素计算文本替代(分别为可访问名称和描述)。名称建议简明,描述则可为简要或详细信息。

该属性在美式英语应拼作 "labeledby"。不过,为与无障碍API映射规范一致,采用 "labelledby" 拼写,以减少开发者困惑。

特性:
特性
相关概念:
用于角色: 基础标记的所有元素,以下角色除外: captioncodedefinitiondeletionemphasisgenericinsertionmarknoneparagraphstrongsubscriptsuggestionsuperscripttermtime
值: ID引用列表

aria-level 属性

定义元素在结构内的层级。

这可应用于树结构中的树项、文档中的标题、嵌套网格、嵌套标签列表及其它结构性项。aria-level 的值必须为大于等于 1 的整数。

层级随嵌套加深而增加。若DOM结构不能准确表达层级,作者显式定义 aria-level 属性。

此属性应用于集合内作为叶节点的元素,如role为 treeitem 的元素,而不是 group。这意味着集合中多个元素可以有相同的层级属性值。虽然将该属性设在容器上可更简洁,但仅在叶节点设置可确保辅助技术有统一用法。

DOM结构能准确反映层级,则用户代理可自动算出每项层级。若无法计算,或用 aria-owns 属性时,也可用本属性显式指明。用户代理对层级的自动支持因平台不同,作者用主流用户代理和辅助技术测试是否需要本属性。若期望由用户代理自动检测,则省略此属性。

对于 treegridaria-level 应用于 role 为 row 的元素,而非 gridcell。虽然看起来和 treeitem 不一致,但这里 row 在垂直方向上是 grid 的叶节点,gridcell是每行横向的叶节点。level 不应用于行内单元格集合,所以只加在 row 元素。

在 role为 heading 的元素上,aria-level 超过 6 会带来可用性问题,目前绝大多数浏览器和辅助技术对 heading 的支持只到 1—9。

特性:
特性
用于角色:
值: integer

aria-live 属性

指示元素会被更新,并描述用户代理、辅助技术和用户可从实时区域获得的更新类型。

该属性的取值按重要程度划分。当设为 polite 时,辅助技术会通知用户更新,但通常不会打断当前操作,优先级较低。assertive 时,辅助技术会立刻通知用户,可能会清空已排队播报的先前更新内容。

礼貌级别本质上是对更新顺序的建议,可被用户代理、辅助技术甚至用户自身覆盖。例如若辅助技术判断某次更改源自键盘或鼠标,可能会即刻播报,即便 aria-live 属性值不是 assertive。

因不同用户需求不同,具体响应由辅助技术调整。辅助技术可实现多级粒度控制,便于用户控制队列与打断。

若对象需要更新但未设置该属性,则继承最近祖先上设置的aria-live值。

aria-live 是确定实时区域更新播报顺序的主要依据。实现时也会考虑角色的默认礼貌级别。例如 log 默认 polite。assertive项会立即播报,紧随其后为polite。遇assertive时可清空待播队列(如 assertive 区域变更可移除所有排队更新)。

对于 polite 区域,辅助技术在合适的时机播报(如句尾、用户暂停输入)。assertive立刻通知。因打断可能导致用户迷失或没完成当前任务,作者不应无必要地用 assertive。

特性:
特性
用于角色: 基础标记全部元素
值: token
取值说明:
说明
assertive 表明区域更新最高优先级,应立即呈现给用户。
off (默认) 表明仅当前聚焦于该区域时,区域更新才会播报,否则不会呈现给用户。
polite 表明区域更新应在适当机会呈现,如读完整句或用户停顿时。

aria-modal 属性

指示元素显示时是否为模态。

aria-modal 属性用于指明“模态”元素出现时页面其它内容不可用。例如弹出模态对话框时,用户交互应仅限于该对话框直至其失焦或关闭。

模态元素显示时,辅助技术转到该元素,除非焦点已被显式设置到别处。部分辅助技术会限制导航在模态内容内。如焦点移出模态外,辅助技术不应再限制导航范围。

模态元素显示时,作者必须保证接口仅用其后代控件可被操作。例如,模态对话框的关闭按钮须为对话框后代。显示模态元素时,作者将其它内容全部设为 inert(HTML 可利用“inert 子树”)。

特性:
特性
用于角色:
可继承到的角色:
值: true/false
取值说明:
说明
false (默认) 元素不是模态。
true 元素为模态。

aria-multiline 属性

指示文本框接受多行输入还是仅为单行。

在大多用户代理中,ENTERRETURN 键在HTML单行和多行文本框的默认行为不同。单行 <input type="text"> 输入回车通常提交表单,多行 <textarea> 回车插入换行。WAI-ARIA textbox 角色通过 aria-multiline 区分上述类型,作者在设计时需注意这种差异。

特性:
特性
用于角色:
可继承到的角色:
值: true/false
取值说明:
说明
false (默认) 这是单行文本框。
true 这是多行文本框。

aria-multiselectable 属性

指示用户可以从当前可选后代中选择多个项目。

作者保证已选中的后代元素设置 aria-selected 属性true,未选中的可选后代设置为 false。作者不应对不可选的后代使用 aria-selected

列表和树等角色可能允许用户同时选择多个项目。

特性:
特性
用于角色:
可继承到的角色:
值: true/false
取值说明:
说明
false (默认) 只能选中一个项目。
true 该组件可同时选中多个项目。

aria-orientation 属性

指示该元素的方向是水平、垂直还是未知/不明确。

在 ARIA 1.1 中,aria-orientation 的默认值由 horizontal 改为 undefined。部分角色有内置默认(如 slider 默认水平,scrollbar 默认垂直),但如 radiogroup 等缺省未定义。

特性:
特性
用于角色:
可继承到的角色:
值: token
取值说明:
说明
horizontal 元素为水平方向。
undefined (默认) 元素方向未知/不明确。
vertical 元素为垂直方向。

aria-owns 属性

标识一个或多个元素,用于在DOM层级无法表达父子关系时,定义可视、功能或上下文上的父子关系。参见相关 aria-controls

aria-owns 属性值为用空格分隔的ID列表,引用文档中的一个或多个元素。添加该属性的目的是告知辅助技术有无法从DOM推断的父子关系。

若元素同时拥有DOM子元素和 aria-owns,则对父子的排序顺序是先DOM子元素,再是 aria-owns 引用元素。若要DOM子元素不排首位,则在 aria-owns 中列出其ID以指定顺序。作者不应aria-owns 用作文档层级的替代,若DOM结构可表达该关系则不要使用本属性。

作者必须保证某元素ID不会同时出现在多个元素的 aria-owns 中。即每个元素只能有一个明确的“属主”。作者禁止aria-owns 构成循环引用。如出错,用户代理可以忽略部分 aria-owns 引用以保持内容关系一致。

特性:
特性
用于角色: 基础标记全部元素
值: ID引用列表

aria-placeholder 属性

定义用于帮助用户输入数据的简短提示(一个单词或短语),当控件无值时展示。该提示可为示例值或期望格式的简要说明。

作者不应aria-placeholder 替代表单标签,两者含义不同:标签指明预期内容类型,Placeholder 是输入内容的样例提示。参见相关 aria-labelledbyaria-label

作者在控件 value 为空字符串时展示该提示,包括首次聚焦时和用户清空已有值时。

与HTML的 placeholder 属性类似,用placeholder替代可视标签会降低一部分用户(包括老年人、认知、运动、精细动作/视觉障碍用户)的可访问性和易用性。标签提示始终显示,而placeholder仅在未输入时显示。且placeholder的颜色常常不够对比、无可见标签也会让控件命中区域变小,不利于聚焦。

如下例因HTML label 无法为 contenteditable 元素做可访问标签,未使用该元素。

以下示例展示用户已输入值的 searchbox

<span id="label">生日:</span>
<div contenteditable role="searchbox" aria-labelledby="label" aria-placeholder="MM-DD-YYYY">03-14-1879</div>

以下示例展示用户未输入值或已清空的同一个 searchbox

<span id="label">生日:</span>
<div contenteditable role="searchbox" aria-labelledby="label" aria-placeholder="MM-DD-YYYY">MM-DD-YYYY</div>
特性:
特性
相关概念:
用于角色:
可继承到的角色:
值: string

aria-posinset 属性

定义元素在当前 listitem 或 treeitem 集合中的编号或位置。如果集合全部元素都在DOM中,则无需设置。参见相关 aria-setsize

如集合全部项都在文档结构中,无需设置该属性,用户代理会自动计算每项在集合中的大小和位置。若某时点仅部分项在文档结构中,则需用本属性显式指明元素序号。

如下为16项集合中的第5至第8项:

<h2 id="label_fruit"> 可选水果 </h2>
<ul role="listbox" aria-labelledby="label_fruit">
  <li role="option" aria-setsize="16" aria-posinset="5"> 苹果 </li>
  <li role="option" aria-setsize="16" aria-posinset="6"> 香蕉 </li>
  <li role="option" aria-setsize="16" aria-posinset="7"> 哈密瓜 </li>
  <li role="option" aria-setsize="16" aria-posinset="8"></li>
</ul>

指定 aria-posinset 时,作者必须设为大于等于1且不大于集合总数的整数。若设置了 aria-posinset必须同时设置 aria-setsize

menuitemmenuitemcheckboxmenuitemradio 设置本属性时,按menu中的总项数(不含分隔符)计值。

特性:
特性
用于角色:
可继承到的角色:
值: integer

aria-pressed 状态

指示切换按钮(toggle button)的当前“按下”状态。参见相关 aria-checkedaria-selected

切换按钮需完整的按下-释放动作来改变其值。激活一次变为 true,再激活回为 falsemixed 代表按钮控制的多个项存在不同状态。若未设置该属性,则该按钮不是切换按钮。

aria-pressedaria-checked 相似但不完全相同。操作系统通常支持按钮的“按下”与复选框的“选中”。

特性:
特性
用于角色:
值: tristate
取值说明:
说明
false 按钮支持“按下”但当前未按下。
mixed 用于三态切换按钮,表示部分受控项不同状态。
true 按钮已按下。
undefined (默认) 按钮不支持“按下”状态。

aria-readonly 属性

表示该元素不可编辑,但仍可操作。参见相关 aria-disabled

这意味着用户可以读取该组件的值,但不能更改。只读元素对用户有意义,应用作者不应限制对该元素或其可聚焦后代的导航。也支持如复制元素值等其它操作。这与禁用元素相反,后者应用可能不允许用户导航至其后代。

实例包括:

  • 表示常量的表单元素。
  • 表格网格中的行或列标题。
  • 如购物车总价等计算结果。
特性:
特性
相关概念:
用于角色:
可继承到的角色:
值: true/false
取值说明:
说明
false (默认) 用户可以设置元素的值。
true 用户不能更改元素的值。

aria-relevant 属性

指示当实时区域的无障碍树被修改时,用户代理应触发哪些通知。参见相关 aria-atomic

属性的取值为用空格分隔的值列表,包括:additionsremovalstext;或表示所有的单一值all

本属性用于描述语义上的重要变化,而非仅仅是表现层的变化。例如,日志顶部移除节点只是为了腾出空间,不具有实际意义;但在好友列表中,删除好友名说明该好友已下线,这是有意义的事件,这种情况应设置all。未设置时默认值为additions text,即文本修改和节点添加为相关事件,节点移除则忽略。

aria-relevant 的 removals 或 all 取值应谨慎使用。只有当内容移除是重要变化(如聊天室好友离开)时,辅助技术才需获知。

只有指定了 'removals' 或 'all' 时,文本移除才被视为相关。例如实时区域文本从'foo'变为'bar',默认下只会播报'bar'的添加,不会播报'foo'的移除。

aria-relevant 是实时区可选属性。此处是对辅助技术的建议,辅助技术未必一定要呈现所有相关类型的变化。

未定义 aria-relevant 时,取值从最近祖先继承。尽管为token列表类型,但继承值不可累加,子元素上指定的值会完全覆盖祖先的。

设为相关的文本变化时,用户代理必须监控任何影响实时区可访问名称和描述计算的后代节点变化,如根据内容自动得出的可访问名称。有时如图片的alt属性文本变更也需触发更新;但若变更发生在实时区外,即使被 aria-labelledby 引用,也不会触发更改。

特性:
特性
用于角色: 基础标记全部元素
值: token列表
取值说明:
说明
additions 实时区域内有元素节点被添加到无障碍树中。
additions text (默认) 等同于 "additions text" 的组合值。
all 等同于 "additions removals text" 的组合。
removals 实时区的无障碍树内文本内容、替代文本或节点被移除。
text 文本内容或替代文本被添加到实时区的无障碍树任意后代节点。

aria-required 属性

指示在提交表单前,用户必须在该元素上输入内容。

例如,如果用户必须填写地址字段,作者需将该字段的 aria-required 属性设为 true

元素为必填信息通常也有可视提示(如控件后带符号)。通过 aria-required 明确告知辅助技术元素必填。

除非本地属性完全等价,宿主语言允许作者在要求输入或选择的控件上使用 aria-required 属性。

特性:
特性
相关概念:
用于角色:
可继承到的角色:
值: true/false
取值说明:
说明
false (默认) 该控件不是必填项。
true 表单提交前,用户必须在该控件输入内容。

aria-roledescription 属性

定义角色的本地化、可读性说明,供元素用。

部分辅助技术(如屏幕阅读器)会将元素角色展示给用户。这类辅助技术通常会本地化并自定义角色名。用户依赖这些角色呈现(如"region"、"button"、"slider"等)来了解元素功能、组件交互方式。

aria-roledescription 能让作者覆写辅助技术对角色名称的本地化及展示。因此,误用 aria-roledescription 可能影响用户理解和交互能力。作者仅在说明如 groupregion 这类非交互性容器时,或为widget提供更精确描述时使用。

使用 aria-roledescription 时,作者确保:

  1. 应用该属性的元素有明确ARIA角色或隐式语义角色。
  2. 属性值非空且不全为空格。

部分辅助技术、用户详细性设置等情形下,某些元素的角色描述可能不会被播报。如果为这类元素指定自定义角色描述,同样有可能不会被辅助技术读取。

此外,作者禁止在ARIA角色(明示或隐式)被禁止 aria-roledescription 的元素上使用本属性。

若满足以下任一情况,用户代理不得暴露该属性:

  1. 应用该属性的元素为不允许 aria-roledescription 的ARIA角色。
  2. 属性值未定义或为空。

辅助技术在播报元素角色时采用该值,但不应因此改变互动功能。例如辅助技术提供“下一个区域”或“下一个按钮”的导航,也应包含应用了 aria-roledescription 的区域和按钮。

下例演示用 aria-roledescription 向屏幕阅读器指明非交互容器为“幻灯片”:

<div role="article" aria-roledescription="slide" id="slide" aria-labelledby="slideheading">
<h1 id="slideheading">Quarterly Report</h1>
<!-- remaining slide contents -->
</div>
<article aria-roledescription="slide" id="slide" aria-labelledby="slideheading">
<h1 id="slideheading">Quarterly Report</h1>
<!-- remaining slide contents -->
</article>

在上述示例中,屏幕阅读器用户可能听到 “Quarterly Report, slide”,而非更模糊的 “Quarterly Report, article” 或 “Quarterly Report, group”。

特性:
特性
用于角色: 基础标记全部元素,以下角色除外: generic
值: string

aria-rowcount 属性

定义 tablegridtreegrid 中的总行数。参见相关 aria-rowindex

如果所有行都在 DOM 中,无需设置本属性用户代理会自动计算总行数。若某时刻仅有部分行在 DOM 中,则需用此属性明确完整表格总行数。

作者必须aria-rowcount 的值设为完整表格的总行数,若总行数未知,必须设为 -1,表示用户代理不应自行推算。

下例为2000行网格,仅显示首行和第100-102行:

<div role="grid" aria-rowcount="2000">
  <div role="rowgroup">
    <div role="row" aria-rowindex="1">
      <span role="columnheader">First Name</span>
      <span role="columnheader">Last Name</span>
      <span role="columnheader">Company</span>
      <span role="columnheader">Phone</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row" aria-rowindex="100">
      <span role="gridcell">Fred</span>
      <span role="gridcell">Jackson</span>
      <span role="gridcell">Acme, Inc.</span>
      <span role="gridcell">555-1234</span>
    </div>
    <div role="row" aria-rowindex="101">
      <span role="gridcell">Sara</span>
      <span role="gridcell">James</span>
      <span role="gridcell">Acme, Inc.</span>
      <span role="gridcell">555-1235</span>
    </div>
    <div role="row" aria-rowindex="102">
      <span role="gridcell">Taylor</span>
      <span role="gridcell">Johnson</span>
      <span role="gridcell">Acme, Inc.</span>
      <span role="gridcell">555-1236</span>
    </div>
  </div>
</div>
特性:
特性
用于角色:
可继承到的角色:
值: integer

aria-rowindex 属性

定义元素tablegridtreegrid 总行数下的行索引或位置。参见相关 aria-rowindextextaria-rowcountaria-rowspan

如所有行都在 DOM ,无需设置本属性用户代理可自动计算每行索引。若只显示部分行,则需用本属性明确每行在完整表格中的位置。

作者必须aria-rowindex为大于等于1的整数,高于同一表格内前一行aria-rowindex值,且不大于表格总行数。若单元格跨多行,必须设为跨度起始行号。

作者在每行设置 aria-rowindex。作者可以进一步为每行所有辅助技术子元素aria-rowindex

下例为2000行网格,仅显示首行和100-102行:

<div role="grid" aria-rowcount="2000">
  <div role="rowgroup">
    <div role="row" aria-rowindex="1">
      <span role="columnheader">First Name</span>
      <span role="columnheader">Last Name</span>
      <span role="columnheader">Company</span>
      <span role="columnheader">Phone</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row" aria-rowindex="100">
      <span role="gridcell">Fred</span>
      <span role="gridcell">Jackson</span>
      <span role="gridcell">Acme, Inc.</span>
      <span role="gridcell">555-1234</span>
    </div>
    <div role="row" aria-rowindex="101">
      <span role="gridcell">Sara</span>
      <span role="gridcell">James</span>
      <span role="gridcell">Acme, Inc.</span>
      <span role="gridcell">555-1235</span>
    </div>
    <div role="row" aria-rowindex="102">
      <span role="gridcell">Taylor</span>
      <span role="gridcell">Johnson</span>
      <span role="gridcell">Acme, Inc.</span>
      <span role="gridcell">555-1236</span>
    </div>
  </div>
</div>

下例为前例的网格,同时在每行的所有辅助技术子元素上均设了 aria-rowindex

<div role="grid" aria-rowcount="2000">
  <div role="rowgroup">
    <div role="row" aria-rowindex="1">
      <span role="columnheader" aria-rowindex="1">First Name</span>
      <span role="columnheader" aria-rowindex="1">Last Name</span>
      <span role="columnheader" aria-rowindex="1">Company</span>
      <span role="columnheader" aria-rowindex="1">Phone</span>
    </div>
  </div>
  <div role="rowgroup">
    <div role="row" aria-rowindex="100">
      <span role="gridcell" aria-rowindex="100">Fred</span>
      <span role="gridcell" aria-rowindex="100">Jackson</span>
      <span role="gridcell" aria-rowindex="100">Acme, Inc.</span>
      <span role="gridcell" aria-rowindex="100">555-1234</span>
    </div>
    <div role="row" aria-rowindex="101">
      <span role="gridcell" aria-rowindex="101">Sara</span>
      <span role="gridcell" aria-rowindex="101">James</span>
      <span role="gridcell" aria-rowindex="101">Acme, Inc.</span>
      <span role="gridcell" aria-rowindex="101">555-1235</span>
    </div>
    <div role="row" aria-rowindex="102">
      <span role="gridcell" aria-rowindex="102">Taylor</span>
      <span role="gridcell" aria-rowindex="102">Johnson</span>
      <span role="gridcell" aria-rowindex="102">Acme, Inc.</span>
      <span role="gridcell" aria-rowindex="102">555-1236</span>
    </div>
  </div>
</div>
特性:
特性
用于角色:
可继承到的角色:
值: integer

aria-rowindextext 属性

定义 aria-rowindex 的人类可读文本替代。参见相关 aria-colindextext

作者仅在 aria-rowindex 提供或计算的值不具意义或无法反映界面上显示的索引(如“战舰”游戏中)时才用 aria-rowindextext

作者不应aria-rowindextext 替代 aria-rowindex,因部分辅助技术需依赖数字行索引以追踪用户位置或实现辅助表格导航。

作者在每行上设置 aria-rowindextext。作者可以在每行的所有无障碍子元素上也设置 aria-rowindextext

特性:
特性
用于角色:
可继承到的角色:
值: string

aria-rowspan 属性

定义某单元格或 gridcell 在 tablegridtreegrid 中所跨的行数。参见相关 aria-rowindexaria-colspan

属性用于宿主语言原生表格外的单元格。若用在原生表格上,作者优先用宿主语言自身的属性而非ARIA属性。若宿主语言本身有等价属性,用户代理必须忽略 aria-rowspan,仅向辅助技术暴露宿主语言属性值。

作者必须aria-rowspan 的值设为大于等于0且不导致该单元格跨越本列下一个单元格的整数。0表示该单元格跨越行组内所有剩余行。

特性:
特性
用于角色:
可继承到的角色:
值: integer

aria-selected 状态

指示各种组件当前“选中”状态。参见相关 aria-checkedaria-pressed

属性用于指示单选或多选composite组件内哪些元素被选中。

optiontabtreeitem 允许用户代理在满足特定条件下提供 aria-selected 的隐式值。除这些情况外,用户代理不得隐式赋值 aria-selected。

特性:
特性
用于角色:
可继承到的角色:
值: true/false/undefined
取值说明:
说明
false 该可选元素未被选中。
true 该可选元素被选中。
undefined (默认) 该元素不可选。

aria-setsize 属性

定义当前 listitem 或 treeitem 集合中的总项数。如果集合全部元素都在DOM中,则无需设置。参见相关 aria-posinset

属性加在集合成员上而非容器。如果辅助技术介绍“第X项,共Y项”,则X等于 aria-posinset 的值,Y等于 aria-setsize

如集合中至当前项的全部项都在文档结构中,无需设置本属性用户代理可自动计算这些项的位置。若前项不全在文档结构里,作者必须设置本属性明确该元素在集合中的位置。

指定 aria-setsize 时,作者必须设为集合总数整数。若集合总数未知,作者设为 -1

menuitemmenuitemcheckboxmenuitemradio 设置本属性时,按menu中总项数(不含分隔符)来计。

下例为16项集合中的第5至第8项:

<h2 id="label_fruit"> 可选水果 </h2>
<ul role="listbox" aria-labelledby="label_fruit">
  <li role="option" aria-setsize="16" aria-posinset="5"> 苹果 </li>
  <li role="option" aria-setsize="16" aria-posinset="6"> 香蕉 </li>
  <li role="option" aria-setsize="16" aria-posinset="7"> 哈密瓜 </li>
  <li role="option" aria-setsize="16" aria-posinset="8"></li>
</ul>

下例为总数未知集合的第5至第8项:

<h2 id="label_fruit"> 可选水果 </h2>
<ul role="listbox" aria-labelledby="label_fruit">
  <li role="option" aria-setsize="-1" aria-posinset="5"> 苹果 </li>
  <li role="option" aria-setsize="-1" aria-posinset="6"> 香蕉 </li>
  <li role="option" aria-setsize="-1" aria-posinset="7"> 哈密瓜 </li>
  <li role="option" aria-setsize="-1" aria-posinset="8"></li>
</ul>
特性:
特性
用于角色:
可继承到的角色:
值: integer

aria-sort 属性

指示表格或网格中的项是按升序还是降序排序。

作者只将本属性应用于表头或网格头。未设置该属性则无排序定义。每个表/网格内,作者只在唯一一个表头设置 aria-sort

特性:
特性
用于角色:
值: token
取值说明:
说明
ascending 项按升序排列。
descending 项按降序排列。
none (默认) 没有定义排序。
other 应用了升/降序外的排序方式。

aria-valuemax 属性

定义范围组件允许的最大值。

作者必须确保 aria-valuemax 的值大于等于 aria-valuemin。若 aria-valuenow 有已知最大/最小,作者提供 aria-valuemaxaria-valuemin 属性。

区间组件有初始值,可逐步增至本属性定义的最大值。声明最大/最小值便于辅助技术告知用户范围大小。

特性:
特性
相关概念:
用于角色:
可继承到的角色:
值: number

aria-valuemin 属性

定义范围组件允许的最小值。

作者必须确保 aria-valuemin 的值小于等于 aria-valuemax。若 aria-valuenow 有最大/最小,作者也提供 aria-valuemaxaria-valuemin

区间组件有初始值,可逐步减至本属性定义的最小值。声明最大/最小值便于辅助技术告知用户范围大小。

特性:
特性
相关概念:
用于角色:
可继承到的角色:
值: number

aria-valuenow 属性

定义范围组件的当前值。参见相关 aria-valuetext

如滑块、进度条等区间组件可用本属性。

若当前值未知(如不确定进度条),作者不应设置 aria-valuenow 属性。属性缺省则代表当前值未知。若有最大/最小,作者提供 aria-valuemaxaria-valuemin

aria-valuenow 的值为十进制数。若区间为数值区间,则值应为其中一个。例如取值[0, 1],有效值如0.5,-2.5、1.1无效。

对于 progressbarscrollbar,辅助技术以百分比形式呈现,依据 aria-valueminaria-valuemax 计算。若未设置,则直接读实际数值。sliderspinbutton 直接读实际数值。

若实际呈现值不能用数字表示,作者配合设置 aria-valuetext,为用户呈现友好可读值。例如滑块呈现为smallmediumlarge,则 aria-valuetext 为文字, aria-valuenow 则用数值表示对应位置。

若同时设置 aria-valuetext,则辅助技术优先读文本值,不读 aria-valuenow

特性:
特性
相关概念:
用于角色:
可继承到的角色:
值: number

aria-valuetext 属性

定义区间组件当前值 (aria-valuenow) 的人类可读文本替代。

如滑块、进度条等区间组件可用本属性。

若设置 aria-valuetext,作者也设置 aria-valuenow,除非当前值未知(如不确定进度条)。

作者只在实际展示值无法用数字表示时设置 aria-valuetext。如滑块视觉为smallmediumlarge,则 aria-valuenow 为1~3的数表示每值区间,aria-valuetext 则为 'small'、'medium'、'large'。若不设置 aria-valuetext,辅助技术只读 aria-valuenow

若设置 aria-valuetext,辅助技术优先读其值,不读 aria-valuenow

特性:
特性
用于角色:
可继承到的角色:
值: string

7. 无障碍树

无障碍树DOM树是并行结构。无障碍树包含用户代理的用户界面对象和文档对象。每个需要暴露给辅助技术DOM元素,在无障碍树中都会创建一个无障碍对象,无论是因为它可能触发无障碍事件,还是因其具有需要暴露的属性关系或特性。

7.1 从无障碍树中排除元素

以下元素不会通过无障碍API暴露,用户代理不得将它们加入无障碍树

若上述规则未将元素排除,用户代理不应包含以下元素于无障碍树:

7.2 包含元素进无障碍树

若未被无障碍树中元素排除的规则排除,用户代理必须为满足以下任一条件的DOM元素无障碍树中提供一个无障碍对象

7.3 无障碍树中的关系

下列术语用于描述DOM元素间的关系。

无障碍子元素 指某DOM元素对应无障碍对象无障碍树中的所有子对象。对于DOM来说,包括(下列排除项除外):

同时不包括以下情况:

如下例中,list 元素有四个无障碍子元素:

<div role="list" aria-owns="child3 child4">
  <div role="listitem">Accessibility Child 1</div>
  <div>
    <div role="listitem">Accessibility Child 2</div>
  </div>
</div>
<div id="child3" role="listitem">Accessibility Child 3</div>
<div id="child4">
  <div role="listitem">Accessibility Child 4</div>
</div>

下例中,第一个list无无障碍子元素,第二个list 有一个无障碍子元素,即ID为 "reparented" 的listitem

<div role="list">
  <div role="listitem" aria-hidden="true">Excluded element</div>
  <div role="listitem" id="reparented">Reparented element</div>
</div>
<div role="list" aria-owns="reparented"></div>

无障碍后代 指所有在无障碍树中作为对应无障碍对象后代的DOM元素。

无障碍父元素 是指DOM元素对应无障碍对象无障碍树中的父节点。对于DOM而言,无障碍父元素可能为以下之一:

下列四个示例均包含一个listitem元素,其无障碍父元素为 role 为 list

<div role="list">
  <div role="listitem">The "list" is my accessibility parent.</div>
</div>
<div role="list">
  <div>
    <div role="listitem">The "list" is my accessibility parent.</div>
  </div>
</div>
<div role="list" aria-owns="child"></div>
<div id="child" role="listitem">The "list" is my accessibility parent.</div>
<div role="list" aria-owns="child"></div>
<div id="child">
  <div role="listitem">The "list" is my accessibility parent.</div>
</div>

8. 在宿主语言中的实现

本规范中定义的角色状态属性本身不构成完整的网页语言或格式,旨在配合宿主语言使用。本节讨论宿主语言如何实现 WAI-ARIA,以确保本文所述的标记能与宿主语言标记平滑有效地集成。

虽然标记语言在表面上看起来相似,但它们没有共享的语言定义基础。为适配不同的语言构建方式,相关要求既有通用,也有针对模块化的部分。在允许各自规范写法不同的同时,目标是在WAI-ARIA信息对作者的表现和脚本在DOM中的操作方式上保持一致性。

WAI-ARIA 角色、状态和属性作为属性实现于元素。角色通过出现在宿主语言 role 属性值中的 token 予以应用。每个状态和属性为单独的属性,具体取值详见本规范对每一状态和属性的定义。属性名是以 aria- 为前缀的状态或属性名。

8.1 Role 属性

实现的宿主语言将提供一个role 属性,具有以下特征:

8.2 状态和属性属性

实现的宿主语言必须允许具有如下特征的属性

支持 XML 名空间 [XML-NAMES] 的宿主语言 可以要求 WAI-ARIA 属性加上命名空间。这种情况下,WAI-ARIA 状态和属性的命名空间必须http://www.w3.org/ns/wai-aria/。在未明文支持的宿主语言中使用时,若宿主语言支持命名空间,且希望代理能识别 WAI-ARIA 命名空间,也用此命名空间。命名空间前缀本规范未定义,但通常为 "aria"。

WAI-ARIA 状态和属性统一以 "aria-" 为前缀。这并非命名空间前缀,而是状态或属性名自身的一部分。因此如果与命名空间合用,完整属性名如 "aria:aria-foo"。

某些宿主语言不用命名空间表示 WAI-ARIA 状态和属性名,可能因宿主语言不支持命名空间,或开发者希望将 WAI-ARIA 纳入核心特性。在这些宿主语言中属性无命名空间,其属性名也不用冒号。在命名空间规范上,通常称为“无前缀属性名”。如 DOM 接口 getAttributeNS,空字符串 "" 代表无命名空间,所以 getAttribute("aria-busy")getAttributeNS("", "aria-busy") 都访问 DOM 中的 aria-busy 属性。

按本节要求,有些用户代理识别加命名空间的 WAI-ARIA 属性,有些识别不加的,也有两者都可。作者应了解所用宿主语言支持哪种形式。除非宿主语言和代理明确要求必须命名空间,建议不用命名空间。即使支持命名空间代理,通常也不会向无障碍API暴露命名空间属性。尤其现在 HTML 及 XHTML 实现都不支持此命名空间。

8.3 焦点导航

实现的宿主语言必须允许作者让所有可交互元素可聚焦,即任何可渲染或可响应事件的元素。实现的宿主语言必须提供机制让网页作者决定这些可聚焦交互元素是否出现在默认Tab导航序。HTML里的tabindex属性即是一种实现方式。

8.4 隐式 WAI-ARIA 语义

WAI-ARIA 设计用于在宿主语言本身不带语义时为对象提供语义信息。但WAI-ARIA 也可为许多宿主语言增强其语义。此外,宿主语言也可能不断进化,提供与 WAI-ARIA 对应的新原生特性。因此,在很多情况下 WAI-ARIA 语义和宿主语义冗余。

这些宿主语言特性可以视为含有“隐式 WAI-ARIA 语义”。用户代理对带隐式 WAI-ARIA 语义特性的处理会类似对应 WAI-ARIA 特性的处理。两者可能因词法差异存在细微不同,但通常向无障碍API暴露等价信息。含隐式 WAI-ARIA 语义的特性满足如“必须有无障碍父角色”、“允许无障碍子角色”、“必须的状态和属性”等结构性要求,无须再显式声明 WAI-ARIA 语义。在具有隐式 WAI-ARIA 角色的元素上,作者还可以直接用该角色支持的 WAI-ARIA 状态和属性,无须再显式指定角色。

例如,如果现有元素已经包含此功能(如复选框或单选按钮),应使用宿主语言的原生语义。WAI-ARIA 标记仅用于增强原生语义(如用 aria-required 指明必填),或将元素语义变为与原功能不同的用途。

隐式 WAI-ARIA 语义影响下一节“与宿主语义冲突”中的冲突解决。因此,隐式 WAI-ARIA 语义需在规范性文档中明确定义,如宿主语言标准或 Core Accessibility API Mappings

8.5 与宿主语言语义冲突

WAI-ARIA 角色、状态和属性,目的是在没有原生语义的宿主元素上补充语义信息,通常用于本身无原生语义的元素。也可用于类似但非完全相同语义的元素(如用嵌套列表作为树结构)。这种方法可作为早期无 WAI-ARIA 支持浏览器的降级策略,也可能因复用原生表现而减少样式或脚本量。除了下文列出的例外,用户代理必须始终用 WAI-ARIA 语义定义暴露给无障碍API的内容,而不采用宿主语言自身语义。

除了正常希望 WAI-ARIA 覆盖原生语义的情形,还存在不应由 WAI-ARIA 覆盖的元素。这类情况包括:存在完全相同原生语义时,无需使用 WAI-ARIA;或 WAI-ARIA 和宿主语义直接冲突。当宿主语言已有等价角色和取值,且作者没有强烈理由规避宿主特性时,优先使用宿主语言特性,不要用 WAI-ARIA 重定义其它元素。

宿主语言可以有与角色对应的隐式 WAI-ARIA 语义。当元素加了 WAI-ARIA 角色,用户代理必须WAI-ARIA 角色的语义,而不是原生语义,除非宿主语言里的原生实现明确禁止该角色要求的WAI-ARIA状态和属性。角色的取值不会像状态和属性那样产生冲突(比如 HTML 的 'checked' 和 aria-checked 可能冲突),作者即使在不推荐复用的元素上加 WAI-ARIA 角色,也要给出合理理由。

WAI-ARIA 状态和属性与宿主语言本身具备的隐式 WAI-ARIA 语义重复时,一旦 WAI-ARIA 和宿主特性值不同步,用户代理和辅助技术无法知晓实际该采用哪个值。为避免冲突,宿主语言必须明确声明哪些 WAI-ARIA 属性在元素上与原生特性语义冲突。若 declared 为直接语义冲突,用户代理必须忽略 WAI-ARIA 属性,而用宿主语言同义特性。

宿主语言可以说明哪些特性不能被 WAI-ARIA 覆盖(即“强原生语义”)。包括含隐式 WAI-ARIA 语义的特性,也包括若允许 WAI-ARIA 改变语义会造成处理混乱的特性。校验工具可以向在强原生语义元素上用 WAI-ARIA 角色报错或警告,但如上所述,除非原生语义永远仅用于表现,用户代理必须仍用 WAI-ARIA 角色的语义暴露至无障碍API。

宿主语言得以对 WAI-ARIA 覆盖原生特性的行为制约,是为防止作者误用或破坏原生特性固有处理逻辑。例如ARAI特性和原生重叠但不完全一致时,仅变更一方易引起API暴露混乱。固有处理指超越简单渲染和API暴露的机制,如允许ARIA参与会导致不可预测后果,因此有理由限制。需要强调的是,宿主语言的这种限制应仅在内容处理的正确性受到影响时采用,不可随意定义所有ARIA特性均不可覆盖。

有些 ARIA 特性对无障碍API的完整建模至关重要,这些特性不会与原生语义冲突(但可补充)。因此,宿主语言禁止对下述 ARIA 特性声明强原生语义,不允许使用:

8.6 状态和属性处理

状态和属性包含在宿主语言中,其值类型语法由宿主语言决定。对于Value中定义的每种值类型,使用宿主语言中对应的数据类型。推荐的 WAI-ARIA 与宿主语言类型映射见 WAI-ARIA 值类型与语言映射,该映射非规范性,为便于新宿主语言支持 WAI-ARIA

ID引用列表和token列表这类值类型允许出现多个对应类型值。用宿主语言认可的分隔符分割多个值,比如空格、逗号等。有些语言要求某一特定分隔符,有些允许多种分隔符。

全局状态和属性适用于宿主语言中任意元素。但必须只在支持该状态或属性的角色元素(无论显式WAI-ARIA角色,还是由宿主语言隐式映射的ARIA角色)上应用非全局状态和属性。当role属性加到元素上,元素的语义和行为,包括支持的ARIA状态和属性,都会被角色行为增强或覆盖。用户代理必须忽略无角色支持(无论显式ARIA角色还是隐式ARIA角色)的元素上用到的非全局状态和属性。例如 aria-valuetext 可用于 progressbar

WAI-ARIA 角色有“支持”或“必须”状态和属性。例如 combobox 角色 支持的属性有 aria-autocomplete,因为某些 combobox 组件实现了自动补全。对比之下,combobox 角色必须aria-expanded 状态以标明可展开(PopUp控件如 listbox 是打开还是关闭)。如果已打开则为展开,否则为折叠。

当使用 WAI-ARIA 角色时,未在DOM出现的“支持”状态和属性按默认值处理。例如缺省 aria-autocomplete 表示无自动补全(等价 aria-autocomplete="none")。

但缺失必须的状态和属性属于作者错误,处理详见处理作者错误

含隐式 WAI-ARIA 语义的元素,支持该角色的全部 WAI-ARIA 状态和属性。故作者可以省略role,只设状态和属性;只有在需要改变元素隐式ARIA角色时才需显式role。

有时状态和属性出现在 DOM 但值为空串("")。作者可以为任意“支持的”(但不是必需的)状态/属性赋空串值。用户代理等同于属性缺省处理:对“支持”属性用默认值处理,对“必须”属性则视为作者错误,详见处理作者错误

8.6.1 ID引用错误处理

用户代理忽略与文档内任何元素ID都不匹配的ID引用。

确保ID唯一是网页作者责任。若有多个元素同ID,用户代理选第一个(行为同 getElementById)。

单个 WAI-ARIA 关系中同一元素被多次引用,用户代理多次返回该元素指针。

aria-activedescendant 只能引用单一ID。任何缺省ID引用的 aria-activedescendant 都是作者错误,不会匹配任何 DOM 元素。

8.7 CSS 选择器

本节未来版本可能会被移除。

属性选择器的支持必须涵盖 WAI-ARIA 属性。例如,.fooMenuItem[aria-haspopup="true"] 会选取所有 class 为 fooMenuItem,且 WAI-ARIA 属性 aria-haspopup 值为 true元素。对 WAI-ARIA 属性的动态变动必须及时更新样式。这样有助于作者基于 WAI-ARIA 语义匹配样式。

9. 处理作者错误

9.1 角色

用户代理通常会对 WAI-ARIA 角色进行校验。

角色定义章节所述,在内容中使用抽象角色属于作者错误。用户代理不得通过无障碍 API 的标准角色机制映射抽象角色。

如果 role 属性不含与任意非抽象 WAI-ARIA 角色名称匹配的 token,则用户代理必须视为该元素未提供 role。例如,<table role="foo"><table> 应实现一致,对 <input type="text" role="structure"> 也是如此,与 <input type="text"> 相同。

部分地标角色要求作者提供名称。若作者未为这些地标指定名称,视为作者错误。用户代理必须将该元素视为未提供 role。如果指定了有效的回退角色,或者该元素有隐含 ARIA 角色,则用户代理应继续暴露该角色。典型如以下角色:

9.2 状态与属性

一般来说,用户代理WAI-ARIA 属性不做太多校验。但用户代理可以根据需要做轻量校验,比如强制要求 aria-posinset 必须在 1 与 aria-setsize 之间。用户代理不负责逻辑校验,例如下列情况:

  1. 由关系属性导致的循环引用(比如两个元素互为所有者)。
  2. 正确的 DOM 树结构使用,比如一个元素被多个元素作为 owner。
  3. WAI-ARIA 角色的元素是否真正实现了该角色行为。例如用户代理不会检查一个设为 checkbox 的元素是否真如复选框一样表现。
  4. 元素未严格遵循所需的父/子角色关系或出现在不允许的父元素外。
  5. 确定 aria-activedescendant 实际是否指向容器控件的无障碍后代
  6. 部分集合成员指定了 aria-setsizearia-posinset 时,确定他们的隐含值。

如果作者为十进制或整数类型属性指定了非数值,用户代理按如下处理:

WAI-ARIA 属性包含未知或不允许的值,用户代理按如下方式暴露给平台 无障碍 API

UIA 中,用户代理可能将相关属性置为“unsupported”。

用户代理不得暴露引用未解析ID的 WAI-ARIA 属性。例如:

若某角色的必需 WAI-ARIA 属性缺失,用户代理按下表中指定的值处理该属性。

缺失必需属性的回退值
WAI-ARIA 角色 必需属性 回退值
checkbox aria-checked false
combobox aria-controls 无映射
combobox aria-expanded false
heading aria-level 2
menuitemcheckbox aria-checked false
menuitemradio aria-checked false
radio aria-checked false
scrollbar aria-controls 无映射
scrollbar aria-valuenow 如果缺失或不是数字,则为(aria-valuemax - aria-valuemin) / 2。如小于aria-valuemin,用aria-valuemin。如大于aria-valuemax,用aria-valuemax
separator(若可聚焦) aria-valuenow 如果缺失或不是数字,则为(aria-valuemax - aria-valuemin) / 2。如小于aria-valuemin,用aria-valuemin。如大于aria-valuemax,用aria-valuemax
slider aria-valuenow 如果缺失或不是数字,则为(aria-valuemax - aria-valuemin) / 2。如小于aria-valuemin,用aria-valuemin。如大于aria-valuemax,用aria-valuemax
switch aria-checked false
meter aria-valuenow 取隐含或已设 aria-valuemin 的值。

非必需状态和属性的隐含值见各角色特性表,这些不属于此处的回退值。

9.3 表现型角色冲突解决

对表现型角色的冲突有多种处理方式。

用户代理不得在无障碍树中暴露显式声明或继承得来的表现型角色元素,但下列情况除外:

例如,aria-describedby 是全局属性,广泛应用;aria-level 非全局属性,仅当元素不为表现型才起作用。

<!-- 1. 由于全局 aria-describedby 属性,[role="none"] 被忽略。 -->
<h1 role="none" aria-describedby="comment-1"> Sample Content </h1>
<!-- 2. [role="none"] 屏蔽了隐式 'heading' 和非全局 aria-level。 -->
<h1 role="none" aria-level="2"> Sample Content </h1>

10. IDL 接口

符合规范的用户代理必须实现以下IDL接口。

10.1 接口混入 ARIAMixin

WebIDLinterface mixin ARIAMixin {
	[CEReactions] attribute DOMString? role;
	[CEReactions] attribute Element? ariaActiveDescendantElement;
	[CEReactions] attribute DOMString? ariaAtomic;
	[CEReactions] attribute DOMString? ariaAutoComplete;
	[CEReactions] attribute DOMString? ariaBusy;
	[CEReactions] attribute DOMString? ariaChecked;
	[CEReactions] attribute DOMString? ariaColCount;
	[CEReactions] attribute DOMString? ariaColIndex;
	[CEReactions] attribute DOMString? ariaColIndexText;
	[CEReactions] attribute DOMString? ariaColSpan;
	[CEReactions] attribute FrozenArray<Element>? ariaControlsElements;
	[CEReactions] attribute DOMString? ariaCurrent;
	[CEReactions] attribute FrozenArray<Element>? ariaDescribedByElements;
	[CEReactions] attribute DOMString? ariaDescription;
	[CEReactions] attribute FrozenArray<Element>? ariaDetailsElements;
	[CEReactions] attribute DOMString? ariaDisabled;
	[CEReactions] attribute FrozenArray<Element>? ariaErrorMessageElements;
	[CEReactions] attribute DOMString? ariaExpanded;
	[CEReactions] attribute FrozenArray<Element>? ariaFlowToElements;
	[CEReactions] attribute DOMString? ariaHasPopup;
	[CEReactions] attribute DOMString? ariaHidden;
	[CEReactions] attribute DOMString? ariaInvalid;
	[CEReactions] attribute DOMString? ariaKeyShortcuts;
	[CEReactions] attribute DOMString? ariaLabel;
	[CEReactions] attribute FrozenArray<Element>? ariaLabelledByElements;
	[CEReactions] attribute DOMString? ariaLevel;
	[CEReactions] attribute DOMString? ariaLive;
	[CEReactions] attribute DOMString? ariaModal;
	[CEReactions] attribute DOMString? ariaMultiLine;
	[CEReactions] attribute DOMString? ariaMultiSelectable;
	[CEReactions] attribute DOMString? ariaOrientation;
	[CEReactions] attribute FrozenArray<Element>? ariaOwnsElements;
	[CEReactions] attribute DOMString? ariaPlaceholder;
	[CEReactions] attribute DOMString? ariaPosInSet;
	[CEReactions] attribute DOMString? ariaPressed;
	[CEReactions] attribute DOMString? ariaReadOnly;
	
	[CEReactions] attribute DOMString? ariaRequired;
	[CEReactions] attribute DOMString? ariaRoleDescription;
	[CEReactions] attribute DOMString? ariaRowCount;
	[CEReactions] attribute DOMString? ariaRowIndex;
	[CEReactions] attribute DOMString? ariaRowIndexText;
	[CEReactions] attribute DOMString? ariaRowSpan;
	[CEReactions] attribute DOMString? ariaSelected;
	[CEReactions] attribute DOMString? ariaSetSize;
	[CEReactions] attribute DOMString? ariaSort;
	[CEReactions] attribute DOMString? ariaValueMax;
	[CEReactions] attribute DOMString? ariaValueMin;
	[CEReactions] attribute DOMString? ariaValueNow;
	[CEReactions] attribute DOMString? ariaValueText;
};

包含 ARIAMixin 的接口必须提供以下算法:

对于在 ARIAMixin 中定义的每个 IDL 属性 idlAttribute,在取值时必须执行以下步骤:

  1. contentAttribute 为通过在 ARIA 属性对应表中查找 idlAttribute 得到的 ARIA 内容属性。

  2. 返回以下操作的结果:以 this、idlAttributecontentAttribute 作为输入,调用 ARIAMixin getter 步骤

同理,在赋值时必须执行以下步骤:

  1. contentAttribute 为通过在 ARIA 属性对应表中查找 idlAttribute 得到的 ARIA 内容属性。

  2. 以 this、idlAttributecontentAttribute 及给定的值为参数,调用 ARIAMixin setter 步骤

这个非常通用的框架的动机在于,希望不同的宿主接口(如 ElementElementInternals)能够为这些 IDL 属性提供不同的行为。另一种做法是要求每个宿主接口独立重复这些 IDL 属性,以便它们可以指定独立的行为,但这样做存在它们不同步的高风险。

10.2 ARIA 属性对应表

下表给出了用于 ARIAMixin 的 IDL 属性名和内容属性名之间的对应关系。

IDL 属性 反映的 ARIA 内容属性
role role
ariaActiveDescendantElement aria-activedescendant
ariaAtomic aria-atomic
ariaAutoComplete aria-autocomplete
ariaBusy aria-busy
ariaChecked aria-checked
ariaColCount aria-colcount
ariaColIndex aria-colindex
ariaColIndexText aria-colindextext
ariaColSpan aria-colspan
ariaControlsElements aria-controls
ariaCurrent aria-current
ariaDescribedByElements aria-describedby
ariaDescription aria-description
ariaDetailsElements aria-details
ariaDisabled aria-disabled
ariaErrorMessageElements aria-errormessage
ariaExpanded aria-expanded
ariaFlowToElements aria-flowto
ariaHasPopup aria-haspopup
ariaHidden aria-hidden
ariaInvalid aria-invalid
ariaKeyShortcuts aria-keyshortcuts
ariaLabel aria-label
ariaLabelledByElements aria-labelledby
ariaLevel aria-level
ariaLive aria-live
ariaModal aria-modal
ariaMultiLine aria-multiline
ariaMultiSelectable aria-multiselectable
ariaOrientation aria-orientation
ariaOwnsElements aria-owns
ariaPlaceholder aria-placeholder
ariaPosInSet aria-posinset
ariaPressed aria-pressed
ariaReadOnly aria-readonly
ariaRequired aria-required
ariaRoleDescription aria-roledescription
ariaRowCount aria-rowcount
ariaRowIndex aria-rowindex
ariaRowIndexText aria-rowindextext
ariaRowSpan aria-rowspan
ariaSelected aria-selected
ariaSetSize aria-setsize
ariaSort aria-sort
ariaValueMax aria-valuemax
ariaValueMin aria-valuemin
ariaValueNow aria-valuenow
ariaValueText aria-valuetext

注意:属性 aria-dropeffectaria-grabbed 在 ARIA 1.1 中已被弃用,并且没有对应的 IDL 属性。

10.2.1 歧义消除模式

本节为非规范性说明。

虽然规范作者可以对此模式做出例外处理,以下规则用于消除上表所列 IDL 属性名称和大小写的歧义。

  • 任何引用两个或多个单词组合概念的属性名(如“value text”)会转化为驼峰式 IDL 属性,每个单词边界首字母大写。例如,aria-valuetext 变为 ariaValueText,其中 V 和 T 都大写。
  • 同理,任何参考可以用连字符连接的概念(比如“multi-selectable”)的属性名,会以连字符拆分点转为驼峰式,连字符后的首字母大写。例如,“multi-selectable”的唯一正确拼写是带连字符的,因此 aria-multiselectable 变为 ariaMultiSelectable,M 和 S 都大写。
  • 当权威词典来源同时收录带连字符和不带连字符拼写(如“multi-line”和“multiline”都有效),则使用带连字符的版本,并应用上面的连字符规则。例如,aria-multiline 变为 ariaMultiLine,M 和 L 大写。
  • 如果所有权威词典来源仅给出没有空格或连字符的复合词,则仅将该词的首字母大写。例如,“place-holder”和“place holder”都不是“placeholder”的正确拼写,因此 aria-placeholder 变为 ariaPlaceholder,只有 P 大写。
  • 目前还没有基于缩写的 ARIA 属性,但如果未来有相关属性,应尽量匹配现有 DOM 约定(如 ID 变为 Id)。

10.2.2 IDL 属性命名说明或特殊情况

本节为非规范性说明。

任何特定属性名称的说明或特殊情况会在此列出。

  • ariaPosInSetaria-posinset 属性指的是项目在集合中的位置(两个单词:“in set”),而不是集合首元素起始的“inset”。因此,IDL 属性名应为 ariaPosInSet(P、I 和第二个 S 大写),不是 ariaPosInset

10.3 ARIAMixin 混入到 Element

用户代理 MUST 必须在 Element 上包含 ARIAMixin

WebIDLElement includes ARIAMixin;

对于 Element

在实践中,这意味着例如,Element 上的 role IDL 会反映 role 内容属性;ariaValueMin IDL 属性会反映 aria-valuemin 内容属性;等等。

10.4 IDL 属性使用示例

本节为非规范性说明。

ARIA IDL 属性反射的主要目的是简化基于 JavaScript 的值操作。以下示例展示其用法。

11. 安全考虑

本节为非规范性说明。

本规范未引入新的安全注意事项。

12. 隐私考虑

本节为非规范性说明。

根据 Web Platform Design Principles,本规范不提供用于判断 Assistive Technologies 是否在使用信息的程序接口。然而,本规范允许作者向 Assistive Technologies 的用户展示与非 Assistive Technologies 用户不同的信息。使用 ARIA 规范的许多特性可以做到这一点,就像在 Web 技术栈的许多其他部分也可以做到一样。这种内容差异可能会被滥用来对 Assistive Technologies 的用户进行主动指纹识别(active fingerprinting)。

A. 将 WAI-ARIA 值类型映射到语言

本节为非规范性说明。

表格中 HTML 列为建议性。有关在 HTML 中使用 WAI-ARIA 状态和属性的指导,请参见 Document conformance requirements for use of ARIA attributes in HTML(HTML-ARIA)。

建议将 true/false 值在 HTML 中映射为使用允许值为 truefalse 的 Keyword and enumerated attributes,而不是使用 HTML 布尔值类型。

下表提供了建议的映射,说明 WAI-ARIA 的状态和属性类型与来自 HTML Standard 和 W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes 的属性类型之间的对应关系。

未在下表列出的语言可能在该语言中定义了适当的值类型。如果没有,我们建议对于通用 XML 语言使用 XML Schema Datatypes。使用 DTD 而非 schema 的文档将无法自动验证,并且需要对 WAI-ARIA 属性进行额外处理。

WAI-ARIA 类型 HTML XML Schema
true/false Keyword and enumerated attributes,允许值为 "true" 和 "false" boolean
true/false/undefined Keyword and enumerated attributes,允许值为 truefalseundefined NMTOKEN,并使用枚举约束允许值 truefalseundefined
tristate Keyword and enumerated attributes,允许值为 "true"、"false" 和 "mixed" NMTOKEN,并使用枚举约束允许值 "true"、"false" 和 "mixed"
number 浮点数 decimal
integer 非负整数 integer
token Keyword and enumerated attributes NMTOKEN,并使用枚举约束允许在状态或属性定义中列出的值
token list 以空格分隔的标记 NMTOKENS,并使用枚举约束允许在状态或属性定义中列出的值
ID reference 另一个元素上已定义的 id 属性 的值 IDREF
ID reference list 一个或多个其他元素上已定义的 id 属性 的值,以 以空格分隔的标记 表示 IDREFS
string 无值约束 string

B. 更新日志

B.1 本次发布的主要特性

B.2 自 ARIA 1.2 起的重要变更

C. 致谢

本节为非规范性说明。

以下人员为本文件的制定作出了贡献。

C.1 发布时 ARIA 工作组的活跃参与者

C.2 资助单位

本出版物部分由美国联邦政府资金资助,资金来自美国教育部国家残障、独立生活与康复研究院(NIDILRR),最初合同号为 ED-OSE-10-C-0067,之后为 HHSP23301500054C,现在为 HHS75P00120P00168。本出版物内容不一定反映美国教育部的观点或政策,文件中提到的商品名、商品或机构亦不代表美国政府的认可。

D. 参考文献

D.1 规范性引用

[ACCNAME-1.2]
Accessible Name and Description Computation 1.2。Bryan Garaventa;Joanmarie Diggs;Michael Cooper。W3C。2019年7月11日。W3C 工作草案。URL: https://www.w3.org/TR/accname-1.2/
[CORE-AAM]
Core Accessibility API Mappings 1.1。 Joanmarie Diggs;Joseph Scheuhammer;Richard Schwerdtfeger;Michael Cooper;Andi Snow-Weaver;Aaron Leventhal。W3C。2017年12月14日。W3C 推荐。URL: https://www.w3.org/TR/core-aam-1.1/
[CORE-AAM-1.2]
Core Accessibility API Mappings 1.2。 Valerie Young;Alexander Surkov;Michael Cooper。W3C。2023年11月2日。W3C 候选推荐。URL: https://www.w3.org/TR/core-aam-1.2/
[CSS3-SELECTORS]
Selectors Level 3。Tantek Çelik;Elika Etemad;Daniel Glazman;Ian Hickson;Peter Linss;John Williams。W3C。2018年11月6日。W3C 推荐。URL: https://www.w3.org/TR/selectors-3/
[DOM]
DOM Standard。Anne van Kesteren。WHATWG。现行标准。URL: https://dom.spec.whatwg.org/
[DPUB-ARIA-1.0]
Digital Publishing WAI-ARIA Module 1.0。Matt Garrish;Tzviya Siegman;Markus Gylling;Shane McCarron。W3C。2017年12月14日。W3C 推荐。URL: https://www.w3.org/TR/dpub-aria-1.0/
[HTML]
HTML Standard。Anne van Kesteren; Domenic Denicola;Ian Hickson;Philip Jägenstedt;Simon Pieters。WHATWG。现行标准。URL: https://html.spec.whatwg.org/multipage/
[infra]
Infra Standard。Anne van Kesteren;Domenic Denicola。WHATWG。现行标准。URL: https://infra.spec.whatwg.org/
[MathML3]
Mathematical Markup Language (MathML) Version 3.0 2nd Edition。David Carlisle;Patrick D F Ion;Robert R Miner。W3C。2014年4月10日。W3C 推荐。URL: https://www.w3.org/TR/MathML3/
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels。S. Bradner。IETF。1997年3月。最佳实践。URL: https://www.rfc-editor.org/rfc/rfc2119
[ROLE-ATTRIBUTE]
Role Attribute 1.0。Shane McCarron 等。W3C。2013年3月28日。W3C 推荐。URL: https://www.w3.org/TR/role-attribute/
[SVG2]
Scalable Vector Graphics (SVG) 2。Amelia Bellamy-Royds;Bogdan Brinza;Chris Lilley;Dirk Schulze;David Storey;Eric Willigers。W3C。2018年10月4日。W3C 候选推荐。URL: https://www.w3.org/TR/SVG2/
[uievents-key]
UI Events KeyboardEvent key Values。 Travis Leithead;Gary Kacmarcik。W3C。2023年5月30日。W3C 候选推荐。URL: https://www.w3.org/TR/uievents-key/
[WEBIDL]
Web IDL Standard。Edgar Chen;Timothy Gu。 WHATWG。现行标准。URL: https://webidl.spec.whatwg.org/
[XML-NAMES]
Namespaces in XML 1.0 (Third Edition)。 Tim Bray;Dave Hollander;Andrew Layman;Richard Tobin;Henry Thompson 等。W3C。2009年12月8日。W3C 推荐。URL: https://www.w3.org/TR/xml-names/

D.2 参考性引用

[AT-SPI]
Assistive Technology Service Provider Interface。GNOME 项目。URL: https://developer-old.gnome.org/libatspi/stable/
[ATK]
ATK - Accessibility Toolkit。GNOME 项目。URL: https://developer.gnome.org/atk/stable/
[AXAPI]
The NSAccessibility Protocol for macOS。Apple, Inc. URL: https://developer.apple.com/documentation/appkit/nsaccessibility
[design-principles]
Web Platform Design Principles。 Sangwhan Moon。W3C。2023年9月7日。W3C 工作组注释。URL: https://www.w3.org/TR/design-principles/
[fingerprinting-guidance]
Mitigating Browser Fingerprinting in Web Specifications。Nick Doty。W3C。2019年3月28日。W3C 工作组注释。URL: https://www.w3.org/TR/fingerprinting-guidance/
[HTML-ARIA]
ARIA in HTML。Scott O'Hara;Patrick Lauke。W3C。2023年12月21日。W3C 推荐。URL: https://www.w3.org/TR/html-aria/
[IAccessible2]
IAccessible2。 Linux Foundation。URL: https://wiki.linuxfoundation.org/accessibility/iaccessible2/
[MSAA]
Microsoft Active Accessibility (MSAA)。Microsoft Corporation。URL: https://docs.microsoft.com/en-us/windows/win32/winauto/microsoft-active-accessibility
[UI-AUTOMATION]
UI Automation。Microsoft Corporation。URL: https://docs.microsoft.com/en-us/windows/win32/winauto/ui-automation-specification
[UIA-EXPRESS]
The IAccessibleEx Interface。Microsoft Corporation。URL: https://docs.microsoft.com/en-us/windows/win32/winauto/iaccessibleex
[wai-aria-1.1]
Accessible Rich Internet Applications (WAI-ARIA) 1.1。Joanmarie Diggs;Shane McCarron;Michael Cooper;Richard Schwerdtfeger; James Craig。W3C。2017年12月14日。W3C 推荐。URL: https://www.w3.org/TR/wai-aria-1.1/
[WAI-ARIA-PRACTICES-1.2]
WAI-ARIA Authoring Practices 1.2。Matthew King;JaEun Jemma Ku;James Nurthen;Zoë Bijl;Michael Cooper。W3C。 2022年5月19日。W3C 工作组注释。URL: https://www.w3.org/TR/wai-aria-practices-1.2/
[WCAG21]
Web Content Accessibility Guidelines (WCAG) 2.1。Michael Cooper;Andrew Kirkpatrick;Joshue O'Connor;Alastair Campbell。W3C。 2023年9月21日。W3C 推荐。URL: https://www.w3.org/TR/WCAG21/
[XMLSCHEMA11-2]
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes。David Peterson;Sandy Gao;Ashok Malhotra;Michael Sperberg-McQueen;Henry Thompson;Paul V. Biron 等。W3C。2012年4月5日。W3C 推荐。URL: https://www.w3.org/TR/xmlschema11-2/