ARIA 角色、状态与属性

一种实时区域，用于传达紧急、时效性强的消息。屏幕阅读器会立即读出，并打断当前正在播报的内容。应谨慎使用——仅保留给真正的错误和警告；滥用会导致辅助技术疲劳。

一种传达紧急消息并要求用户响应的对话框。结合了对话框语义与提醒播报特性。仅用于破坏性操作的确认、阻止后续工作的错误，或其他无法延迟处理的中断场景。

标记一个可以独立存在的自包含内容——博客文章、新闻报道、论坛回复或产品卡片。优先使用原生 <article> 元素；仅在无法使用 HTML 元素时才使用 role="article"。

原生 HTML： <article>

全站标题地标 — 通常包含网站徽标、主导航和搜索框。顶层 <header> 元素会自动具有此角色。每个页面只允许有一个 banner。

原生 HTML： <header> (top-level)

将元素标记为按钮 — 一个在激活时触发操作的控件。优先使用原生 HTML <button> 元素；仅在无法使用原生元素时，才在 <div> 或 <span> 上使用 role="button"。

原生 HTML： <button>

将元素标记为二态或三态复选框。优先使用 <input type="checkbox">；仅当无法使用原生输入时才使用 role="checkbox"——例如，需要构建必须显示混合值的三态控件。

原生 HTML： <input type="checkbox">

将文本输入框与弹出值列表配对标记——用于自动补全、即时搜索和自定义下拉选择。原生 <select> 元素可处理简单的单选场景；仅当需要筛选、自定义渲染或远程建议时才使用 role="combobox"。

原生 HTML： <select>

用于承载与主要内容相关但本身具有独立意义的内容的地标角色——侧边栏、相关文章栏、补充说明框。处于顶层的 <aside> 元素会自动携带此角色。

原生 HTML： <aside>

全站页脚地标——版权声明、联系方式、法律链接。顶层 <footer> 元素会自动携带此角色。每个页面只能有一个 contentinfo。

原生 HTML： <footer> (top-level)

将元素标记为某个术语的定义。需与 role="term"（或原生 <dfn>）配合使用，以将术语与其定义关联。优先使用原生 <dl>/<dt>/<dd> 或 <dfn>——这些元素本身即携带相应语义。

原生 HTML： <dfn>

将容器标记为模态或非模态对话框。建议使用原生 <dialog> 元素配合 showModal()——它可自动处理焦点限制、顶层渲染、背景遮罩以及 Escape 关闭功能。仅在无法使用原生元素时才借助 role="dialog"。

原生 HTML： <dialog>

标记一个自成一体的图示块 — 图片、图表、代码清单 — 通常配有说明文字。优先使用原生 <figure> 元素；仅在宿主元素无法使用 <figure> 时，才使用 role="figure"。

原生 HTML： <figure>

表单地标 — 用于提交数据的一组输入控件。<form> 元素仅在拥有无障碍名称时才会作为表单地标暴露。若无名称，它只是一个普通表单，而非地标。

原生 HTML： <form aria-label>

标记一组相关元素的通用分组。语义权重低于地标 — 屏幕阅读器不会在地标菜单中列出分组。表单控件分组应使用 <fieldset> + <legend>；role="group" 适用于非表单类分组。

原生 HTML： <fieldset>

将元素标记为标题。应优先使用 <h1>–<h6>——原生标题元素天然具备正确的语义及级别。仅在无法使用 <h*> 元素时，才考虑使用 role="heading" 来升级其他元素。

原生 HTML： <h1> – <h6>

将元素标记为超链接——激活时导航到新资源的控件。优先使用原生 HTML <a href> 元素；只有在无法使用原生元素的情况下，才对 <span> 或 <div> 使用 role="link"。

原生 HTML： <a href>

将元素标记为列表项的容器。优先使用 <ul>、<ol> 或 <dl>——原生元素自动处理角色、项目计数和视觉标记符。只有当 CSS list-style: none 触发 Safari 的列表角色移除启发式规则时，才使用 role="list"。

原生 HTML： <ul> / <ol>

将元素标记为可选选项的列表。简单的单选场景请使用 <select>——原生元素提供适合移动端的选择器与完整的键盘支持。仅在需要自定义样式、带自定义渲染的多选功能，或与组合框配合使用时，才使用 role="listbox"。

原生 HTML： <select> (单选)

将元素标记为列表中的一个条目。在 <ul> 或 <ol> 内使用 <li>——原生元素自带角色及所在位置信息。仅在与非列表父元素上显式声明的 role="list" 配合使用时，才使用 role="listitem"。

原生 HTML： <li>

主内容地标 — 页面的主要内容区域，不包含重复出现的页眉、导航和页脚。<main> 元素会自动具有此角色。每个页面只允许有一个 main。

原生 HTML： <main>

将容器标记为应用菜单 — 即「文件/编辑」风格菜单或上下文菜单的弹出层。没有对应的 HTML 等效元素。网站导航列表不是 menu；应使用包含链接 <ul> 的 <nav>。

将容器标记为持久菜单栏 — 即桌面应用中始终可见的水平「文件/编辑/查看」风格菜单条。与弹出式的 menu 不同。在 Web 上几乎从不是正确的选择。

将元素标记为菜单或菜单栏内的可操作项。没有对应的 HTML 原生元素——菜单是仅靠 ARIA 实现的构件。仅在构建真正的应用程序式菜单时使用此角色；普通导航列表不应使用 menu/menuitem。

地标角色，用于分组一组导航链接——主导航、面包屑、目录。<nav> 元素自动具备此角色。每页出现多个 nav 很常见且没有问题，但每个 nav 必须具有独特的无障碍名称。

原生 HTML： <nav>

将元素标记为 listbox 内的可选项。option 必须是 listbox 的后代（直接嵌套或通过 aria-owns 关联）。原生 <option> 应嵌套在 <select> 中使用；仅当构建自定义 listbox 或 combobox 弹出层时，才使用 role="option"。

原生 HTML： <option>

将元素标记为进度指示器。优先使用 <progress>——它原生提供语义、确定性视觉效果及数值属性。仅当需要对原生元素进行深度样式定制时，才考虑使用 role="progressbar"。

原生 HTML： <progress>

将元素标记为互斥选项组中的单个选项。radio 必须置于 radiogroup（或原生 fieldset）内。优先使用 <input type="radio">；仅当无法使用原生输入框时，才考虑 role="radio"。

原生 HTML： <input type="radio">

用于不适合 banner、main、navigation、complementary 或 contentinfo 的内容的通用地标 — 但该内容足够重要，值得用户导航至此。<section> 仅在拥有无障碍名称时，才会成为 region 地标。

原生 HTML： <section aria-label>

用于包裹搜索表单的地标区域，让屏幕阅读器用户可直接跳转至站内搜索。原生 <search> 元素（HTML 2024）会自动携带此角色；如需兼容更多浏览器，可在 <form> 上使用 role="search"。

原生 HTML： <search>

将元素标记为专用于搜索任务的文本输入框。优先使用 <input type="search"> — 它在大多数浏览器上可提供清除按钮交互及免费的搜索语义。仅在自定义 contenteditable 搜索字段上才需使用 role="searchbox"。

原生 HTML： <input type="search">

将元素标记为内容区块之间或复合组件内项目之间的分隔符。在段落文本中使用 <hr> 作为主题分隔线；仅在菜单、工具栏或其他组件内部分隔项目时，才使用 role="separator"。

原生 HTML： <hr>

将元素标记为从范围内选取值的输入控件。优先使用 <input type="range">；仅在需要自定义轨道时才使用 role="slider"——例如原生控件不支持的双滑块范围选择器。

原生 HTML： <input type="range">

一种传递非紧急建议性信息的动态区域。屏幕阅读器以礼貌模式播报变化——在当前语音停顿后插入，不打断正在进行的朗读。适用于常规确认、数量提示和进度更新。原生 <output> 元素自动具有该角色。

原生 HTML： <output>

将元素标记为开关控件。功能上与复选框相近，但播报为“开关，开启”或“开关，关闭”，而非“已选中”——更符合设置切换的语义。目前尚无对应的原生 HTML 元素。

将元素标记为选项卡界面中的一个标签页。tab 必须位于 tablist 内部，并应通过 aria-controls 引用其关联的 tabpanel。HTML 中没有原生标签页元素——标签页是纯 ARIA 模式。

将容器标记为选项卡界面中的标签条。其子元素为 role="tab"。标签页与 tabpanel 是纯 ARIA 模式——HTML 中没有原生的 tablist 元素。

标记与某个标签页配对的内容面板。每个 tabpanel 通过 aria-labelledby 由其对应的 tab 命名；tab 则通过 aria-controls 引用该面板。每次仅显示一个面板，其余面板使用 hidden 属性隐藏。

将元素标记为单行或多行文本输入框。优先使用 <input type="text"> 或 <textarea>——它们免费处理所有文本框行为。仅在为 contenteditable 元素构建富文本编辑器时，才使用 role="textbox"。

原生 HTML： <input type="text"> / <textarea>

将容器标记为工具栏——一组相关控件的集合（格式栏、图标按钮行）。降低 Tab 停留成本：10 个按钮组成的工具栏只占一个 Tab 停止点，通过方向键在按钮间移动。

将元素标记为由 treeitem 组成的层级容器——文件浏览器、嵌套分类或组织结构图。单 Tab 停止点，方向键导航，支持展开/折叠。无对应的原生 HTML 等效元素。

将元素标记为树形结构中的一个节点。treeitem 可以是可展开的（拥有子节点）或终端的（叶节点）。仅在构建需要单个制表位箭头键导航的层级浏览器时使用——文件资源管理器、组织架构图、嵌套分类等。

控制辅助技术在实时区域更新时是播报整个内容，还是仅播报变更部分。默认值为 "false"（仅播报差异）。当上下文只有作为完整句子才有意义时，应设置为 "true"。

将某个区域标记为正在更新中，使辅助技术暂不播报过渡性通知。在加载或大量 DOM 变更进行期间设为 "true"；当区域稳定后切换回 "false"。

表示复选框、单选按钮或复选式菜单项的当前选中状态。取值为 "true"、"false" 或 "mixed"。原生 HTML 复选框会自动管理此状态——仅在自定义组件上手动设置。

标记集合中代表当前项目的元素——导航栏中的当前页面、向导中的当前步骤、日期选择器中的今天。比 aria-selected 更具针对性；应用于链接及“选中”语义不适用的场景。

表示控件可感知、可聚焦，但不响应用户输入。在原生 HTML disabled 属性可用时优先使用；仅当需要元素保持可聚焦或能接收提示信息时才使用 aria-disabled。

指示可折叠元素——展开式按钮、组合框、菜单、树形项——当前是否处于展开状态。取值为 "true" 或 "false"，通常与 aria-controls 配对，指向该控件所打开的区域。

将元素及其所有后代从无障碍树中移除。视力正常的用户仍可看到该元素；辅助技术则完全无法访问。应仅用于装饰性内容，切勿将其应用于可聚焦的控件。

表示表单控件未通过验证。应配合 aria-describedby 指向可供人阅读的错误消息，以便屏幕阅读器同时播报无效状态及其原因。

将区域标记为其更新应由辅助技术宣读、而无需移动焦点的区域。大多数情况选用 "polite"，仅在内容确实紧急时选用 "assertive"。该区域必须在初始渲染时就存在于 DOM 中。

告知辅助技术在对话框打开期间将页面其余部分视为惰性。在 role="dialog" 或 role="alertdialog" 上设置为 "true"。此属性本身并不会真正使背景内容惰性——需配合 inert 属性或焦点陷阱一同使用。

表示切换按钮当前是否处于按下状态。切换开启时设为 "true"，关闭时设为 "false"；辅助技术会在播报标签的同时播报该状态。

表示表单控件的值不可编辑，但控件仍可操作 — 可聚焦、可复制，且值会随表单一同提交。与 aria-disabled 不同，后者使控件完全无法操作。

表示单选或多选容器中的某个条目当前处于已选中状态。适用于 tab、option、gridcell、treeitem 等角色。与 aria-checked（复选框/单选按钮）和 aria-pressed（切换按钮）含义不同。

在复合构件上，指向当前处于激活状态的后代元素的 ID。DOM 焦点保持在容器上，虚拟焦点在子元素间移动。是列表框、组合框和网格采用漫游 tabindex 方案的替代方式。

在文本框或组合框上，声明控件提供哪种类型的自动完成功能——内联建议、选项列表、两者兼有或无。与 HTML autocomplete 属性不同，后者用于浏览器层面的表单字段语义。

声明此控件所管辖的元素或元素集合——包括其存在或内容。常见组合：标签页控制其面板，展开按钮控制被显示的区域。辅助技术对此属性的支持参差不齐，应谨慎使用。

引用一个或多个元素的 ID，将其文本内容作为当前元素的扩展描述，在无障碍名称之后朗读。适用于帮助文本、格式提示和内联错误信息。

告知辅助技术：激活此控件将打开一个弹出层，并说明弹出层的类型。可接受的值为 "menu"、"listbox"、"tree"、"grid"、"dialog" 或 "true" / "false"。应与 aria-expanded 配合使用，以便辅助技术同时通报弹出层的展开状态。

在没有可见文本时，以字符串形式提供无障碍名称。仅在页面上没有可见标签时使用 — 若存在可见文本，应优先使用 aria-labelledby，以确保播报内容与用户所见一致。

引用一个或多个元素的 ID，将其可见文本作为当前元素的无障碍名称。当页面上已有文本描述该控件时，优先于 aria-label 使用。

表示元素在结构中的层级位置。在 role="heading" 元素上为必填属性；也可用于嵌套列表中的 role="treeitem" 和 role="listitem"。值为正整数，从 1 开始。

当 DOM 结构无法表达父子关系时，在无障碍树中声明该关系，将被引用元素作为当前元素的子项重新归属，供辅助技术使用。这是一个强力工具，容易误用。

当 DOM 无法表达项目位置时（通常因列表虚拟化、分页或过滤），标注该项在集合中的位置。必须与 aria-setsize 配合使用，以便屏幕阅读器能报告“第 3 项，共 47 项”。

表示在表单提交前，用户必须填写该控件的值。原生表单字段应使用 HTML required 属性；仅当不存在 HTML 等效属性时才使用 aria-required — 例如基于 div 构建的 combobox。

当 DOM 中未包含集合的全部项目时，用于声明集合的总项目数。与 aria-posinset 配合使用，使屏幕阅读器能够播报“第 14 项，共 5,000 项”，即使当前仅渲染了其中五项。若总数未知，使用 -1。

在可排序网格或表格的列标题或行标题上，声明当前排序方向。可选值为 "ascending"、"descending"、"other" 或 "none"。同一时刻表格中只应有一个标题处于已排序状态。

范围类小部件（滑块、进度条、spinbutton、滚动条）的当前数值。需与 aria-valuemin 和 aria-valuemax 配合使用，以便辅助技术宣告有意义的位置。非数字标签请使用 aria-valuetext。