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

浏览器兼容性

另见