Element.ariaDetailsElements — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaDetailsElements

Beschreibung

Die Eigenschaft ariaDetailsElements gehört zur ARIA-Reflexion von Elementreferenzen. Sie spiegelt das Attribut aria-details wider. Dort stehen normalerweise ID-Werte, die durch Leerzeichen getrennt sind. Die Eigenschaft arbeitet stattdessen direkt mit Element-Objekten. Assistive Technologien wie Screenreader erkennen darüber, dass es zu einem Element weiterführende Informationen gibt, etwa eine ausführliche Bildbeschreibung, einen Kommentar oder eine Fußnote.

Im Unterschied zu aria-describedby wird der Inhalt bei aria-details nicht zu einem flachen Beschreibungstext zusammengefasst. Die Nutzer können zu den verknüpften Elementen navigieren. Dadurch dürfen die Details strukturiert sein und Listen, Tabellen oder Links enthalten.

Der Vorteil gegenüber dem Attribut: Die verknüpften Elemente brauchen keine id. Außerdem darf ein Element in einem Shadow Root auf Elemente im umgebenden Light DOM verweisen, also in einem übergeordneten Baum. Das ist in Web Components praktisch, weil ID-Verweise dort nicht über Baumgrenzen hinweg funktionieren.

Beim Lesen wird entweder ein Array der referenzierten Elemente zurückgegeben oder null, wenn keine Verknüpfung besteht. Steht im Attribut aria-details eine Liste von IDs, löst der Getter diese zu Elementen auf. Wenn Sie Elemente zuweisen, wird das Inhaltsattribut auf einen leeren String gesetzt. Wenn Sie null zuweisen, wird es entfernt.

Parameter

Name	Typ	Default	Beschreibung
$value	Array<Element> \| null	null	Nur beim Setzen: Array der Elemente, die die Details liefern. `null` entfernt die Verknüpfung und das Attribut `aria-details`.

Rückgabewert

Typ

Array<Element> | null

Beschreibung

Ein eingefrorenes Array der aktuell gültigen Detail-Elemente oder null, wenn keine Verknüpfung gesetzt ist. Elemente, die nicht gültig sind, etwa weil sie in einem tieferliegenden Shadow Root liegen, werden herausgefiltert.

Beispiele

Bild mit ausführlicher Beschreibung verknüpfen

// HTML: <img id="chart" src="umsatz.png" alt="Umsatzdiagramm 2024">
//       <section class="chart-details">…ausführliche Tabelle…</section>
const img = document.querySelector('#chart');
const details = document.querySelector('.chart-details');

// Keine id am Detail-Element nötig
img.ariaDetailsElements = [details];

console.log(img.ariaDetailsElements[0] === details);
console.log(img.getAttribute('aria-details'));

true ""

Vorhandenes aria-details-Attribut auslesen

// HTML: <button aria-details="hinweis1 hinweis2">Löschen</button>
//       <div id="hinweis1">Kann nicht rückgängig gemacht werden.</div>
//       <div id="hinweis2">Betrifft alle Unterordner.</div>
const btn = document.querySelector('button');

const ids = btn.ariaDetailsElements?.map((el) => el.id) ?? [];
console.log(ids);

["hinweis1", "hinweis2"]

Web Component verweist auf Light-DOM-Kommentar

class ReviewField extends HTMLElement {
  constructor() {
    super();
    const root = this.attachShadow({ mode: 'open' });
    root.innerHTML = '<textarea aria-label="Text"></textarea>';
  }
  connectedCallback() {
    const textarea = this.shadowRoot.querySelector('textarea');
    // Referenz über die Shadow-Grenze hinweg in den Light DOM
    const comment = document.querySelector(this.getAttribute('details-for'));
    if (comment && 'ariaDetailsElements' in Element.prototype) {
      textarea.ariaDetailsElements = [comment];
    }
  }
}
customElements.define('review-field', ReviewField);

Verknüpfung wieder entfernen

const img = document.querySelector('#chart');
img.ariaDetailsElements = null;

console.log(img.ariaDetailsElements);
console.log(img.hasAttribute('aria-details'));

null false

// Wichtig · Fallstricke

Kompatibilität: Die ARIA-Reflexion von Elementreferenzen ist relativ neu. Ältere Browser kennen die Eigenschaft nicht. Prüfen Sie deshalb vorher mit 'ariaDetailsElements' in Element.prototype und setzen Sie andernfalls das Attribut aria-details mit IDs.
Eingefrorenes Array: Das zurückgegebene Array lässt sich nicht verändern. Ein push() auf das Ergebnis löst einen Fehler aus. Weisen Sie stattdessen ein neues Array zu, zum Beispiel el.ariaDetailsElements = [...(el.ariaDetailsElements ?? []), neu].
Shadow DOM: Verweise sind nur auf Elemente im selben Baum oder in einem übergeordneten Baum gültig. Verweise in einen verschachtelten Shadow Root hinein werden beim Lesen herausgefiltert.
Attribut und Eigenschaft gemischt: Nach dem Setzen über die Eigenschaft steht aria-details auf "". Die ID-Liste ist dann nicht mehr sichtbar. Wird das Attribut später per setAttribute() überschrieben, gelten wieder die IDs.
Unterstützung durch Screenreader: Wie gut aria-details angekündigt wird, hängt vom Screenreader ab. Für kurze Texte ist aria-describedby oft zuverlässiger.

Siehe auch

Element.ariaFlowToElements Element.ariaControlsElements Element.ariaOwnsElements Element.ariaDescribedByElements Element.ariaBrailleLabel