ARIA: progressbar 角色

描述

progressbar 範圍控制元件表明已收到請求，並且應用程式正在朝著完成所請求的操作取得進展。

作者可以設定 aria-valuemin 和 aria-valuemax 來指示進度指示器的最小值和最大值。否則，它們的隱式值遵循 HTML <input type="range"> 的相同規則

• 如果 aria-valuemin 缺失或不是數字，則預設為 0（零）。
• 如果 aria-valuemax 缺失或不是數字，則預設為 100。
• 只有當進度條的最小值不是 0 或最大值不是 100 時，才需要為 progressbar 角色設定 aria-valuemin 和 aria-valuemax 屬性。
• 應提供並更新只讀的 aria-valuenow，除非值為 indeterminate（不確定），在這種情況下，請不要包含該屬性。如果設定了該屬性，請確保 aria-valuenow 的值介於最小值和最大值之間。

如果 progressbar 角色應用於 HTML <progress> 元素，則可訪問名稱可以來自關聯的 <label>。否則，如果存在可見標籤，請使用 aria-labelledby；如果不存在可見標籤，請使用 aria-label。

所有後代都是展示性的

某些使用者介面元件，當在平臺輔助功能 API 中表示時，只能包含文字。輔助功能 API 無法表示 progressbar 中包含的語義元素。為了解決此限制，瀏覽器會自動將 presentation 角色應用於任何 progressbar 元素的子元素，因為它是一個不支援語義子元素的角色。

例如，考慮以下包含標題的 progressbar 元素。

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

由於 progressbar 的子元素是表示性的，因此以下程式碼是等效的

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

從輔助技術使用者的角度來看，標題不存在，因為前面的程式碼片段在輔助功能樹中等同於以下內容：

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

關聯的 WAI-ARIA 角色、狀態和屬性

aria-valuenow

僅當值不是不確定時才存在且必需。設定為介於 0（或 aria-valuemin，如果存在）和 aria-valuemax 之間的十進位制值，表示進度條的當前值。

aria-valuetext

輔助技術通常將 aria-valuenow 的值顯示為百分比。如果這不準確，請使用此屬性使進度條值易於理解。

aria-valuemin

設定為表示最小值並小於 aria-valuemax 的十進位制值。如果不存在，則預設值為 0。

aria-valuemax

設定為表示最大值並大於 aria-valuemin 的十進位制值。如果不存在，則預設值為 100。

aria-label 或 aria-labelledby

定義字串值或標識用於標記 progressbar 元素（提供可訪問名稱）的元素。需要可訪問名稱。

建議使用原生的 <progress> 或 <input type="range"> 元素，而不是 progressbar 角色。使用者代理會為 <progress> 元素提供一個可樣式化的控制元件，該控制元件基於當前 value 相對於 0（最小值）和 max 值。

示例

在下面的示例中，進度條使用了 aria-valuemin 和 aria-valuemax 的預設值 0 和 100

<div>
  <span id="loadinglabel">Loading:</span>
  <span role="progressbar" aria-labelledby="loadinglabel" aria-valuenow="23">
    <svg width="100" height="10">
      <rect height="10" width="100" stroke="black" fill="black" />
      <rect height="10" width="23" fill="white" />
    </svg>
  </span>
</div>

使用語義化 HTML，這可以寫成

<label for="loadinglabel">Loading:</label>
<progress id="loadinglabel" max="100" value="23"></progress>

最佳實踐

如果進度條描述的是頁面特定區域的載入進度，請包含 aria-describedby 屬性來引用進度條的狀態，並在該區域載入完成之前將其 aria-busy 屬性設定為 true。

優先使用 HTML

建議使用原生的 <progress> 或 <input type="range"> 元素，而不是 progressbar 角色。

規範

另見

• HTML <progress> 元素
• 其他範圍小部件包括
  • meter
  • scrollbar
  • separator (如果可聚焦)
  • slider
  • spinbutton