大网数据广告活动
Web 标准与前端开发

Element:ariaControlsElements 属性

· 52CE 我爱测

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

DOM

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

aria-controls 主题包含关于应当如何使用 HTML 属性(attribute)和接口属性(property)的更多信息。

值

一个由 HTMLElement 的子类组成的数组,表示由此元素控制的元素。

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

描述

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

当定义了 aria-controls 属性时,该属性会反映这个 HTML 属性,但仅限与有效作用域内元素匹配的已列出的引用 id 值。如果设置了该属性,则相应的特性会被清除。有关反射元素引用和作用域的更多信息,请参见反射属性指南中的反射的元素引用。

示例

获取受控元素

此示例演示如何使用 ariaControlsElements 获取通过 aria-controls 设置的受控元素。

HTML

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

<button id="toggleButton" aria-controls="panel1 panel2" aria-expanded="false">
  展示详情
</button>

<div class="panel" id="panel1" aria-hidden="true">
  <p>面板 1 可通过按钮打开/关闭。</p>
</div>

<div class="panel" id="panel2" aria-hidden="true">
  <p>面板 2 可通过按钮打开/关闭。</p>
</div>
.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,展示时为 false。

  panel2.style.display = isExpanded ? "none" : "block";
  panel2.setAttribute("aria-hidden", isExpanded); // 隐藏时为 true,展示时为 false。
});

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

log(`aria-controls:${toggleButton.getAttribute("aria-controls")}`);
// ariaControlsElements 特性检测
if ("ariaControlsElements" in Element.prototype) {
  // 获取 ariaControlsElements
  const controlledElements = toggleButton.ariaControlsElements;
  log(`ariaControlsElements:${controlledElements}`);

  // 列出每一个 ariaControlsElements 的 innerText
  controlledElements.forEach((controlled) => {
    log(` 受控元素文本:${controlled.textContent.trim()}`);
  });
} else {
  log("element.ariaControlsElements:不被浏览器支持");
}

结果

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

Get the controlled elements

规范

浏览器兼容性

参见

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。