Element: ariaDetailsElements 属性

基准线 2025
新推出

自 ⁨2025 年 4 月⁩起,此功能适用于最新设备和浏览器版本。此功能可能不适用于较旧的设备或浏览器。

Element 接口的 ariaDetailsElements 属性是一个数组,其中包含为应用该属性的元素提供可访问详细信息的元素。可访问详细信息类似于可访问描述(参见 ariaDescribedByElements),但提供了更冗长的信息。

关于此属性和相关 ARIA 属性应如何使用的其他信息,请参见 aria-details 主题。

一个 HTMLElement 的子类的数组。这些元素的内部文本可以与空格连接起来,以获得可访问的详细信息。

读取时,返回的数组是静态的且只读的。写入时,将复制分配的数组:之后对数组的更改不会影响属性的值。

描述

此属性是使用 aria-details 属性设置可访问详细信息的一种灵活替代方案。与 aria-details 不同,分配给此属性的元素不必具有 id 属性。

aria-details 属性定义并匹配有效的范围内元素时,此属性将反映该属性,但仅限于列出的引用 id 值。如果设置了此属性,则相应的属性将被清除。有关反映的元素引用和范围的更多信息,请参阅Reflected attributes 指南中的 Reflected element references

示例

获取可访问的详细信息

本示例演示了如何使用 ariaDetailsElements 来获取使用 HTML 中的 aria-details 属性定义的有关信息。

HTML

HTML 定义了两个 <span> 元素,并在 <button>aria-details 属性中引用了它们的 id。

html
<button aria-details="details1 details2">Button text</button>
…
<span id="details1">Details 1 information about the element.</span>
<span id="details2">Details 2 information about the element.</span>

JavaScript

下面的代码首先通过 Element.getAttribute()(一个列出被引用元素 id 值的字符串)记录 aria-details 属性的值。然后,它检查 ariaDetailsElements 是否受支持,如果受支持,则记录其值。最后,它通过遍历返回的元素并连接它们的内部文本来计算并返回可访问字符串。

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

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

结果

下面的日志显示了原始元素引用、关联/返回的元素以及可访问的详细信息。

规范

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

浏览器兼容性

另见