Element: ariaControlsElements-Eigenschaft

Baseline 2025
Newly available

Since April 2025, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

Die ariaControlsElements-Eigenschaft der Element-Schnittstelle ist ein Array, das die Elemente enthält, die von dem Element gesteuert werden, auf das sie angewendet wird. Zum Beispiel kann dies auf einer Combobox gesetzt werden, um anzuzeigen, welches Element sie öffnet, oder auf einem Scrollbar, um die ID des Elements anzugeben, das sie steuert.

Das Thema aria-controls enthält zusätzliche Informationen darüber, wie das Attribut und die Eigenschaft verwendet werden sollten.

Wert

Ein Array von Unterklassen von HTMLElement, das die von diesem Element gesteuerten Elemente darstellt.

Beim Lesen ist das zurückgegebene Array statisch und schreibgeschützt. Beim Schreiben wird das zugewiesene Array kopiert: Nachfolgende Änderungen am Array beeinflussen den Wert der Eigenschaft nicht.

Beschreibung

Die Eigenschaft ist eine flexible Alternative zur Verwendung des aria-controls-Attributs, um die gesteuerten Elemente festzulegen. Im Gegensatz zu aria-controls müssen die dieser Eigenschaft zugewiesenen Elemente kein id-Attribut haben.

Die Eigenschaft spiegelt das aria-controls-Attribut wider, wenn es definiert ist, jedoch nur für aufgelistete Referenz-id-Werte, die mit gültigen In-Scope-Elementen übereinstimmen. Wenn die Eigenschaft festgelegt ist, wird das entsprechende Attribut gelöscht. Weitere Informationen zu reflektierten Elementreferenzen und dem Umfang finden Sie unter Reflected element references im Reflected attributes-Leitfaden.

Beispiele

Die gesteuerten Elemente abrufen

Dieses Beispiel zeigt, wie ariaControlsElements verwendet werden kann, um die gesteuerten Elemente abzurufen, die mit aria-controls festgelegt wurden.

HTML

Das HTML definiert zuerst ein

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

JavaScript

Der Code richtet zunächst die Panels so ein, dass sie basierend auf dem aria-expanded-Attribut des Buttons geöffnet oder ausgeblendet werden.

js
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.
});

Als Nächstes holt das Beispiel den Wert des aria-controls-Attributs mit Element.getAttribute() (ein String, der die id-Werte der referenzierten Elemente auflistet). Es prüft dann, ob die ariaControlsElements-Eigenschaft unterstützt wird, und wenn ja, protokolliert es ihren Wert. Schließlich gibt es den inneren Text für jedes der gesteuerten Elemente zurück und protokolliert diesen.

js
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");
}

Ergebnis

Klicken Sie auf den Button unten, um die Panels anzuzeigen und auszublenden. Das Protokoll zeigt die ursprünglichen Elementreferenzen, die zugeordneten/zurückgegebenen Elemente und den inneren Text jedes Elements.