HTML 中的 ARIA

W3C 推荐标准

关于本文档的更多信息
此版本:
https://www.w3.org/TR/2025/REC-html-aria-20250805/
最新发布版本:
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'Hara (Microsoft)
Patrick H. Lauke (TetraLogical)
前编辑:
Steve Faulkner (TPGi) - 截止于
反馈:
GitHub w3c/html-aria (拉取请求, 新问题, 开放问题)
public-webapps@w3.org 邮件标题请使用 [html-aria] … 消息主题 … (存档)
勘误:
存在勘误

另见 翻译.


摘要

本规范定义了在 [HTML] 元素上使用 可访问富互联网应用(WAI-ARIA)1.2数字出版 WAI-ARIA 模块 1.0 属性的编写规则(作者符合性要求)。 本规范的主要目标是为作者(即 Web 开发者)使用的合规性检查工具定义要求。这些要求将帮助作者开发网页内容,包括使用 ARIA 补充或扩展宿主语言 [HTML] 功能的自定义界面和小部件。

本文档状态

本节描述了本文档在发布时的状态。当前 W3C 发布物和本技术报告最新修订版可在 W3C 标准和草案索引中找到。

ARIA in HTML 是一个 [HTML] 规范模块。任何该规范模块引用但未明确定义的 HTML 功能、符合性要求或术语,均由 HTML 标准 定义。

自本规范于 2021 年 12 月 9 日成为 W3C 推荐标准以来,已提出以下实质性新增和/或修正:

文档审阅者可通过文档中的特殊样式标识候选新增和/或修正:

候选修正会在文档中标记。

候选新增会在文档中标记。

本文档由 Web 应用工作组按照 推荐标准流程发布为推荐标准。包含 候选修订, 自上一版推荐标准以来引入了实质性变更和新特性。

W3C 推荐将本规范作为 Web 标准广泛部署。

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

候选新增会在文档中标记。

候选修正会在文档中标记。

本文档由一组成员依据 W3C 专利政策制定。 W3C 维护着 公开的专利披露列表 ,其中列出了与工作组成果相关的专利披露;该页面还包括专利披露说明。任何个人如确知专利且认为其包含 必要权利要求 ,必须按照 《W3C 专利政策》第6节进行披露。

本文档受 2023年11月3日 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 role="button">...</button>

同样,下面的例子在 fieldset 元素上使用了 role=group, 在 main 元素上使用了 role=Main。 这些都是不必要的,因为 fieldset 元素本身隐式暴露为 role=groupmain 元素也隐式暴露为 role=main。 实践中,只要 role 值使用 ASCII 小写, 一般不会对辅助技术用户造成副作用。 更多信息请见 4.4 ARIA 角色、状态和属性的大小写要求

示例 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 元素同样禁止作者指定这些属性。

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

注意

虽然设置与隐式 ARIA 语义匹配的 ARIA role 和/或 aria-* 属性不推荐,但某些情况下显式设置这些属性可能很有帮助——例如某些用户代理未对特定元素暴露隐式 ARIA 语义时。

注意

按照下表,使用 数字出版 WAI-ARIA 模块 1.0 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

role 外不可指定其他角色 仅允许 link,但不推荐

全局 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-glossary doc-pullquotedoc-tip

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

audio 无对应角色

角色: application

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

autonomous custom element

来自作者定义的 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

role 外不可指定其他角色 仅允许 generic,但不应使用

禁止命名

另外,允许用于 generic 角色的全局 aria-* 属性 但作者不得body 元素上指定 aria-hidden=true

br 无对应角色

角色: nonepresentation

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

button

role=button

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

角色: checkboxcomboboxgridcelllinkmenuitemmenuitemcheckboxmenuitemradiooptionradio separatorsliderswitchtab, 或 treeitem。 (亦允许 button,但不推荐。)

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


如果 buttonselect 元素的第一个子元素: 不可指定 rolearia-* 属性

canvas 无对应角色

任意 role

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

caption role=caption

role 外不可指定其他角色 仅允许 caption,但不推荐

禁止命名

另外,全局 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

role 外不可指定其他角色 仅允许 listbox,但不推荐

aria-* 属性

dd 无对应角色

role

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

del role=deletion

任意 role,但 deletion不推荐

禁止命名

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

details role=group

role 外不可指定其他角色 仅允许 group,但不推荐

全局 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 后代:
role 外不可指定其他角色 除了 figure, 且不推荐

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 只有在提供了 可访问名称时, 才会被暴露为地标区域(landmark)。

form-associated custom element

由作者在 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

role 外不可指定其他角色 除了 documentgeneric,且它们不推荐

不允许任何 aria-* 属性

i role=generic

任意 role,尽管 generic不应 使用。

禁止命名

其他情况下,全局 aria-* 属性 以及适用于允许角色的任何 aria-* 属性。

iframe 无对应角色

角色: applicationdocumentimgimagenonepresentation

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

img
img 具有非空 altalt="some text")或通过其他 img 命名方法提供了可访问名称, 或 img 没有 alt 且未被提供名称:
role=img or image

角色: buttoncheckboxlink math menuitemmenuitemcheckboxmenuitemradio meter optionprogressbar radio scrollbarseparatorsliderswitchtabtreeitem。 (img or image 也允许,但不推荐。)

DPub 角色: doc-cover

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

img 无可访问名称

imgalt 为空 (alt="") 且缺少其他 img 命名方法
role=nonerole=presentation

img 缺少 alt 属性且缺少任何其他 img 命名方法
role=img or image

img 没有 alt 属性或可访问名称: role 外不可指定其他角色,仅限 role=nonepresentation 角色。 (role=img or image 也允许,但不推荐。)

img 具有空的 alt="" 属性且没有 aria-labelaria-labelledby 为其提供可访问名称: role 外不可指定其他角色,仅限 role=nonepresentation 角色,且不推荐

不允许 aria-* 属性aria-hidden="true" 外。

否则,若 img 具有作者定义的可访问名称, 参见 具有可访问名称的 img

input type=button role=button

角色: checkbox combobox gridcell linkmenuitemmenuitemcheckboxmenuitemradiooptionradio separatorslider switchtab, 或 treeitem。 (button 也允许,但不推荐。)

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

input type=checkbox role=checkbox

角色: menuitemcheckboxoptionswitchbutton(若与 aria-pressed 一起使用)。 (checkbox 也允许,但不推荐。)

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

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

注意

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

input type=color 无对应角色

不允许 role

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

input type=date 无对应角色

不允许 role

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

input type=datetime-local 无对应角色

不允许 role

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

input type=emaillist 属性 role=textbox

role 外不可指定其他角色 除了 textbox,且不推荐

全局 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

role 外不可指定其他角色 除了 spinbutton,且不推荐

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

input type=password 无对应角色

不允许 role

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

input type=radio role=radio

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

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

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

注意

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

input type=range role=slider

role 外不可指定其他角色 除了 slider,且不推荐

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

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

input type=reset role=button

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

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

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

input type=search, 且无 list 属性 role=searchbox

role 外不可指定其他角色 除了 searchbox,且不推荐

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

input type=submit role=button

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

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

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

input type=tel, 且无 list 属性 role=textbox

role 外不可指定其他角色 除了 textbox,且不推荐

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

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

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

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

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

role 外不可指定其他角色 除了 combobox,且不推荐

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

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

input type=time 无对应角色

不允许 role

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

input type=url 且无 list 属性 role=textbox

role 外不可指定其他角色 除了 textbox,且不推荐

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

input type=week 无对应角色

不允许 role

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

ins role=insertion

任意 role,尽管 insertion不推荐

禁止命名

其他情况下,全局 aria-* 属性 以及适用于允许角色的任何 aria-* 属性。

kbd 无对应角色

任意 role

禁止命名

其他情况下,全局 aria-* 属性 以及适用于允许角色的任何 aria-* 属性。

label 无对应角色

如果 label 元素隐式或显式关联到 可标注(labelable) 元素,则 不允许 role

否则,若 label 未与元素关联,则任意 role, 尽管 generic不应使用。

禁止命名(若以 generic 角色暴露,或以其他禁止命名的角色暴露)。

其他情况下,全局 aria-* 属性

legend 无对应角色

不允许 role

禁止命名

其他情况下,全局 aria-* 属性

li

li 是列表元素的子元素 (ulolmenu),则 role=listitem

否则,若 li 不是列表元素的子元素,则以 role=generic 暴露。

role 外不可指定其他角色,除 listitem 外(不推荐), 若父级列表元素具有隐式或显式 list 角色。

否则,若父级列表元素未暴露为隐式或显式 list 角色,则任意 role

注意

关于列表元素允许的角色,参见 ulolmenu

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

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

link 无对应角色

不允许 rolearia-* 属性

main role=main

role 外不可指定其他角色 除了 main,且不推荐

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

map 无对应角色

不允许 rolearia-* 属性

mark 无对应角色

任意 role

禁止命名

其他情况下,全局 aria-* 属性 以及适用于允许角色的任何 aria-* 属性。

math role=math

role 外不可指定其他角色 除了 math,且不推荐

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

menu role=list

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

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

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

meta 无对应角色

不允许 rolearia-* 属性

meter role=meter

role 外不可指定其他角色 除了 meter,且不推荐

作者不应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

role 外不可指定其他角色 除了 group,且不推荐

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

option 元素,处于选项列表中, 或在 datalist 中表示建议 role=option

role 外不可指定其他角色 除了 option,且不推荐

作者不应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

role 外不可指定其他角色 除了 progressbar,且不推荐

作者不应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

角色: alertalertdialogapplicationbannercomplementarycontentinfodialogdocumentfeedgroup logmainmarqueenavigationnonenotepresentationsearchstatustabpanel。 (亦允许 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 (没有 multiple 属性,且没有 size 属性值大于 1 role=combobox

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

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

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

select (带有 multiple 属性或 size 属性值大于 1 role=listbox

role 外不可指定其他角色 仅允许 listbox,但不推荐

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

其他情况下,任何 全局 aria-* 属性 以及适用于 listbox 角色的其他 aria-* 属性。

selectedcontent role=generic

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

否则,任意 role,如果该元素用在自定义 select 元素的 button 部分以外的上下文中,尽管 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 元素隐式暴露为 ARIA role=button

不允许 role 如果 summary 元素是 其父 details 的 summary

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

否则,作者可以指定 任意 role,以及任何 全局 aria-* 属性 和适用于允许角色的所有 aria-* 属性。

sup role=superscript

任意 role,尽管 superscript 不推荐

禁止命名

其他情况下,全局 aria-* 属性 以及适用于允许角色的任何 aria-* 属性。

SVG role=graphics-document,定义见 SVG AAM

任意 role,尽管 graphics-document 不推荐

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

table role=table

任意 role,尽管 table 不推荐

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

tbody role=rowgroup

任意 role,尽管 rowgroup 不推荐

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

td

role=cell,如果其祖先 table 元素以 role=table 暴露

role=gridcell,如果其祖先 table 元素以 role=gridtreegrid 暴露

无对应角色,如果其祖先 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

role 外不可指定其他角色 仅允许 textbox,但不推荐

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

tfoot role=rowgroup

任意 role,尽管 rowgroup 不推荐

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

th

role=columnheaderrowheadercell,如果其祖先 table 元素以 role=table 暴露

role=columnheaderrowheadergridcell,如果其祖先 table 元素以 role=gridtreegrid 暴露

无对应角色,如果其祖先 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=tablegridtreegridrole 外不可指定其他角色 仅允许 row,但不推荐; 否则 任意 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 向辅助技术用户暴露。 因此,建议作者在诸如 divspan 这样的语义中性元素上添加 role 属性,而不是覆盖列表中这些元素的语义。

注意

建议作者参考以下文档,以获得超出本节所提供内容的在 HTML 中使用 ARIA 的指导:

  • Using ARIA —— 面向作者的实用指南,介绍如何使用可访问富互联网应用规范为 HTML 元素添加无障碍信息。
  • WAI-ARIA Authoring Practices 1.2 —— 作者指南,帮助理解和实现可访问富互联网应用。

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"

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

一般而言,作者在同时指定了 hidden 属性的元素上使用 aria-hidden="true"不推荐。然而,作者不得在 处于 until-found 状态且同时带有 hidden 属性的任何元素上使用 aria-hidden="true"

注意
可聚焦元素是任何可通过键盘或指针设备获得焦点的元素。可聚焦元素并不总是可以通过键盘 Tab 键聚焦的元素。 例如,带有 tabindex="-1" 的元素是可聚焦的,但不是可通过 Tab 键聚焦的元素。
注意
在具有 hidden 属性的元素上使用 aria-hidden="true" 至多是多余, 至少是没有必要;最糟糕的情况是,如果作者或用户样式表有意覆盖了 hidden 属性的默认 UA 样式 display: none,其使用会阻止访问该内容。 最后,如果 hidden 属性的值为 until-found,则使用 aria-hidden=true 会阻止当通过浏览器页面内查找功能发现并可视化呈现给用户时, 该内容被辅助技术用户发现。
任何允许使用 placeholder 属性的元素 aria-placeholder="..."

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

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

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

任何允许使用 max 属性的元素:meter maxprogress max, 以及 input 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 属性的祖先 的 contenteditablecontenteditable="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 的已弃用特性。一致性检查器MUST就这些特性的已弃用状态向作者发出警告。在可能的情况下,建议作者使用这些已弃用特性的替代方案。

4.3.1 已弃用的 ARIA 角色

注意

directory 角色在WAI-ARIA 1.2中被标记为“将弃用”。实际上,directory 角色与具有隐式或显式 list 角色的元素没有功能差异。建议作者改用 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 角色、状态和属性的属性大小写要求

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

注意

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

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

5. ARIA 角色允许的后代

本节为非规范性内容。

下表将(并扩展)内容类型(Kinds of content)与允许的后代 信息(定义于 [HTML] 规范)映射到具有等效 role 的元素。

第 1 列链接到每个 ARIA role 的规范性定义(Accessible Rich Internet Applications (WAI-ARIA) 1.2)。 第 2 列标明当某个 role 用于 HTML 元素时,它所属的内容类型 类别。 第 3 列指示在明确指定 role 的元素中可以包含哪些类型的 HTML 后代,通常与具有相同隐式角色的 HTML 元素一致。

例如, button 元素具有隐式的 role=button。 在 HTML 中,button 元素允许包含短语内容(Phrasing content)作为后代, 且不允许交互内容(Interactive content) 或带有 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 列(允许的后代)中标注为“参见 Required Owned Elements”,请针对相应角色查看。

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”。
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.0] 或 [HTML] 的特性。相反,本规范为声称支持 HTML 中 ARIA 检查的一致性检查器提供规则和指导,同时为作者提供指导。

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

A. 参考文献

A.1 规范性参考文献

[accname-1.2]
可访问名称与描述计算 1.2。Bryan Garaventa;Melanie Sumner。W3C。2025年6月17日。W3C 工作草案。URL: https://www.w3.org/TR/accname-1.2/
[dpub-aria-1.0]
数字出版 WAI-ARIA 模块 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/
[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。2025年7月30日。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/rfc/rfc2119
[RFC8174]
RFC 2119 关键词中大小写歧义。B. Leiba。IETF。2017年5月。最佳当前实践。URL: https://www.rfc-editor.org/rfc/rfc8174
[svg-aam-1.0]
SVG 可访问性 API 映射。Amelia Bellamy-Royds;Ian Pouncey。W3C。2018年5月10日。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]
ARIA 使用指南。Steve Faulkner;David MacDonald。W3C。2018年9月27日。W3C 工作草案。URL: https://www.w3.org/TR/using-aria/
[wai-aria-practices-1.2]
WAI-ARIA 编写实践 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/