Element: ariaDescribedByElements 屬性

基準線 2025
新推出

自 ⁨2025 年 4 月⁩起,此功能適用於最新裝置和瀏覽器版本。此功能可能不適用於較舊的裝置或瀏覽器。

Element 介面的 ariaDescribedByElements 屬性是一個數組,其中包含為應用該屬性的元素提供可訪問描述的元素。可訪問描述類似於可訪問標籤(請參閱 ariaLabelledByElements),但提供的資訊更詳細。

aria-describedby 主題包含有關如何使用該屬性和特性的附加資訊。

HTMLElement 的子類的陣列。這些元素的內部文字可以與空格連線起來,以獲得可訪問的描述。

讀取時,返回的陣列是靜態的且只讀的。寫入時,將複製分配的陣列:之後對陣列的更改不會影響屬性的值。

描述

該屬性是使用 aria-describedby 屬性設定可訪問描述的一種靈活替代方法。與 aria-describedby 不同,分配給此屬性的元素不必具有 id 屬性。

aria-describedby 屬性被定義時,該屬性會反映元素的該屬性,但僅限於列出的、匹配有效作用域內元素的引用 id 值。如果設定了該屬性,則相應的屬性將被清除。有關反射的元素引用和作用域的更多資訊,請參閱反射屬性指南中的 反射的元素引用

示例

獲取可訪問描述

此示例展示瞭如何使用 ariaDescribedByElements 來獲取使用 aria-describedby 定義的可訪問描述。

HTML

HTML 定義了兩個 <span> 元素,並在 <button>aria-describedby 屬性中引用了它們的 id。

html
<button aria-describedby="trash-desc1 trash-desc2">Move to trash</button>
…
<span id="trash-desc1">Trash will be permanently removed after 30 days.</span>
<span id="trash-desc2">Or Else!</span>

CSS

在這裡,我們只需隱藏包含可訪問文字的 <span> 元素。

css
span {
  display: none;
}

JavaScript

下面的程式碼首先使用 Element.getAttribute() 記錄 aria-describedby 屬性的值(一個列出被引用元素 id 值的字串)。然後,它檢查 ariaDescribedByElements 是否受支援,如果支援,則記錄其值。最後,它透過迭代返回的元素並連線它們的內部文字來計算並返回可訪問字串。

js
const buttonElement = document.querySelector("button");
log(`aria-describedby: ${buttonElement.getAttribute("aria-describedby")}`);
// Feature test for ariaDescribedByElements
if ("ariaDescribedByElements" in Element.prototype) {
  // Get ariaDescribedByElements
  const buttonElements = buttonElement.ariaDescribedByElements;
  log(`ariaDescribedByElements: ${buttonElements}`);

  // Accessible description from the elements
  const text = buttonElements.map((e) => e.textContent.trim()).join(" ");
  log(`Accessible description: ${text.trim()}`);
} else {
  log("element.ariaDescribedByElements: not supported by browser");
}

結果

下面的日誌顯示了原始元素引用、關聯/返回的元素以及可訪問描述。

規範

規範
無障礙富網際網路應用程式 (WAI-ARIA)
# dom-ariamixin-ariadescribedbyelements

瀏覽器相容性

另見