HTML 中的 ARIA

W3C 推荐标准

有关本文档的更多详细信息
此版本:
https://www.w3.org/TR/2026/REC-html-aria-20260811/
最新发布版本:
https://www.w3.org/TR/html-aria/
最新编辑草案:
https://w3c.github.io/html-aria/
历史记录:
https://www.w3.org/standards/history/html-aria/
提交历史记录
实现报告:
https://w3c.github.io/html-aria/results/implementation-results.html
编辑:
Scott O'HaraMicrosoft
Patrick H. LaukeTetraLogical
前任编辑:
Steve FaulknerTPGi)- 任职至
反馈:
GitHub w3c/html-aria拉取请求新建议题未解决的议题
public-aria@w3.org 主题行应为 [html-aria] ……消息主题……存档
勘误:
存在勘误

另见 翻译.


摘要

本规范定义了在[HTML]元素上使用 无障碍富互联网应用(WAI-ARIA)1.2数字出版 WAI-ARIA 模块 1.1 属性的编写规则(作者一致性要求)。 本规范的主要目标是为作者(即网页开发者)使用的一致性检查工具的使用定义要求。这些要求将帮助作者开发网络内容,包括定制接口和组件, 利用 ARIA 来补充或扩展宿主语言 [HTML] 的功能。

本文档的状态

本节介绍本文档在发布时的 状态。当前 W3C 出版物的列表以及本技术报告的最新修订版可在 W3C 标准与草案 索引中找到。

HTML 中的 ARIA 是 [HTML] 规范模块。本规范 模块引用但未明确定义的任何 HTML 特性、一致性 要求或术语,均由 HTML 标准定义。

自本规范于 2021 年 12 月 09 日成为 W3C 推荐标准以来, 已进行了以下实质性更改:

有关本规范所做更改(包括信息性和编辑性更新)的完整列表,请参阅 GitHub 上所有已关闭的拉取 请求

本文档由无障碍富互联网 应用工作组使用 推荐标准 流程发布为推荐标准。

W3C 建议广泛部署本规范,作为 Web 的标准。

W3C 推荐标准是经过广泛 共识建立后,由 W3C 及其成员认可,并且 工作组成员承诺为实现提供 免版税许可 的规范。 对本推荐标准的未来更新可能会纳入 新特性

本文档由一个依据 W3C 专利 政策运作的工作组编制。 W3C 维护一份 与该工作组交付成果相关的所有专利披露的公开列表; 该页面还包含 披露专利的说明。实际 知晓某项专利,并认为该专利包含 必要权利要求 的个人,必须依照 W3C 专利政策第 6 节披露相关信息。

本文档受 2025 年 8 月 18 日 W3C 流程文档管辖。

1. 在 HTML 中使用 ARIA 的作者要求

作者可以使用 ARIA rolearia-* 属性来 更改 HTML 元素所公开的含义(语义),但须遵循 WAI-ARIA 定义的要求,但 ARIA 特性与给定 HTML 元素的 强原生语义 冲突或等同于其 隐式 ARIA 语义 的情况除外。HTML 特性的隐式 ARIA 语义HTML 无障碍 API 映射 规范定义。

本规范中定义的 ARIA 功能在 HTML 中的使用约束,旨在防止作者导致辅助技术产品报告出与实际 UI 不符的无意义用户界面信息。

作者 不得以与 4. 在 HTML 中使用 ARIA 属性的文档符合性要求4.2 用 ARIA 属性替代等效 HTML 属性的要求 表格中描述的语义冲突的方式使用 ARIA rolearia-* 属性。 不建议作者将 ARIA rolearia-* 属性设置为与任一表格中 隐式 ARIA 语义匹配的值。 这样做没有必要,并且可能导致意外后果。

2. ARIA 语义的扩展与区别于 HTML 之处

本节为非规范内容。

通过使用 ARIA,作者可以指定超出原生 HTML 当前能力范围的语义。这非常有用,因为它为作者提供了创建小部件的机会,或者为原生 HTML 特性暴露特定可访问状态和属性, 这些仅使用 HTML 是无法实现的。

例如,button 元素没有原生 HTML 特性用于暴露“按下”状态。ARIA 允许作者通过指定 aria-pressed 属性来扩展该元素的语义, 使听觉用户界面可以与控件的视觉呈现保持一致。

在以下示例中,button 元素允许用户在网页应用中切换某个设置的状态。aria-pressed 属性用于增强 button 元素。 处于“按下”状态时,该信息可被辅助技术用户感知。

示例 1:通过 ARIA 传达按钮的按下状态
<button aria-pressed=true>...</button>

也存在某些情况下,某些 aria-* 属性允许在具有特定 role 的元素上使用, 而等效的原生属性在 HTML 本身中目前并不合法。

例如,HTML 没有禁用超链接(a href 元素)的直接概念。诸如 <a href="..." disabled> ... </a> 的写法是无效的, 并且不会被辅助技术识别。

ARIA 在这方面与 HTML 不同,允许在具有显式 role=link 的元素上指定 aria-disabled 属性。 如果作者在 HTML 超链接上指定 aria-disabled=true,用户代理不会在功能上做出不同处理(超链接仍可点击/操作), 但它会向辅助技术暴露为处于禁用状态。

同样,原生 HTML option 元素作为 select 的后代只能设置为 selected, 而具有显式 option 角色的元素不仅可以使用等效的 aria-selected,也可以使用 aria-checked 属性, 支持超越原生 select 元素能力的小部件/结构。

不幸的是,在 ARIA 和 HTML 功能相近但允许方式不同的场景下,可能导致支持和用户体验的不一致。 在 ARIA 允许而 HTML 不支持的情况下,通常建议作者实现完全定制的 ARIA 小部件,对作者和用户更有利。

在下面的示例中,一个超链接需要以禁用状态进行传达。HTML 不允许在超链接上使用 disabled 属性, 使用 aria-disabled=true 虽可向辅助技术传达禁用状态,但实际上并不会禁用该元素。 最有效的做法是移除 href 属性,使 a 元素成为占位符, 然后通过 ARIA 为该占位链接传达其预期角色和状态。

3. 作者避免错误使用 ARIA 的指导

本节为非规范内容。

3.1 避免用非交互角色覆盖交互元素

ARIA 用于修正或调整元素的角色,当需要向用户暴露不同角色时很有用。但通常作者或用户不宜使用 ARIA 将交互元素(如 button)覆盖为通常由非交互元素暴露的角色。例如标题元素。

如下例,在 button 元素上使用 role=heading。 这是不允许的,因为 button 元素具有默认功能,与标题角色的用户预期冲突。

示例 3:错误角色
<button role="heading">search</button>

作者需要采取额外措施确保移除 button 的默认功能和表现,即使这样也可能无法完全抑制该元素的隐式特性, 具体取决于用户如何与网页交互。例如启用 Windows 高对比度模式,或在浏览器阅读模式下查看网页。

3.2 避免指定冗余角色

下例展示了 button 元素被显式赋予 role=button。 其实无需指定该角色,因为“button”元素本身已经隐式暴露为 button 角色。 实践中,这种冗余通常不会导致意外副作用,除了让标记变得冗长,并错误引导其他作者认为这种做法有用。 请参考 3.3 谨慎处理副作用 章节,了解指定不必要角色可能引发的问题。

示例 4:button 上的冗余角色
<!-- 避免这样做! -->
<button role="button">...</button>

类似地,以下代码在 fieldset 元素上使用 role=group,并在 main 元素上使用 role=main。 这是不必要的,因为 fieldset 元素会隐式公开为 role=group,而 main 元素同样会 隐式公开为 role=main

示例 5:fieldset 和 main 上的冗余角色
<!-- 避免这样做! -->
<fieldset role="group">...</fieldset>
<!-- 同样,也要避免这样做! -->
<main role="main">...</main>

下例在 ul 元素上使用了 role=list。 由于 ul 元素隐式有 list 角色,显式添加该角色一般会被认为是冗余的。 不过,如果视觉呈现去除了列表项的标记,一些用户代理会抑制列表的隐式 ARIA 语义。在此类特定情形下, 若确需暴露该角色,作者可以显式添加。

示例 6:列表上的冗余角色
<!-- 一般避免这样做! -->
<ul role="list">...</ul>

3.3 谨慎处理副作用

下例在 summary 元素上使用了 role=button。 这是不必要的,并可能导致跨平台问题。例如,阻止元素正确暴露其状态,并强制采用 button 角色, 而原本可由平台或浏览器暴露为特定角色。

示例 7:非预期后果
<details>
  <!-- 避免这样做! -->
  <summary role="button">more information</summary>
  ...
</details>

3.4 遵循 ARIA 规则

可访问富互联网应用(WAI-ARIA)1.2 定义了许多不应由作者使用的角色。 这些角色多数归为 抽象角色,明确规定不应由作者使用。 下例演示了抽象 select 角色的无效用法,作者本意可能是想用 combobox 角色。

示例 8:抽象角色不适合作者使用
<!-- 不要这样做! -->
<div role="select" ...>...</div>

ARIA 还定义了 generic 角色, 用以实现与部分没有更具体 ARIA 语义的 HTML 元素功能对齐。例如 HTML 的 divspan 等元素。ARIA 不建议作者使用 generic 角色,其设计初衷是供用户代理实现者使用。

下例中,作者应使用 div 替换 article 元素,而不是使用 generic 角色。 如果无法更改 HTML 元素,可以指定 presentationnone 角色, 以移除 article 元素的隐式角色。

示例 9:不要将元素指定为 generic
<!-- 避免这样做! -->
<article role="generic" ...>...</article>

此外,ARIA 在 与宿主语言语义冲突中明确说明, 如果作者同时使用原生 HTML 特性和 ARIA 属性暴露状态和属性,则宿主语言特性优先于同时使用的显式 ARIA 属性。

例如,下例作者使用了 HTML 的 input type=checkbox,并指定了 aria-checked=true。 但用户代理应忽略 aria-checked 属性,而是根据表单控件的原生特性暴露状态。

示例 10:隐式 checked 状态优先于显式 ARIA 属性
<!-- 不要这样做! -->
<input type="checkbox" checked aria-checked="false">

3.5 遵循 HTML 规则

虽然 ARIA 可用于改变 HTML 特性对辅助技术用户的暴露方式,但这些修改不会改变 HTML 的底层解析和允许内容模型。 例如, div 元素允许作者指定任意 role,但这并不意味着可将其用在超出 HTML 对该元素定义的规则范围之外。

例如,下例作者在 div 元素上指定了 link 角色。 虽然 HTML 允许超链接(暴露为 role=link)成为 p 元素的后代,但 HTML 解析器不允许 div 成为 p 的后代。

示例 11:ARIA 语义与无效 HTML 嵌套
<!-- 不要这样做! -->
<p>
  ... <div role=link tabindex=0>...</div> ... 
</p>

HTML 解析器会将上述标记输出为如下结构:

示例 12:不理想渲染标记与有效替代方案
<!-- 上例的标记实际渲染如下 -->
<p>...</p>
<div role=link tabindex=0>...</div> 
... 
<p></p>

<!-- 替换 div 为 span。span 可作为 p 元素的后代! -->
<p>
  ... <span role=link tabindex=0>...</span> ...
</p>

虽然本规范指出每个 HTML 元素可指定的 ARIA 属性, 但该示例说明即使角色允许,实际使用的上下文依然可能导致渲染和可访问性问题。

4. 在 HTML 中使用 ARIA 属性的文档符合性要求

下表为在 HTML 文档中使用 ARIA 标记提供了逐元素的规范性文档一致性要求。 此外,还指出了适用于HTML 元素隐式 ARIA 语义。 这些元素的隐式 ARIA 语义HTML AAM 中定义。

第一列单元格中的每个语言特性(元素)均隐含同一行第二列单元格中给出的 ARIA 语义 (角色、状态和特性)。 每行的第三个单元格定义作者可以在该元素上指定的 ARIA role 值和 aria-* 属性。 如果第三列的单元格中包含术语 任何 role, 则表示可以在该元素上使用任何 role 值。不过,不建议作者在这些元素上指定 元素的隐式角色、generic 角色或 已被 ARIA 弃用的角色。 如果第三列的单元格中包含术语 role,则表示 作者不得覆盖 HTML 元素的隐式 ARIA 语义或原生语义。

WAI-ARIA 标识了具有 禁用状态和特性的角色。 这些角色不允许作者指定某些 WAI-ARIA 属性。 公开这些隐式 WAI-ARIA 角色的 HTML 元素也禁止作者 指定这些 WAI-ARIA 属性。

被标识为禁止命名的元素,是指作者不得为其指定 aria-labelaria-labelledby 属性的元素,除非该元素允许使用 允许作者命名的显式 WAI-ARIA 角色覆盖其隐式角色。有关更多信息,请参阅4.1 使用 ARIA 属性为元素命名的要求

尽管不建议设置与 隐式 ARIA 语义相匹配的 ARIA role 和/或 aria-* 属性, 但在某些情况下,显式设置这些属性可能 会有所帮助——例如,对于不公开某些元素的隐式 ARIA 语义的用户代理。

尽管使用下表所述的数字出版 WAI-ARIA 模块 1.1 role 值是符合规范的,但这些角色 并非旨在用于网站实现。如果将这些角色用于数字出版 行业范围之外的用途,则需要进一步进行手动测试,以确保向 用户提供预期的体验。

按 HTML 元素使用 ARIA 属性的规则
HTML 元素

隐式 ARIA 语义 (在标记中显式指定这些 不推荐

允许的 ARIA 角色、状态和属性
a 带有 href role=link

角色: buttoncheckboxmenuitemmenuitemcheckboxmenuitemradiooptionradioswitchtabtreeitem。 (也允许 link,但不推荐。)

DPub 角色: doc-backlinkdoc-bibliorefdoc-glossrefdoc-noteref

全局 aria-* 属性以及 适用于所允许角色的任何 aria-* 属性。

不推荐在带有 href 属性的 a 元素上使用 aria-disabled="true"

如果需要以编程方式将链接传达为“已禁用”, 请移除 href 属性
a 不带 href role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

abbr 无对应角色

任何 role

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于 所允许角色的任何 aria-* 属性。

address role=group

任何 role,但不推荐使用 group

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

area 带有 href role=link

link不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 link 角色的任何 aria-* 属性。

area 不带 href role=generic

角色: buttonlink。 (也允许 generic,但不应使用。)

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

article role=article

角色: applicationdocumentfeedmainnonepresentationregion。 (也允许 article,但不推荐。)

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

aside role=complementary

角色: feednonenotepresentationregionsearch。 (也允许 complementary,但不推荐。)

DPub 角色: doc-dedicationdoc-exampledoc-footnotedoc-glossarydoc-pullquotedoc-tip

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

audio 无对应角色

角色: application

全局 aria-* 属性 以及适用于 application 角色的任何 aria-* 属性。

自主 自定义元素

从作者定义的 ElementInternals 暴露的角色

否则为 role=generic

如果角色由 ElementInternals 定义, 不得指定 role

否则,可以使用任何 role,但 不应使用 generic

如果暴露为 generic 角色,或者暴露为另一个禁止命名的角色,则 禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

b role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

base 无对应角色

不得使用 rolearia-* 属性

bdi role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

bdo role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

blockquote role=blockquote

任何 role,但 blockquote 不推荐使用。

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

body role=generic

generic不得使用其他 role,并且该角色不应使用。

禁止命名

否则,可以使用全局 aria-* 属性 中允许用于 generic 角色的属性,但作者不得body 元素上指定 aria-hidden=true

br 无对应角色

角色: nonepresentation

作者可以br 元素上指定 aria-hidden 属性。 除此之外,不允许使用其他 aria-* 属性。

button

role=button

如果 buttonselect 元素的第一个子元素,则该元素 为 inert

角色: checkboxcomboboxgridcelllinkmenuitemmenuitemcheckboxmenuitemradiooptionradioseparatorsliderswitchtab、 或 treeitem。 (也允许 button,但不推荐。)

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。


如果 buttonselect 元素的第一个子元素: 不得使用 rolearia-* 属性

canvas 无对应角色

任何 role

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

caption role=caption

caption不得使用其他 role,并且该角色不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性

cite 无对应角色

任何 role

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

code role=code

任何 role,但 code 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

col 无对应角色

不得使用 rolearia-* 属性

colgroup 无对应角色

不得使用 rolearia-* 属性

data role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

datalist role=listbox

listbox不得使用其他 role,并且该角色不推荐使用。

不得使用 aria-* 属性

dd 无对应角色

不得指定 role

全局 aria-* 属性 以及适用于 definition 角色的任何 aria-* 属性。

del role=deletion

任何 role,但 deletion 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

details role=group

group不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 group 角色的任何 aria-* 属性。

dfn role=term

任何 role,但 term 不推荐使用。

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

dialog role=dialog

角色: alertdialog。 (也允许 dialog,但不推荐。)

全局 aria-* 属性 以及适用于 dialog 角色的任何 aria-* 属性。

div role=generic

如果是 dl 元素的直接子元素, 则只能使用 presentationnone。否则,可以使用 任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

dl 无对应角色

角色: grouplistnonepresentation

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

dt 无对应角色

角色: listitem

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

em role=emphasis

任何 role,但 emphasis 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

embed 无对应角色

角色: applicationdocumentimgimagenonepresentation

全局 aria-* 属性以及 适用于所允许角色的任何 aria-* 属性。

fieldset role=group

角色: nonepresentationradiogroup。 (也允许 group,但不推荐。)

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

figcaption 无对应角色

角色: groupnonepresentation

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

figure role=figure

如果 figure 有有效的 figcaption 后代:
figure不得使用其他 role, 并且该角色不推荐使用。

DPub 角色: doc-example

否则,如果 figure 没有 figcaption 后代:
可以使用任何 role,但 figure 不推荐使用。

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

footer

如果不是 articleasidemainnavsection 元素的后代,也不是具有 role=articlecomplementarymainnavigationregion 的元素的后代, 则为 role=contentinfo

否则为 role=generic

角色: grouppresentationnone。 (如果不是 articleasidemainnavsection 元素的后代,也不是具有 role=articlecomplementarymainnavigationregion 的元素的后代, 则也允许 role=contentinfo, 但不推荐。 否则,也允许 role=generic, 但不应使用。)

DPub 角色: doc-footnote

如果暴露为 generic,则禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

form

role=form

角色: nonepresentationsearch。 (也允许 form,但不推荐。)

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

除非为 form 提供 可访问名称, 否则它不会作为地标区域暴露。

表单关联 自定义元素

从作者定义的 ElementInternals 暴露的角色

否则为 role=generic

如果角色由 ElementInternals 定义, 不得指定 role

否则,可使用与表单相关的角色: buttoncheckboxcomboboxlistboxprogressbargroupradioradiogroupsearchboxsliderspinbuttonswitchtextbox。 (也允许 generic,但不应使用。)

如果暴露为 generic 角色,则禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

h1 至 h6 role=headingaria-level = 元素标签名称中的数字

角色: nonepresentationtab。 (也允许 heading,但不推荐。)

DPub 角色: doc-subtitle

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

head 无对应角色

不得使用 rolearia-* 属性

header

如果不是 articleasidemainnavsection 元素的后代,也不是具有 role=articlecomplementarymainnavigationregion 的元素的后代,则 role=banner

否则为 role=generic

角色: groupnonepresentation。 (如果不是 articleasidemainnavsection 元素的后代,也不是具有 role=articlecomplementarymainnavigationregion 的元素的后代, 则也允许 role=banner, 但不推荐。 否则,也允许 role=generic, 但不应使用。)

如果暴露为 generic,则禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

hgroup role=group

任何 role,但不推荐使用 group

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

hr role=separator

角色: nonepresentation。 (也允许 separator,但不推荐。)

DPub 角色: doc-pagebreak

全局 aria-* 属性 以及适用于 separator 角色的任何 aria-* 属性。

html role=generic

documentgeneric不得使用其他 role,并且这些角色不推荐使用。

不得使用 aria-* 属性

i role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

iframe 无对应角色

角色: applicationdocumentimgimagenonepresentation

全局 aria-* 属性以及 适用于所允许角色的任何 aria-* 属性。

img 如果 img 具有非空的 altalt="some text"),或者由其他 img 命名方法提供了可访问名称, 或者 img 没有 alt 且没有可访问名称:
role=img 或 image

角色: buttoncheckboxlinkmathmenuitemmenuitemcheckboxmenuitemradiometeroptionprogressbarradioscrollbarseparatorsliderswitchtabtreeitem。 (也允许 img 或 image,但不推荐。)

DPub 角色: doc-cover

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

如果 img 没有 alt 属性或没有可访问名称: 除 role=nonepresentation 角色外, 不得使用其他 role。 (也允许 role=img 或 image,但不推荐。)

img 具有空的 alt 且没有可访问名称

如果 img 具有空的 altalt="") 并且没有任何其他 img 命名方法
role=nonerole=presentation

role=nonepresentation 角色外 不得使用其他 role,并且这些角色不推荐使用。

aria-hidden="true" 外,不得使用 aria-* 属性

input type=button role=button

角色: checkboxcomboboxgridcelllinkmenuitemmenuitemcheckboxmenuitemradiooptionradioseparatorsliderswitchtab、 或 treeitem。 (也允许 button,但不推荐。)

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

input type=checkbox role=checkbox

角色: menuitemcheckboxoptionswitch如果与 aria-pressed 一起使用,则可以为 button。 (也允许 checkbox,但不推荐。)

作者不得input type=checkbox 元素上使用 aria-checked 属性

否则,可以使用任何全局 aria-* 属性以及 适用于所允许角色的任何 aria-* 属性。

menuitemcheckboxoptionswitch 角色用于 type=checkbox 时,可以使用 HTML checked 属性代替 aria-checked 属性。

input type=color 无对应角色

不得指定 role

全局 aria-* 属性以及 aria-disabled 属性。

input type=date 无对应角色

不得指定 role

全局 aria-* 属性 以及适用于 textbox 角色的任何 aria-* 属性。

input type=datetime-local 无对应角色

不得指定 role

全局 aria-* 属性 以及适用于 textbox 角色的任何 aria-* 属性。

input type=email 且没有 list 属性 role=textbox

textbox不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 textbox 角色的任何 aria-* 属性。

input type=file 无对应角色

不得指定 role

全局 aria-* 属性aria-disabledaria-invalidaria-required 属性。

input type=hidden 无对应角色

不得使用 rolearia-* 属性

input type=image role=button

允许以下角色,但不推荐buttoncheckboxgridcelllinkmenuitemmenuitemcheckboxmenuitemradiooptionradioseparatorsliderswitchtabtreeitem

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

如果可能,作者应当考虑使用允许指定角色的其他 HTML 元素, 例如 button 元素。

input type=month 无对应角色

不得指定 role

全局 aria-* 属性 以及适用于 textbox 角色的任何 aria-* 属性。

input type=number role=spinbutton

spinbutton不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 spinbutton 角色的任何 aria-* 属性。

input type=password 无对应角色

不得指定 role

全局 aria-* 属性 以及适用于 textbox 角色的任何 aria-* 属性。

input type=radio role=radio

角色: menuitemradio。 (也允许 radio,但不推荐。)

作者不得input type=radio 元素上使用 aria-checked 属性

否则,可以使用任何全局 aria-* 属性以及适用于所允许角色的任何 aria-* 属性。

menuitemradio 角色用于 type=radio 时, 可以使用 HTML checked 属性代替 aria-checked 属性。

input type=range role=slider

slider不得使用其他 role,并且该角色不推荐使用。

作者不应input type=range 上使用 aria-valuemaxaria-valuemin 属性。

否则,可以使用任何 全局 aria-* 属性 以及适用于 slider 角色的任何其他 aria-* 属性。

input type=reset role=button

允许以下角色,但不推荐buttoncheckboxcomboboxgridcelllinkmenuitemmenuitemcheckboxmenuitemradiooptionradioseparatorsliderswitchtabtreeitem

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

如果可能,作者应当考虑使用允许指定角色的其他 HTML 元素, 例如 button 元素。

input type=search, 且没有 list 属性 role=searchbox

searchbox不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 searchbox 角色的任何 aria-* 属性。

input type=submit role=button

允许以下角色,但不推荐buttoncheckboxcomboboxgridcelllinkmenuitemmenuitemcheckboxmenuitemradiooptionradioseparatorsliderswitchtabtreeitem

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

如果可能,作者应当考虑使用允许指定角色的其他 HTML 元素, 例如 button 元素。

input type=tel, 且没有 list 属性 role=textbox

textbox不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 textbox 角色的任何 aria-* 属性。

input type=text 或具有缺失或无效的 type,且没有 list 属性 role=textbox

角色: comboboxsearchboxspinbutton。 (也允许 textbox,但不推荐。)

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

input type=textsearchtelurlemail, 或具有缺失或无效的 type并带有 list 属性 role=combobox

combobox不得使用其他 role,并且该角色不推荐使用。

作者不应在上述带有 list 属性的 input 上使用 aria-haspopup 属性。

否则,可以使用任何 全局 aria-* 属性 以及适用于 combobox 角色的任何其他 aria-* 属性。

input type=time 无对应角色

不得指定 role

全局 aria-* 属性 以及适用于 textbox 角色的任何 aria-* 属性。

input type=url 且没有 list 属性 role=textbox

textbox不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 textbox 角色的任何 aria-* 属性。

input type=week 无对应角色

不得指定 role

全局 aria-* 属性 以及适用于 textbox 角色的任何 aria-* 属性。

ins role=insertion

任何 role,但 insertion 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

kbd 无对应角色

任何 role

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

label 无对应角色

如果 label 元素以隐式或显式方式与 可标记 元素关联,则 不得指定 role

否则,如果 label 未与元素关联,则可以使用任何 role, 但不应使用 generic

如果暴露为 generic 角色,或者暴露为另一个禁止命名的角色,则 禁止命名

否则,可以使用全局 aria-* 属性

legend 无对应角色

不得指定 role

禁止命名

否则,可以使用全局 aria-* 属性

li

如果 li 是暴露为 role=list 的元素的子元素 (例如 ulolmenu): role=listitem

否则, role=generic

如果父列表元素具有隐式或显式的 list 角色, 除 listitem 外, 不得使用其他 role, 并且该角色不推荐使用。

否则,如果父列表元素未暴露隐式或显式的 list 角色,则可以使用 任何 role

有关列表元素允许的角色,请参阅 ulolmenu

全局aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

作者不应使用以下已弃用的 DPub 角色: doc-biblioentrydoc-endnote

link 无对应角色

不得使用 rolearia-* 属性

main role=main

main不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 main 角色的任何 aria-* 属性。

map 无对应角色

不得使用 rolearia-* 属性

mark 无对应角色

任何 role

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

math role=math

math不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 math 角色的任何 aria-* 属性。

menu role=list

角色: grouplistboxmenumenubarnonepresentationradiogrouptablisttoolbartree。 (也允许 list,但不推荐。)

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

作者不应使用已弃用的 directory 角色。

meta 无对应角色

不得使用 rolearia-* 属性

meter role=meter

meter不得使用其他 role,并且该角色不推荐使用。

作者不应meter 元素上使用 aria-valuemaxaria-valuemin 属性。

否则,可以使用任何 全局 aria-* 属性 以及适用于 meter 角色的任何其他 aria-* 属性。

nav role=navigation

角色: menumenubarnonepresentationtablist。 (也允许 navigation,但不推荐。)

DPub 角色: doc-indexdoc-pagelistdoc-toc

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

noscript 无对应角色

不得使用 rolearia-* 属性

object 无对应角色

角色: applicationdocumentimgimage

全局 aria-* 属性以及 适用于所允许角色的任何 aria-* 属性。

ol role=list

角色: grouplistboxmenumenubarnonepresentationradiogrouptablisttoolbartree。 (也允许 list,但不推荐。)

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

作者不应使用已弃用的 directory 角色。

optgroup role=group

group不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 group 角色的任何 aria-* 属性。

option 元素位于选项 列表中,或者 表示 datalist 中的建议 role=option

option不得使用其他 role,并且该角色不推荐使用。

作者不应option 元素上使用 aria-selected 属性。

全局 aria-* 属性以及 适用于 option 角色的任何其他 aria-* 属性。

output role=status

任何 role,但 status 不推荐使用。

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

p role=paragraph

任何 role,但 paragraph 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

param 无对应角色

不得使用 rolearia-* 属性

picture 无对应角色

不得指定 role

作者可以picture 元素上指定 aria-hidden 属性。 除此之外,不允许使用其他 aria-* 属性。

pre role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

progress role=progressbar

progressbar不得使用其他 role,并且该角色不推荐使用。

作者不应progress 元素上使用 aria-valuemax 属性。

否则, 可以使用任何全局 aria-* 属性 以及适用于 progressbar 角色的任何其他 aria-* 属性。

q role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

rp 无对应角色

任何 role

禁止命名

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

rt 无对应角色

任何 role

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

ruby 无对应角色

任何 role

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

s role=deletion

任何 role,但 deletion 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

samp role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

script 无对应角色

不得使用 rolearia-* 属性

search

role=search

角色: formgroupnonepresentationregion。 (也允许 search,但不推荐。)

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

section

如果 section 元素具有 可访问名称, 则 role=region

否则为 role=generic

角色: alertalertdialogapplicationbannercomplementarycontentinfodialogdocumentfeedgrouplogmainmarqueenavigationnonenotepresentationsearchstatustabpanel。 (也允许 role=region, 但不推荐不应使用 role=generic。)

DPub 角色: doc-abstractdoc-acknowledgmentsdoc-afterworddoc-appendixdoc-bibliographydoc-chapterdoc-colophondoc-conclusiondoc-creditdoc-creditsdoc-dedicationdoc-endnotesdoc-epigraphdoc-epiloguedoc-erratadoc-exampledoc-foreworddoc-glossarydoc-indexdoc-introductiondoc-noticedoc-pagelistdoc-partdoc-prefacedoc-prologuedoc-pullquotedoc-qnadoc-toc

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

select (呈现为下拉 框 role=combobox

角色:menu。 (也允许 combobox,但不推荐。)

作者不应select 元素上使用 aria-multiselectable 属性。

否则, 可以使用任何全局 aria-* 属性 以及适用于 comboboxmenu 角色的任何其他 aria-* 属性。

select (呈现为列表 框 role=listbox

listbox不得使用其他 role,并且该角色不推荐使用。

作者不应select 元素上使用 aria-multiselectable 属性。

否则, 可以使用任何全局 aria-* 属性 以及适用于 listbox 角色的任何其他 aria-* 属性。

selectedcontent role=generic

如果作为 select 元素的有效后代使用:不得使用 rolearia-* 属性

否则,如果该元素在其预期上下文之外使用,而不是作为可自定义 select 元素的 button 部分的子元素,则可以使用 任何 role, 但 generic 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

slot 无对应角色

不得使用 rolearia-* 属性

small role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

source 无对应角色

不得使用 rolearia-* 属性

span role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

strong role=strong

任何 role,但 strong 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

style 无对应角色

不得使用 rolearia-* 属性

sub role=subscript

任何 role,但 subscript 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

summary

无对应角色

summary 元素所暴露的角色可能因用户代理 和辅助技术而异。

如果 summary 元素是其父 details 元素的 summary, 则不得指定 role

全局 aria-* 属性aria-disabledaria-haspopup 属性。

否则,如果 summary 元素不是其父 details 元素的 summary, 作者可以指定任何 role,以及任何 全局 aria-* 属性 和适用于所允许角色的任何 aria-* 属性。

sup role=superscript

任何 role,但 superscript 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

SVG 根据 SVG AAM 的定义,role=graphics-document

任何 role,但 graphics-document 不推荐使用。

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

table role=table

任何 role,但 table 不推荐使用。

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

tbody role=rowgroup

任何 role,但 rowgroup 不推荐使用。

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

td

如果祖先 table 元素暴露为 role=table, 则 role=cell

如果祖先 table 元素暴露为 role=gridtreegrid, 则 role=gridcell

如果祖先 table 元素未暴露为 role=tablegridtreegrid, 则无对应角色

如果祖先 table 元素具有 role=tablegridtreegrid, 则除以下角色外 不得使用其他 role

  • 如果祖先 table 元素暴露为 role=table,则允许 cell, 但不推荐
  • 如果祖先 table 元素暴露为 role=gridtreegrid,则允许 gridcell, 但不推荐

否则,如果祖先 table 元素未暴露为 role=tablegridtreegrid, 则可以使用任何 role

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

template 无对应角色

不得使用 rolearia-* 属性

textarea role=textbox

textbox不得使用其他 role,并且该角色不推荐使用。

全局 aria-* 属性 以及适用于 textbox 角色的任何 aria-* 属性。

tfoot role=rowgroup

任何 role,但 rowgroup 不推荐使用。

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

th

如果祖先 table 元素暴露为 role=table, 则为 role=columnheaderrowheadercell

如果祖先 table 元素暴露为 role=gridtreegrid, 则为 role=columnheaderrowheadergridcell

如果祖先 table 元素未暴露为 role=tablegridtreegrid, 则无对应角色

如果祖先 table 元素具有 role=tablegridtreegrid, 则除以下角色外 不得使用其他 role

否则,如果祖先 table 元素未暴露为 role=tablegridtreegrid, 则可以使用任何 role

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

thead role=rowgroup

任何 role,但 rowgroup 不推荐使用。

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

time role=time

任何 role,但 time 不推荐使用。

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

title 无对应角色

不得使用 rolearia-* 属性

tr role=row

如果祖先 table 元素具有 role=tablegridtreegrid, 则除 row不得使用其他 role,并且该角色不推荐; 否则可以使用 任何 role,但 row 不推荐使用。

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

track 无对应角色

不得使用 rolearia-* 属性

u role=generic

任何 role,但 不应使用 generic

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

ul role=list

角色: grouplistboxmenumenubarnonepresentationradiogrouptablisttoolbartree。 (也允许 list,但不推荐。)

全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

作者不应使用已弃用的 directory 角色。

var 无对应角色

任何 role

禁止命名

否则,可以使用全局 aria-* 属性 以及适用于所允许角色的任何 aria-* 属性。

video 无对应角色

角色:application

全局 aria-* 属性 以及适用于 application 角色的任何 aria-* 属性。

wbr 无对应角色

角色: nonepresentation

作者可以wbr 元素上指定 aria-hidden 属性。 除此之外,不允许使用其他 aria-* 属性。

在表格第二列中标有 无对应角色的元素没有任何隐式 ARIA 语义,但它们确实 具有含义, 而且这种含义可以通过 ARIA 未提供的角色、状态和属性来表示, 并通过可访问性 API 暴露给辅助技术用户。 因此,建议作者向语义上中性的元素添加 role 属性,例如 divspan, 而不是覆盖 所列元素的语义。

建议作者参考以下文档,以获取 除本文所提供内容之外在 HTML 中使用 ARIA 的指导:

  • 使用 ARIA - 一份面向作者的实用指南,介绍如何 使用 Accessible Rich Internet Applications 规范为 HTML 元素 添加可访问性信息。
  • ARIA 创作实践指南 - 一份面向作者的 指南,用于 理解和实现 Accessible Rich Internet Applications。

4.1 使用 ARIA 属性为元素命名的要求

作者可以使用 aria-labelaria-labelledby 属性,为具有允许作者命名的隐式或显式 ARIA 角色的元素指定可访问 名称Accessible Rich Internet Applications (WAI-ARIA) 1.2 定义了允许 作者命名的角色以及禁止作者命名的 角色

作者不得在具有不可命名的隐式 WAI-ARIA 角色的元素上指定 aria-labelaria-labelledby。其隐式 WAI-ARIA 角色禁止作者命名的 HTML 元素在4. 在 HTML 中使用 ARIA 属性的文档一致性要求中标明。

以下标记示例展示了一组具有禁止作者命名的隐式 ARIA 角色的 HTML 元素。

示例 14:具有禁止作者命名的隐式 ARIA 角色的元素
<!-- 不要执行以下操作! -->
<p aria-label="...">...</p>
<span aria-label="...">...<span>
<code aria-label="...">...<code>
<div aria-labelledby="...">...</div>

以下标记示例展示了具有允许作者命名的显式 WAI-ARIA 角色的元素。 由于这些元素上指定了显式角色,因此允许使用 aria-labelaria-labelledby 属性。

示例 15:具有允许作者命名的显式 ARIA 角色的元素
<p role="link" tabindex="0" aria-label="...">...</p>
<span role="button" tabindex="0" aria-label="...">...<span>
<div role="article" aria-labelledby="...">...</div>

4.2 使用 ARIA 属性代替等效 HTML 属性的要求

除非另有说明,否则作者可以在预期具有相应 aria-* 语义的 HTML 元素上,使用 aria-* 属性 代替其 HTML 等效属性。例如,作者可以button 元素上指定 aria-disabled=true,同时实现必要的脚本以在功能上 禁用该 button,而不是使用 disabled 属性。

WAI-ARIA 的“与宿主语言 语义的冲突”中所述, 当 HTML 元素同时使用 aria-* 属性及其宿主语言(HTML) 等效属性时,用户代理必须忽略 WAI-ARIA 属性——具有相同 隐式 ARIA 语义的 原生 HTML 属性优先。因此,作者不应在一个元素上同时指定原生 HTML 属性 和等效的 aria-* 属性。请查阅各个属性以了解任何 进一步的作者特定要求。

下表列出了与 aria-* 属性具有等效关系的 HTML 元素及其属性。

第一列单元格中的每个语言特性(元素和属性)都隐含同一行 第二列单元格中给出的 ARIA 语义(状态和属性)。每行的第三个单元格 定义作者如何使用原生 HTML 特性,以及 使用提供相同 隐式 ARIA 语义aria-* 属性时的要求。

按 HTML 特性划分的 ARIA 属性使用规则
HTML 特性

隐式 ARIA 语义

HTML 特性和 aria-* 属性的作者指南
任何允许使用 checked 属性的元素 aria-checked="true"

在 HTML 中允许使用 checked 属性的任何元素上使用 checked 属性。 使用 indeterminate IDL 属性来指示 input type=checkbox 元素的“混合”状态。

如果元素的选中状态 或元素的不确定选中值可能与 aria-checked 属性的当前值相冲突,则作者不得在任何此类元素上使用 aria-checked 属性。

作者可以在具有允许该属性的 WAI-ARIA 角色的任何 其他元素上使用 aria-checked 属性。

任何允许使用 disabled 属性的元素,包括 option disabledoptgroup disabled aria-disabled="true"

在 HTML 中允许使用 disabled 属性的任何元素上使用 disabled 属性。

作者可以在 HTML 中允许使用 disabled 属性的任何元素上,或具有允许 aria-disabled 属性的 WAI-ARIA 角色的任何元素上使用 aria-disabled 属性。

作者不应在同时具有 disabled 属性的任何 元素上使用 aria-disabled="true"

作者不得在同时具有 disabled 属性的任何 元素上使用 aria-disabled="false"

任何具有 hidden 属性的元素 aria-hidden="true"

除可聚焦元素和 body 元素外, 作者可以在任何允许指定 全局 aria-* 属性的 HTML 元素上使用 aria-hidden 属性。

通常不推荐作者在同时指定了 hidden 属性的任何元素上使用 aria-hidden="true"。但是, 如果元素同时具有处于 找到之前隐藏 状态的 hidden 属性,则作者不得在该元素上使用 aria-hidden="true"

可聚焦元素是指可以通过键盘或 指针设备获得焦点的任何元素。可聚焦元素并不总是 可以通过键盘 Tab 键切换到的元素。例如,具有 tabindex="-1" 的元素是可聚焦的,但不是可通过 Tab 键切换到的元素。
在具有 hidden 属性的元素上使用 aria-hidden="true",往好处说也只是不必要的重复。往坏处说, 如果 hidden 属性默认的用户代理 display: none 样式被作者或用户样式表有意覆盖, 这种用法可能会阻止访问其内容。 最后,如果 hidden 属性处于“找到之前隐藏”状态, 使用 aria-hidden=true 会使这些内容在通过浏览器的页面内查找功能找到并 以可视方式呈现给用户时,仍无法被辅助技术用户 发现。
任何允许使用 placeholder 属性的元素 aria-placeholder="..."

在 HTML 中允许使用 placeholder 属性的任何元素上使用 placeholder 属性。

作者可以在 HTML 中允许使用 placeholder 属性的任何元素上,或具有允许 aria-placeholder 属性的 WAI-ARIA 角色的任何元素上使用 aria-placeholder 属性。

作者不得在同时具有 placeholder 属性的任何元素上使用 aria-placeholder 属性。

任何允许使用 max 属性的元素:meter maxprogress maxinput max aria-valuemax="..."

在 HTML 中允许使用 max 属性的任何元素上 使用 max 属性。

作者可以在具有允许 aria-valuemax 属性的 WAI-ARIA 角色的任何其他元素上使用 aria-valuemax 属性。

作者不应在任何允许使用 max 属性的元素上使用 aria-valuemax。应改用 max 属性。

作者不得在同时具有 max 属性的任何元素上使用 aria-valuemax

任何允许使用 min 属性的元素:meter mininput min aria-valuemin="..."

在 HTML 中允许使用 min 属性的任何元素上 使用 min 属性。

作者可以在具有允许 aria-valuemin 属性的 WAI-ARIA 角色的任何其他元素上使用 aria-valuemin 属性。

作者不应在任何允许使用 min 属性的元素上使用 aria-valuemin。应改用 min 属性。

作者不得在同时具有 min 属性的任何元素上使用 aria-valuemin

任何允许使用 readonly 属性的元素: input readonlytextarea readonly 和允许使用 readonly表单关联 自定义元素 aria-readonly="true"

在 HTML 中允许使用 readonly 属性的任何元素上 使用 readonly 属性。

作者可以在具有允许该属性的 WAI-ARIA 角色的任何元素上使用 aria-readonly 属性。

作者不应在同时具有 readonly 属性的任何元素上使用 aria-readonly="true"

作者不得在同时具有 readonly 属性的任何元素上使用 aria-readonly="false"

具有 contenteditable=true 的元素,或 没有 contenteditable 属性、但最近的 具有 contenteditable 属性的祖先元素拥有 contenteditable="true" 的元素。

这等效于 isContentEditable IDL 属性。

aria-readonly="false" 作者不得在具有 isContentEditable="true" 的元素上设置 aria-readonly="true"
任何允许使用 required 属性的元素:input requiredtextarea required, 和 select required aria-required="true"

在 HTML 中允许使用 required 属性的任何元素 上使用 required 属性。

作者可以在 HTML 中允许使用 required 属性的任何元素上,或具有允许 aria-required 属性的 WAI-ARIA 角色的任何元素上使用 aria-required 属性。

作者不应在同时具有 required 属性的任何元素上使用 aria-required="true"

作者不得在同时具有 required 属性的任何元素上使用 aria-required="false"

任何允许使用 colspan 属性的元素:tdth aria-colspan="..."

在 HTML 中允许使用 colspan 属性的任何元素上 使用 colspan 属性。

作者不应在同时具有 colspan 属性的任何元素上使用 aria-colspan 属性。

如果元素同时具有 colspan 属性,并且两个属性的值不 匹配,则作者不得在该元素上使用 aria-colspan

任何允许使用 rowspan 属性的元素: tdth aria-rowspan="..."

在 HTML 中允许使用 rowspan 属性的任何元素上 使用 rowspan 属性。

作者不应在同时具有 rowspan 属性的任何元素上使用 aria-rowspan 属性。

如果元素同时具有 rowspan 属性,并且两个属性的值不 匹配,则作者不得在该元素上使用 aria-rowspan

4.3 已弃用的 ARIA 角色、状态和属性的要求

ARIA 规范的已弃用 要求一节指出,如果某个 ARIA 特性被标记为已弃用,则建议作者 不要在新内容中使用该特性。

以下角色和属性是 ARIA 和 DPub ARIA 中已弃用的特性。一致性检查器 必须向作者警告这些特性的弃用状态。只要 可能,建议作者使用已弃用特性的替代方案。

4.3.1 已弃用的 ARIA 角色

directory 角色在 WAI-ARIA 1.2 中被标记为弃用。实际上,与具有隐式或显式声明的 list 角色的元素相比,directory 角色在功能上没有任何 差异。建议作者改用 HTML 的原生列表元素之一,或 ARIA list 角色。

4.3.2 已弃用的 DPub ARIA 角色

doc-biblioentrydoc-endnote 角色在 Digital Publishing WAI-ARIA Module 1.1 中被标记为弃用,因为它们不是具有隐式或 显式 list 角色的元素的有效子元素。作者可以使用标准列表及其子 li 元素,而不需要这些角色。

4.3.3 已弃用的 ARIA 属性

aria-dropeffectaria-grabbed 属性在 WAI-ARIA 1.1 中已被弃用。目前 ARIA 中没有可替代其拟议 功能的特性。

4.4 ARIA 角色、状态和属性的大小写要求

对于所有 role 标记值以及值被 定义为标记的任何 状态或属性(aria-*),作者应当使用 ASCII 小写

虽然现代浏览器将 rolearia-* 属性值视为 ASCII 大小写不敏感,但并非所有辅助技术都能正确解析这些值。

为减少互操作性问题,强烈建议作者对 aria-*role 属性值使用 ASCII 小写。此外, 建议作者对不同的浏览器和辅助技术组合进行严格测试,以确保其内容能够正确 暴露给用户。

5. ARIA 角色允许的后代

本节为非规范性内容。

下表将内容类型和允许的 后代信息(在 [HTML] 规范中定义)映射到具有等效 role 的元素,并对其进行了扩展。

第 1 列链接到规范性的 Accessible Rich Internet Applications (WAI-ARIA) 1.2 中各 ARIA role 的定义。 第 2 列标明每个 role 在 HTML 元素上使用时所属的内容 类型类别。 第 3 列指出哪些类型的 HTML 元素可以作为 指定了显式 role 的元素的后代,通常与具有 相同隐式角色的 HTML 元素相匹配。

例如, button 元素具有隐式 role=button。 在 HTML 中,button 元素允许短语内容作为 后代,并且不允许交互式内容 或具有 tabindex 属性的后代。因此,任何指定 role=button 的元素都应遵循 相同的后代限制,不允许任何交互式内容后代、 指定了 tabindex 的元素,或任何其角色值 属于交互式内容类别的元素(在第 3 列中标明)。

不一致后代的示例
<!-- 一致性检查器将报告错误 -->
<button>
  <div role="button">...</div>
</button>
<div role="button">
  <button>...</button>
</div>
<div role="link">
  <textarea>...</textarea>
</div>

此外,还有一些角色,Accessible Rich Internet Applications (WAI-ARIA) 1.2 对其允许的后代规定了特定要求。对于这些特定角色, 第 3 列(后代许可)通过指出“参阅‘必需的拥有元素’” 对这些要求进行了标明。

ARIA 角色允许的后代
角色 内容类别 允许的后代
alert 流内容(Flow content) 流内容(Flow content), 但不得包含 main 元素后代。
alertdialog 流内容(Flow content) 流内容(Flow content)
application 流内容(Flow content) 流内容(Flow content)
article 流内容(Flow content), 但不得包含 main 元素后代。
banner 流内容(Flow content), 但不得包含 mainheaderfooter 元素后代。
blockquote 流内容(Flow content), 但不得包含 main 元素后代。
button 短语内容(Phrasing content),但不得包含 交互内容(Interactive content)后代,也不得包含带有 tabindex 属性的后代。
caption 不适用 流内容(Flow content), 但不得包含 maintable 元素后代。
cell 不适用 流内容(Flow content), 但不得包含 main 元素后代。
checkbox 短语内容(Phrasing content),但不得包含 交互内容(Interactive content)后代,也不得包含带有 tabindex 属性的后代。
code 短语内容(Phrasing content)
columnheader 不适用 流内容(Flow content), 但不得包含 headerfootermain 元素后代。
combobox 流内容(Flow content), 但不得包含 main 元素后代。
complementary 流内容(Flow content), 但不得包含 main 元素后代。
contentinfo 流内容(Flow content), 但不得包含 headerfootermain 元素后代。
definition 短语内容(Phrasing content)
deletion 短语内容(Phrasing content)
dialog 流内容(Flow content) 流内容(Flow content)
directory 流内容(Flow content) 流内容(Flow content), 但不得包含 main 元素后代。
document 流内容(Flow content) 流内容(Flow content)
emphasis 短语内容(Phrasing content)
feed 流内容(Flow content) 流内容(Flow content), 但不得包含 main 元素后代。
figure 流内容(Flow content), 但不得包含 main 元素后代。
form 流内容(Flow content), 但不得包含 form 元素后代。
generic 流内容(Flow content)
grid 参见 ARIA grid 角色所定义的 “Required Owned Elements”。
gridcell 交互内容(Interactive content) 流内容(Flow content), 但不得包含 main 元素后代。
group 流内容(Flow content)
heading 短语内容(Phrasing content)
imgimage 短语内容(Phrasing content),但不得包含交互内容(Interactive content)后代。
insertion 短语内容(Phrasing content)
link 流内容(Flow content), 但不得包含交互内容(Interactive content)后代,也不得包含带有 tabindex 属性的后代。
list 流内容(Flow content) 参见 ARIA list 角色所定义的 “Required Owned Elements”。
listbox 参见 ARIA listbox 角色所定义的 “Required Owned Elements”。
listitem 不适用 流内容(Flow content), 但不得包含 main 元素后代。
log 流内容(Flow content) 流内容(Flow content), 但不得包含 main 元素后代。
main 流内容(Flow content) 流内容(Flow content), 但不得包含 main 元素后代。
marquee 流内容(Flow content) 流内容(Flow content), 但不得包含 main 元素后代。
math 流内容(Flow content) 流内容(Flow content)
menu 参见 ARIA menu 角色所定义的 “Required Owned Elements”。
menubar 参见 ARIA menubar 角色所定义的 “Required Owned Elements”。
menuitem 交互内容(Interactive content) 短语内容(Phrasing content),但不得包含 交互内容(Interactive content)后代,也不得包含带有 tabindex 属性的后代。
menuitemcheckbox 交互内容(Interactive content) 短语内容(Phrasing content),但不得包含 交互内容(Interactive content)后代,也不得包含带有 tabindex 属性的后代。
menuitemradio 交互内容(Interactive content) 短语内容(Phrasing content),但不得包含 交互内容(Interactive content)后代,也不得包含带有 tabindex 属性的后代。
meter 短语内容(Phrasing content),但不得包含 meter 元素后代。
navigation 流内容(Flow content), 但不得包含 main 元素后代。
none 不适用 透明(Transparent)
note 流内容(Flow content) 流内容(Flow content), 但不得包含 main 元素后代。
option 交互内容(Interactive content) 短语内容(Phrasing content),但不得包含 交互内容(Interactive content)后代,也不得包含带有 tabindex 属性的后代。
paragraph 短语内容(Phrasing content)
presentation 不适用 透明(Transparent)
progressbar 短语内容(Phrasing content),但不得包含 progress 元素后代。
radio 短语内容(Phrasing content),但不得包含 交互内容(Interactive content)后代,也不得包含带有 tabindex 属性的后代。
radiogroup 流内容(Flow content)
region 流内容(Flow content), 但不得包含 main 元素后代。
row 不适用 参见 ARIA row 角色所定义的 “Required Owned Elements”。
rowgroup 不适用 参见 ARIA rowgroup 角色所定义的 “Required Owned Elements”。
rowheader 不适用 流内容(Flow content), 但不得包含 main 元素后代。
scrollbar 交互内容(Interactive content)(如果可聚焦) 短语内容(Phrasing content)
search 流内容(Flow content), 但不得包含 main 元素后代。
searchbox 流内容(Flow content), 但不得包含 main 元素后代。
separator 交互内容(Interactive content)(如果可聚焦) 短语内容(Phrasing content)
slider 短语内容(Phrasing content)
spinbutton 流内容(Flow content), 但不得包含 main 元素后代。
status 流内容(Flow content) 流内容(Flow content), 但不得包含 main 元素后代。
strong 短语内容(Phrasing content)
subscript 短语内容(Phrasing content)
superscript 短语内容(Phrasing content)
switch 短语内容(Phrasing content),但不得包含 交互内容(Interactive content)后代,也不得包含带有 tabindex 属性的后代。
tab 交互内容(Interactive content) 短语内容(Phrasing content),但不得包含 交互内容(Interactive content)后代,也不得包含带有 tabindex 属性的后代。
table 参见 ARIA table 角色所定义的 “Required Owned Elements”。
tablist 参见 ARIA tablist 角色所定义的 “Required Owned Elements”。
tabpanel Flow content Flow content
term 短语内容(Phrasing content) 短语内容(Phrasing content)
textbox 交互内容(Interactive content) 流内容(Flow content), 但不得包含 main 元素后代。
time 短语内容(Phrasing content)
timer 流内容(Flow content) 流内容(Flow content), 但不得包含 main 元素后代。
toolbar 流内容(Flow content) 流内容(Flow content), 但不得包含 main 元素后代。
tooltip 流内容(Flow content) 短语内容(Phrasing content)
tree 流内容(Flow content) 参见 ARIA tree 角色所定义的 “Required Owned Elements”。
treegrid 流内容(Flow content) 参见 ARIA treegrid 角色所定义的 “Required Owned Elements”。
treeitem 交互内容(Interactive content) 短语内容(Phrasing content)

6. 一致性

除了标记为非规范性的部分外,本规范中的所有编写指南、图示、示例和注释均为非规范性内容。除此之外,规范中的其他内容均为规范性内容。

本文档中的关键词 MAY(可以)、MUST(必须)、MUST NOT(不得)、NOT RECOMMENDED(不推荐)、SHOULD(应该)、SHOULD NOT(不应该) 应按照 BCP 14 [RFC2119] [RFC8174] 的说明进行解释,仅当这些词以全部大写形式出现时(如本处所示)。

6.1 一致性检查要求

声称支持检查 HTML 文档中 ARIA 的一致性检查器必须按照本规范的定义,对 rolearia-* 属性在HTML 元素上的使用进行一致性要求检查。

一个符合要求的文档不得包含任何带有作者自定义 rolearia-* 属性且属性值不符合本规范规定的使用范围的元素。具体每个HTML 元素的允许值见 4. 在 HTML 中使用 ARIA 属性的文档一致性要求。 一致性检查器应该将作者为元素显式指定与其 隐式 ARIA 语义相同的 role 的情况标记为不符合, 因为不推荐作者显式设置这些角色。

一致性检查器可以自定义术语和严重级别,用于在报告文档不符合本规范时进行分类。

7. 隐私与安全注意事项

本节为非规范性内容。

本规范不定义 [wai-aria-1.2]、 [dpub-aria-1.1] 或 [HTML] 的特性。相反,它提供了 供声称支持检查 HTML 中 ARIA 的一致性 检查器使用的规则和指导,同时也为作者提供指导。

因此,本规范没有已知的隐私或安全影响,因为它未定义任何可能引发相关问题的新特性。

A. 参考文献

A.1 规范性参考文献

[accname-1.2]
可访问名称和描述计算 1.2. Bryan Garaventa; Melanie Sumner. W3C. 2026年5月29日. W3C 工作草案. URL: https://www.w3.org/TR/accname-1.2/
[dpub-aria-1.1]
数字出版 WAI-ARIA 模块 1.1. Matt Garrish; Tzviya Siegman. W3C. 2025年6月12日. W3C 推荐标准. URL:https://www.w3.org/TR/dpub-aria-1.1/
[html]
HTML 标准. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. 现行 标准. URL:https://html.spec.whatwg.org/multipage/
[html-aam-1.0]
HTML 可访问性 API 映射 1.0. Scott O'Hara; Rahim Abdi. W3C. 2026年7月29日. W3C 工作草案. URL:https://www.w3.org/TR/html-aam-1.0/
[infra]
Infra 标准. Anne van Kesteren; Domenic Denicola. WHATWG. 现行标准. URL:https://infra.spec.whatwg.org/
[RFC2119]
用于 RFC 中表示 要求级别的关键词. S. Bradner. IETF. 1997年3月. 当前最佳实践. URL:https://www.rfc-editor.org/info/rfc2119/
[RFC8174]
RFC 2119 关键词中大写与小写的歧义. B. Leiba. IETF. 2017年5月. 当前最佳实践. URL:https://www.rfc-editor.org/info/rfc8174/
[svg-aam-1.0]
SVG 可访问性 API 映射. Cynthia Shelly; Mark Rogers. W3C. 2026年7月27日. W3C 工作草案. URL:https://www.w3.org/TR/svg-aam-1.0/
[wai-aria-1.1]
可访问的富互联网应用(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-1.2]
可访问的富互联网应用(WAI-ARIA) 1.2. Joanmarie Diggs; James Nurthen; Michael Cooper; Carolyn MacLeod. W3C. 2023年6月6日. W3C 推荐标准. URL:https://www.w3.org/TR/wai-aria-1.2/

A.2 补充性参考文献

[using-aria]
Using ARIA(ARIA 使用指南)。 Steve Faulkner;David MacDonald。W3C。2026年2月24日。W3C 工作草案。URL: https://www.w3.org/TR/using-aria/