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 上檢視此頁面 • 報告此內容問題