ARIA: scrollbar 角色 - ARIA

描述

scrollbar 是一个范围，它控制视口内容当前在视口框中可见的部分；无论视口是完整的浏览器大小、iframe 还是任何元素的块格式化上下文。

什么是滚动条

当内容区域大于应用程序窗口时，许多应用程序提供原生滚动条。滚动条通常出现在查看区域的右侧或底部。原生滚动条显示为薄矩形轨迹区域，其长度与其控制的视口相同，带有一个称为滑块或滚动块的 UI 部分，该部分可以沿轨迹拖动以在视口内移动相关内容。一些滚动条在轨迹的两端都有箭头，激活时可以使视口滚动一小段预设距离。

以本文档为例：如果视口是完整的浏览器窗口且内容高于视口，在大多数浏览器中，窗口右边缘的滚动条表示页面的总长度，而滚动滑块表示页面内容中当前在视口中的部分。

滚动条也可以出现在作为完整浏览器窗口子部分的视口上。继续以本文档为例，如果此内容嵌入在 <iframe> 或 <object> 中，原生垂直滚动条的高度将是框架的高度。滚动条通常与视口长度相同，但并非必须如此。

如果您当前没有看到滚动条，可能是因为您的浏览器只在滚动时显示滚动条，或者只在元素内容太大而无法适应其块格式化上下文时显示。根据浏览器和操作系统，即使内容适合视口且不需要或不可能滚动时，滚动条也可以设置为可见。

ARIA `scrollbar`

最好始终使用原生滚动条。您可以使用 CSS overflow 属性来确保原生滚动条的出现。CSS 滚动条规范正在开发中。一些浏览器允许通过带前缀的伪元素来样式化滚动条。

由于原生滚动条的样式设置历来受到限制，您可能会遇到需要支持并使其完全可访问的 JavaScript 实现的滚动条。为此，您可以使用 scrollbar 角色来通知辅助技术，某个 UI 控件是交互式滚动条。

带有 scrollbar 角色的元素是一个图形对象，用于控制查看区域中内容的滚动；它是指示元素是滚动条的 ARIA 角色。最相似的 HTML 元素是 range <input> 类型，<input type="range">。

scrollbar 元素有两个必需属性：aria-controls 和 aria-valuenow。aria-controls 属性引用其控制的可滚动区域的 id。aria-valuenow 属性定义滚动条的当前值。

虽然 aria-valuenow 始终是必需的，但 aria-valuemin 和 aria-valuemax 属性仅在 scrollbar 的最小值不为 0 或最大值不为 100 时才需要为滚动条角色设置。aria-valuenow 的值必须始终介于最小值和最大值（含）之间，如果最小值和最大值分别默认为 0 和 100，则介于 0 和 100（含）之间。aria-valuenow 传达视口距离文档底部的远近。把它想象成一个进度条，文档的开始是最小值，文档的结束是最大值。

scrollbar 通过滚动条的大小和滑块相对于其控制的方向（水平或垂直）的可见范围的位置，表示当前值和可能值的范围。换句话说，scrollbar 的长度（高度或宽度）表示视口中的所有内容。aria-valuemin 值表示内容的开始和滚动条的开始，aria-valuemax 值表示内容的结束和滚动条的结束。aria-valuenow 表示视口中当前可见的内容以及可移动滑块的当前位置或值。aria-valuenow 值通常会由辅助技术计算为 aria-valuemin 和 aria-valuemax 之间的百分比。

注意：辅助技术通常将 aria-valuenow 的值呈现为 aria-valuemin 和 aria-valuemax 之间范围的百分比，除非设置了 aria-valuetext。建议以适合此计算的方式设置 aria-valuemin、aria-valuemax 和 aria-valuenow 的值。

与原生滚动条一样，用户直接或间接使用鼠标、触摸板、键盘和语音输入与 scrollbar 元素交互。scrollbar 角色实现也必须适应所有这些交互方法。

使用鼠标时，用户必须能够通过点击滚动条两端的滚动箭头（如果存在）、点击滚动轨迹的空白部分以及点击并拖动滚动滑块来激活 scrollbar。

还必须支持键盘滚动。当焦点位于 scrollbar 控制的视口内时，向上箭头 和 向下箭头（或水平滚动条的 向左箭头 和 向右箭头）应按比例移动滚动条滑块。此外，Page Up、Page Down、Space 和 Shift + Space 键必须在每次按键时将内容和滚动滑块移动视口的高度（或宽度），直到内容的底部或顶部（或左侧或右侧）可见。

必须使用 JavaScript 将 scrollbar 操作转换为滚动命令，通过以下方式向用户提供反馈：

视觉更新 scrollbar 元素，
滚动视口内容，以及
更新 aria-valuenow 属性值。

scrollbar 角色的默认方向是垂直的。在这种情况下，包含 aria-orientation="vertical" 是可选的。方向表示滚动条的方向以及滚动条对查看区域的滚动效果。如果滚动是左右而非上下，则在带有 scrollbar 角色的元素上包含 aria-orientation="horizontal"。

注意：需要一个可访问名称。如果 scrollbar 角色应用于 HTML <input> 元素（或 <meter> 或 <progress> 元素），可访问名称可以来自相关的 <label>。否则，如果存在可见标签，则使用 aria-labelledby；如果不存在可见标签，则使用 aria-label。

所有后代都是展示性的

有某些类型的用户界面组件，当在平台辅助功能 API 中表示时，只能包含文本。辅助功能 API 无法表示 scrollbar 中包含的语义元素。为了解决这个限制，浏览器会自动将角色 presentation 应用于任何 scrollbar 元素的所有后代元素，因为它是一个不支持语义子元素的角色。

例如，考虑以下包含标题的 scrollbar 元素。

html

<div role="scrollbar"><h3>Title of my scrollbar</h3></div>

因为 scrollbar 的后代是展示性的，所以以下代码是等效的：

html

<div role="scrollbar"><h3 role="presentation">Title of my scrollbar</h3></div>

从辅助技术用户的角度来看，标题不存在，因为前面的代码片段在辅助功能树中等同于以下内容：

html

<div role="scrollbar">Title of my scrollbar</div>

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

aria-controls (必需): 通过 id 标识滚动条控制的视口内容。
aria-valuenow (必需): 设置为一个介于 0（如果存在，则为 aria-valuemin）和 aria-valuemax 之间的十进制值，表示滚动条的当前值。
aria-valuetext: 辅助技术通常将 aria-valuenow 的值显示为百分比。如果这没有帮助，请使用此属性使滚动条值对用户更易于理解。
aria-valuemin: 设置为表示最小值的十进制值，且小于 aria-valuemax。如果不存在，默认值为 0。
aria-valuemax: 设置为表示最大值的十进制值，且大于 aria-valuemin。如果不存在，默认值为 100。
aria-labelledby: 当不使用原生表单控件因此无法将滚动条与 <label> 关联时，如果存在可见文本可以提供所需的可访问名称，则设置为包含充当标签的文本元素的 id。否则，使用 aria-label。
aria-label: 如果无法使用 <label>，并且不存在可由 aria-labelledby 引用的可见文本，则提供标签 scrollbar 元素的字符串值，从而提供所需的可访问名称。
aria-orientation: 默认情况下，方向为 vertical。该属性可以包含并设置为 horizontal、undefined（所有角色的默认值，除非另有说明）或 vertical。

键盘交互

向上箭头: 视口中的内容向上移动一行，滑块按比例向上移动滚动条，直到到达内容的顶部和滚动条的顶部。
向下箭头: 视口中的内容向下移动一行，滑块按比例向下移动滚动条，直到到达内容的底部和滚动条的底部。
左箭头: 在水平滚动时，视口中的内容向左移动一个字符的宽度，滑块按比例向左移动滚动条，直到内容的左边缘与视口的左端接合，并且滑块在滚动条的左端对齐。
右箭头: 在水平滚动时，视口中的内容向右移动一个字符的宽度，滑块按比例向右移动滚动条，直到内容的右边缘与视口的右端接合，并且滑块在滚动条的右端对齐。
Page Up 和 Shift + Space: 视口中的内容向上移动一个视口的高度，滑块按比例向上移动滚动条，直到到达内容的顶部和滚动条的顶部。
Page Down 和 Space: 视口中的内容向下移动一个视口的高度，滑块按比例向下移动滚动条，直到内容的底部和滚动条的底部被到达。内容的底部或顶部可见。

示例

以下是一个单词可能太长而无法容纳父容器的示例。

html

<div id="pi-label">Pi</div>
<div id="pi">
  3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
</div>
<div
  role="scrollbar"
  aria-labelledby="pi-label"
  aria-controls="pi"
  aria-orientation="horizontal"
  aria-valuenow="0"
  aria-valuemin="0"
  aria-valuemax="100">
  <div id="thumb"></div>
</div>

当使用 ARIA 角色而不是原生 UI 功能时，必须使用 CSS 来样式化滚动条和滑块，并且必须使用 JavaScript 来处理所有键盘和指针事件。

可以使用 CSS 来确保 PI 的溢出值具有原生滚动条

html

<h3 id="PI">Pi</h3>
<p class="pi" tabindex="0" aria-labelledby="PI">
  3.1415926535897932384626433832795028841971693993751058209749445923078164062862089986280348253421170679
</p>

css

.pi {
  overflow: auto;
  max-width: 100%;
}

上述 CSS 表示，如果段落中最长单词的长度宽于段落的包含框，当用户与段落的视口交互时，将出现原生滚动条。添加了 tabindex 属性，以允许使用键盘的用户导航到溢出的内容并滚动。

规范

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

另见

<input type="range">,
HTML <progress> 元素
HTML <meter> 元素
其他范围小部件包括
- meter
- slider
- separator (如果可聚焦)
- progressbar
- spinbutton
文档 scroll 事件

帮助改进 MDN

了解如何贡献

本页由 MDN 贡献者于 2025年5月12日修改。

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