Element: ariaControlsElements 属性

基准线 2025

新推出

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

Element 接口的 ariaControlsElements 属性是一个数组，其中包含由应用此属性的元素所控制的元素。例如，这可以设置在 combobox 上，以指示它弹出的元素，或者设置在 scrollbar 上，以指示它控制的元素的 ID。

有关如何使用该属性和特性的更多信息，请参阅 aria-controls 主题。

值

一个 HTMLElement 的子类数组，表示由该元素控制的元素。

读取时，返回的数组是静态的且只读的。写入时，会复制分配的数组：后续对数组的更改不会影响该属性的值。

描述

该属性是使用 aria-controls 属性设置被控制元素的灵活替代方案。与 aria-controls 不同，分配给此属性的元素不必具有 id 属性。

当 aria-controls 属性定义时，该属性会反映它，但仅限于列出的、与有效的范围内元素匹配的 ID 值。如果设置了该属性，则相应的属性将被清除。有关反映的元素引用和范围的更多信息，请参阅 _Reflected attributes_ 指南中的 Reflected element references。

示例

获取被控制的元素

此示例显示了如何使用 ariaControlsElements 来获取使用 aria-controls 设置的被控制元素。

HTML

HTML 首先定义了一个 <button> 元素和两个它所控制的 <div> 元素，panel1 和 panel2。对被控制面板的引用列在按钮的 aria-controls 属性中。

html

<button id="toggleButton" aria-controls="panel1 panel2" aria-expanded="false">
  Show Details
</button>

<div class="panel" id="panel1" aria-hidden="true">
  <p>Panel1 opened/closed by button.</p>
</div>

<div class="panel" id="panel2" aria-hidden="true">
  <p>Panel2 opened/closed by button.</p>
</div>

css

.panel {
  display: none; /* Initially hidden */
  border: 1px solid #cccccc;
  padding: 5px;
  margin-top: 5px;
}

<pre id="log"></pre>

#log {
  height: 70px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

JavaScript

代码首先根据按钮的 aria-expanded 属性来设置面板的打开或隐藏。

const logElement = document.querySelector("#log");
function log(text) {
  logElement.innerText = `${logElement.innerText}${text}\n`;
  logElement.scrollTop = logElement.scrollHeight;
}

const toggleButton = document.querySelector("#toggleButton");
const panel1 = document.querySelector("#panel1");
const panel2 = document.querySelector("#panel2");

toggleButton.addEventListener("click", () => {
  const isExpanded = toggleButton.getAttribute("aria-expanded") === "true";

  toggleButton.setAttribute("aria-expanded", !isExpanded);
  panel1.style.display = isExpanded ? "none" : "block";
  panel1.setAttribute("aria-hidden", isExpanded); // true when hidden, false when shown.

  panel2.style.display = isExpanded ? "none" : "block";
  panel2.setAttribute("aria-hidden", isExpanded); // true when hidden, false when shown.
});

接下来，示例使用 Element.getAttribute() 获取 aria-controls 属性的值（一个列出被引用元素 ID 的字符串）。然后，它检查 ariaControlsElements 属性是否受支持，如果支持，则记录其值。最后，它返回并记录每个被控制元素的内部文本。

log(`aria-controls: ${toggleButton.getAttribute("aria-controls")}`);
// Feature test for ariaControlsElements
if ("ariaControlsElements" in Element.prototype) {
  // Get ariaControlsElements
  const controlledElements = toggleButton.ariaControlsElements;
  log(`ariaControlsElements: ${controlledElements}`);

  // List innerText for each of the ariaControlsElements
  controlledElements.forEach((controlled) => {
    log(` Controlled element text: ${controlled.textContent.trim()}`);
  });
} else {
  log("element.ariaControlsElements: not supported by browser");
}

结果

点击下面的按钮来显示和隐藏面板。日志显示原始元素引用、关联/返回的元素以及每个元素的内部文本。

规范

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

浏览器兼容性

另见

aria-controls 属性
ElementInternals.ariaControlsElements
Attribute reflection 指南中的 Reflected element references

帮助改进 MDN

了解如何贡献

此页面最后修改于 ⁨2025年8月12日⁩，由 MDN contributors 贡献。

在 GitHub 上查看此页面 • 报告此内容的错误