Element.ariaOwnsElements — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaOwnsElements

Beschreibung

Die Eigenschaft ariaOwnsElements ist das elementbasierte Gegenstück zum HTML-Attribut aria-owns. Sie enthält ein Array von Element-Objekten, die Hilfstechnologien wie Screenreader als Kinder des aktuellen Elements behandeln sollen, obwohl sie im DOM an einer anderen Stelle stehen. Die Beziehung kann visuell, funktional oder kontextuell sein.

Man braucht das vor allem, wenn sich die logische Struktur nicht im DOM abbilden lässt. Das kommt etwa bei Popups, Menüs oder Listboxen vor, die aus Layout-Gründen am Ende von <body> eingefügt werden, zum Beispiel über ein Portal in React oder Vue. Anders als beim Attribut übergibt man hier direkt Element-Referenzen statt einer durch Leerzeichen getrennten ID-Liste. Die Zielelemente brauchen deshalb keine id.

Beim Lesen bekommt man ein eingefrorenes Array (oder null). Das Array kann man nicht verändern, sondern nur die ganze Eigenschaft neu zuweisen. Wenn man die Eigenschaft setzt, wird das Attribut aria-owns auf einen leeren String gesetzt. Setzt man stattdessen das Attribut, verwirft der Browser die zuvor zugewiesenen Element-Referenzen. Liefert nur das Attribut die Beziehung, gibt die Eigenschaft die über die IDs gefundenen Elemente zurück.

Ein Element sollte nur ein einziges „Besitzer“-Element haben. Außerdem sollte aria-owns nur für Beziehungen verwendet werden, die sich nicht über die DOM-Hierarchie ausdrücken lassen.

Rückgabewert

Typ

Element[] | null

Beschreibung

Eingefrorenes Array der „besessenen“ Elemente oder null, wenn keine Beziehung gesetzt ist. Beim Setzen sind ein Array von Element-Objekten oder null erlaubt. null entfernt die Beziehung.

Beispiele

Beziehung aus dem Attribut auslesen

// HTML:
// <div id="tree" role="tree" aria-owns="branch1 branch2"></div>
// <div id="branch1" role="treeitem">Zweig 1</div>
// <div id="branch2" role="treeitem">Zweig 2</div>
const tree = document.getElementById('tree');
console.log(tree.getAttribute('aria-owns'));
console.log(tree.ariaOwnsElements?.map((el) => el.id));

branch1 branch2 ["branch1", "branch2"]

Popup aus einem Portal dem Menü-Button zuordnen

const button = document.querySelector('#menu-button');

// Menü wird aus Layout-Gründen direkt in <body> eingefügt
const menu = document.createElement('ul');
menu.setAttribute('role', 'menu');
menu.innerHTML = '<li role="menuitem">Öffnen</li><li role="menuitem">Speichern</li>';
document.body.append(menu);

if ('ariaOwnsElements' in Element.prototype) {
  // Keine ID nötig – direkte Element-Referenz
  button.ariaOwnsElements = [menu];
} else {
  // Fallback über das Attribut
  menu.id ||= 'menu-' + crypto.randomUUID();
  button.setAttribute('aria-owns', menu.id);
}

console.log(button.ariaOwnsElements?.length);

1

Beziehung ändern und entfernen

const owner = document.querySelector('#listbox');
const a = document.querySelector('#option-a');
const b = document.querySelector('#option-b');

owner.ariaOwnsElements = [a];
// Das Array ist eingefroren – push() wirft einen TypeError.
// Deshalb die ganze Eigenschaft neu zuweisen:
owner.ariaOwnsElements = [...owner.ariaOwnsElements, b];
console.log(owner.ariaOwnsElements.length);

// Beziehung komplett entfernen
owner.ariaOwnsElements = null;
console.log(owner.ariaOwnsElements);

2 null

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Eigenschaft ist relativ neu (Teil von „ARIA reflection“ mit Element-Referenzen). Vor der Nutzung mit 'ariaOwnsElements' in Element.prototype prüfen und notfalls auf das Attribut aria-owns zurückfallen.
Eingefrorenes Array: Methoden wie push() oder splice() auf dem zurückgegebenen Array funktionieren nicht. Änderungen immer durch Neuzuweisung vornehmen.
Shadow DOM: Referenzierte Elemente müssen im selben oder in einem übergeordneten Scope liegen. Referenzen in einen tieferen Shadow Root hinein werden beim Lesen herausgefiltert.
Attribut und Eigenschaft überschreiben sich gegenseitig: Wird aria-owns per setAttribute() gesetzt, gehen die explizit zugewiesenen Element-Referenzen verloren.
Barrierefreiheit: Die Beziehung verändert die Reihenfolge im Barrierefreiheitsbaum, aber nicht die Tab-Reihenfolge. Ein Element darf nur von einem einzigen Element „besessen“ werden. Mehrfachzuordnungen und Zyklen führen zu undefiniertem Verhalten. Wo es möglich ist, sollte man stattdessen die DOM-Struktur anpassen.
Die Eigenschaft ist nicht zu verwechseln mit ariaControlsElements: „controls“ bedeutet Steuerung, „owns“ eine Eltern-Kind-Beziehung.

Siehe auch

Element Element.ariaDetailsElements Element.ariaFlowToElements Element.ariaControlsElements Element.ariaRelevant