ARIA: document 角色

描述

document 角色用于包含辅助技术用户可能希望以阅读模式浏览的内容的顶级容器。仅在复杂复合 小部件 或 应用程序 中可获得焦点的（focusable）部分内才有用，document 角色会通知辅助技术将读取上下文切换回阅读模式：document 角色告知具有阅读或浏览模式的辅助技术使用文档模式来读取此元素包含的内容。

<div role="dialog">
  …
  <div id="InfoText" role="document" tabindex="0">
    <p>Some informational text goes here.</p>
  </div>
  …
  <button>Close</button>
</div>

此示例显示了一个 对话框，这是一个复杂复合小部件角色，其中包含一些控件和一个包含一些信息文本的部分，辅助技术用户在选项卡（Tab）到该部分时可以进入阅读模式。

默认情况下，网页被视为文档；辅助技术（AT）在进入新网页时会进入浏览或阅读模式。此模式可以通过各种角色进行更改，包括小部件（widget）角色和应用程序（application）角色。document 角色会将辅助技术带回浏览或阅读模式。

通常放置在应用程序角色或其他交互式小部件角色内，document 角色用于指示复杂复合小部件中辅助技术用户应使用其浏览或虚拟阅读模式（如果可用）来阅读的部分。

由于具有阅读模式的辅助技术默认对除具有小部件或应用程序角色设置的所有元素都采用该模式，因此 document 角色仅对小部件或应用程序内应作为静态富文本读取的可获取焦点元素有用。通过向包含小部件内文本的元素添加 role="document" 和 tabindex="0"，屏幕阅读器用户可以通过按 Tab 键将焦点设置在 document 元素上，并使用屏幕阅读器的阅读光标读取文本。

辅助技术应将上下文切换回文档模式，可能从为父级的动态上下文重新配置的控件中拦截，重新启用标准输入事件，例如 Up 或 Down 箭头键盘事件，以控制阅读光标。

与 article 角色不同，document 角色与具有 document 角色的其他元素没有任何关联，它仅仅与包含它的复合小部件有关。文章（article）可以有关联的文章。

关联的 WAI-ARIA 角色、状态和属性

aria-expanded

如果 document 元素是可折叠的，则包含 true 或 false 的值，以指示 document 当前是展开还是折叠。其他值包括默认的 undefined，表示 document 不可折叠。

tabindex="0"

用于使其可获得焦点，以便辅助技术用户可以选项卡（Tab）到它并立即开始阅读。

键盘交互

应通过在该元素上设置 tabindex="0" 属性/值对使其可获得焦点。这样，用户就可以选项卡（Tab）到它，阅读模式会自动调用，并且内容可以立即被读取。

所需的 JavaScript 功能

无，除非任何属性需要。例如，如果 document 是可折叠的，那么 aria-expanded 的状态和值必须被维护。

示例

一个例子是 Gmail 和单个对话视图。GMail 是一个 Web 应用程序。在 Gmail 中，大多数用户代理交互都被应用程序劫持。但是，当键盘焦点设置在包含对话主题的单个对话的起始标题上时，屏幕阅读器用户可以使用阅读模式命令来阅读消息，展开或折叠它们，并进行操作。一旦焦点通过激活“后退”按钮或按下关联的键盘快捷键返回到消息列表，就会再次调用直接应用程序交互模式，并且用户可以使用 箭头 键将焦点移到列表中的其他对话。

最佳实践

始终确保具有 document 角色的项可获得焦点，通过设置值为 0 的 tabindex 属性。这也会将其包含在选项卡（Tab）顺序中。

新增优势

document 角色是一种通过明确说明这是用户应使用标准屏幕阅读器命令阅读的内容来间接控制辅助技术行为的简便方法。

规范

另见

• ARIA: widget 角色
• ARIA: application 角色