ARIA: dialog 角色

dialog 角色用于标记基于 HTML 的应用程序对话框或窗口，它将内容或 UI 与 Web 应用程序或页面的其余部分分开。对话框通常使用覆盖层置于页面内容的上方。对话框可以是无模式的（仍然可以与对话框外的内容进行交互）或模式的（只能与对话框内的内容进行交互）。

html

<div
  role="dialog"
  aria-labelledby="dialog1Title"
  aria-describedby="dialog1Desc">
  <h2 id="dialog1Title">Your personal details were successfully updated</h2>
  <p id="dialog1Desc">
    You can change your details at any time in the user account section.
  </p>
  <button>Close</button>
</div>

描述

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

使用 dialog 角色标记对话框元素有助于辅助技术将对话框的内容识别为已分组并与页面其余部分内容分开。但是，仅添加 role="dialog" 并不足以使对话框可访问。此外，还需要执行以下操作：

对话框必须正确标记
键盘焦点必须正确管理

以下各节将描述如何满足这两个要求。

标记

即使对话框本身不需要能够接收焦点，它仍然需要被标记。为对话框提供的标签将为对话框内的交互式控件提供上下文信息。换句话说，对话框的标签充当其内部控件的分组标签（类似于 <legend> 元素为 <fieldset> 元素内的控件提供分组标签）。

如果对话框已有可见的标题栏，则该标题栏中的文本可用于标记对话框本身。实现此目的的最佳方法是通过 aria-labelledby 属性将 role="dialog" 元素进行标记。此外，如果对话框包含除对话框标题外的其他描述性文本，可以使用 aria-describedby 属性将此文本与对话框关联。此方法显示在下面的代码片段中：

html

<div
  role="dialog"
  aria-labelledby="dialog1Title"
  aria-describedby="dialog1Desc">
  <h2 id="dialog1Title">Your personal details were successfully updated</h2>
  <p id="dialog1Desc">
    You can change your details at any time in the user account section.
  </p>
  <button>Close</button>
</div>

注意： 请记住，对话框的标题和描述文本不必是可聚焦的，以便被非虚拟模式下运行的屏幕阅读器感知。ARIA 对话框角色和标记技术的结合应使屏幕阅读器在焦点移入对话框时播报对话框的信息。

所需的 JavaScript 功能

焦点管理

对话框在键盘焦点的管理方式上有特定要求。

对话框应始终至少有一个可聚焦的控件。对于许多对话框，会有一个按钮，如“关闭”、“确定”或“取消”。除了必需的控件外，对话框还可以包含任意数量的可聚焦元素，甚至是整个表单或其他容器小部件，如选项卡。
当对话框出现在屏幕上时，键盘焦点（其控件取决于对话框的目的）应移至对话框内的默认可聚焦控件。对于仅提供基本消息的对话框，可能是“确定”按钮。对于包含表单的对话框，可能是表单中的第一个字段。
在对话框关闭后，键盘焦点应移回它在进入对话框之前的位置。否则，焦点可能会丢失到页面开头。
对于大多数对话框，预期的行为是对话框的制表符顺序会循环，这意味着当用户通过对话框中的可聚焦元素制表时，当到达最后一个元素后，第一个可聚焦元素将被聚焦。换句话说，制表符顺序应包含在对话框内并由对话框约束。
如果对话框可以移动或调整大小，请确保这些操作对键盘用户和鼠标用户都是可执行的。同样，如果对话框提供了特殊功能，如工具栏或上下文菜单，这些功能也必须能被键盘用户触及和操作。
对话框可以是模式的或无模式的。当一个模式对话框出现在屏幕上时，无法与对话框外的任何页面内容进行交互。换句话说，只要模式对话框显示，主应用程序 UI 或页面内容就被视为暂时禁用。对于无模式对话框，在对话框显示时仍然可以与对话框外的内容进行交互。请注意，对于无模式对话框，必须有一个全局键盘快捷键，允许焦点在打开的对话框和主页面之间移动。

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

aria-labelledby: 使用此属性为对话框添加标签。通常，aria-labelledby 属性的值将是用于为对话框命名的元素的 ID。
aria-describedby: 使用此属性描述对话框的内容。

对用户代理和辅助技术的可能影响

当使用 dialog 角色时，用户代理应执行以下操作：

将元素作为对话框公开给操作系统的辅助功能 API。

当对话框正确标记并且焦点移至对话框内的元素（通常是交互式元素，如按钮）时，屏幕阅读器应播报对话框的可访问角色、名称和可选描述，以及播报当前聚焦的元素。

注意： 对于辅助技术应如何处理此技术，观点可能有所不同，并且播报顺序可能因所使用的辅助技术而异。上述信息是其中一种观点，可能会随着规范的定义而改变。

示例

包含表单的对话框

html

<div
  role="dialog"
  aria-labelledby="dialog1Title"
  aria-describedby="dialog1Desc">
  <h2 id="dialog1Title">Subscription Form</h2>
  <p id="dialog1Desc">We will not share this information with third parties.</p>
  <form>
    <p>
      <label for="firstName">First Name</label>
      <input id="firstName" type="text" />
    </p>
    <p>
      <label for="lastName">Last Name</label>
      <input id="lastName" type="text" />
    </p>
    <p>
      <label for="interests">Interests</label>
      <textarea id="interests"></textarea>
    </p>
    <p>
      <input type="checkbox" id="autoLogin" name="autoLogin" />
      <label for="autoLogin">Auto-login?</label>
    </p>
    <p>
      <input type="submit" value="Save Information" />
    </p>
  </form>
</div>

工作示例

jQuery-UI 对话框

注意

注意： 虽然可以阻止键盘用户将焦点移至对话框外的元素，但屏幕阅读器用户仍可能使用其屏幕阅读器的虚拟光标导航到该内容。开发人员确保在模式对话框活动期间，模式对话框外部的内容对所有用户都不可访问非常重要。

规范

规范
无障碍富互联网应用程序 (WAI-ARIA) # dialog
未知规范

另见

帮助改进 MDN

了解如何贡献

此页面最后修改于 2025 年 5 月 12 日，由 MDN 贡献者修改。

在 GitHub 上查看此页面 • 报告此内容的可能问题