Element.ariaDescribedByElements — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaDescribedByElements

Beschreibung

Die Eigenschaft ariaDescribedByElements gehört zur ARIA-Reflexion von Element. Sie enthält die Elemente, deren Textinhalt Hilfstechnologien (z. B. Screenreadern) als Beschreibung vorlesen. Das sind zusätzliche Hinweise, die nach dem barrierefreien Namen kommen, etwa Formathinweise oder Fehlermeldungen zu einem Eingabefeld.

Anders als das Attribut aria-describedby, das eine durch Leerzeichen getrennte Liste von IDs erwartet, arbeitet diese Eigenschaft direkt mit Elementobjekten. Die beschreibenden Elemente brauchen also keine id. Das hilft besonders bei dynamisch erzeugtem Markup, in Komponenten-Bibliotheken und bei Web Components, wo eindeutige IDs schwer zu garantieren sind.

Beim Lesen gilt: Ist nichts explizit gesetzt, löst der Browser die IDs aus aria-describedby auf und gibt die passenden Elemente zurück. Fehlt das Attribut, ist das Ergebnis null. Wenn Sie ein Array zuweisen, setzt der Browser das Attribut auf einen leeren String. Die Referenzen werden intern gespeichert und nicht als IDs ins Attribut geschrieben. Wenn Sie null zuweisen, entfernt der Browser das Attribut.

Ein Element kann auch aus einem Shadow Root heraus auf Elemente in einem übergeordneten Baum (z. B. dem Dokument) verweisen. Umgekehrt geht das nicht: Elemente innerhalb eines tieferen Shadow Roots sind nicht erreichbar. Solche ungültigen Referenzen filtert der Getter heraus.

Parameter

Name	Typ	Default	Beschreibung
$value	Array<Element> \| null	null	Wert beim Setzen: ein Array von Elementen, die das Element beschreiben. Mit `null` entfernen Sie die Zuordnung und das Attribut `aria-describedby`.

Rückgabewert

Typ

ReadonlyArray<Element> | null

Beschreibung

Ein eingefrorenes Array der beschreibenden Elemente in der angegebenen Reihenfolge, oder null, wenn keine Beschreibung zugeordnet ist. Solange sich der Inhalt nicht ändert, liefert der Getter dasselbe Array-Objekt.

Beispiele

Hinweistext an ein Passwortfeld hängen (ohne IDs)

// Markup: <input type="password" class="pw"> <p class="pw-hint">Mindestens 12 Zeichen.</p>
const input = document.querySelector('.pw');
const hint = document.querySelector('.pw-hint');

input.ariaDescribedByElements = [hint];

console.log(input.ariaDescribedByElements[0] === hint);
console.log(JSON.stringify(input.getAttribute('aria-describedby')));

true ""

Vorhandenes aria-describedby-Attribut auslesen

// Markup:
// <button id="del" aria-describedby="warn info">Löschen</button>
// <span id="warn">Nicht rückgängig zu machen.</span>
// <span id="info">Betrifft alle Dateien.</span>
const button = document.getElementById('del');

const texts = (button.ariaDescribedByElements ?? [])
  .map((el) => el.textContent.trim());

console.log(texts);

["Nicht rückgängig zu machen.", "Betrifft alle Dateien."]

Fehlermeldung bei der Validierung dynamisch ergänzen

const field = document.querySelector('#email');
const hint = document.querySelector('#email-hint');

const showError = (message) => {
  const error = document.createElement('p');
  error.className = 'error';
  error.textContent = message;
  field.after(error);
  // Das Array ist eingefroren, deshalb ein neues Array zuweisen
  field.ariaDescribedByElements = [hint, error];
  field.ariaInvalid = 'true';
};

const clearError = () => {
  field.nextElementSibling?.classList.contains('error') && field.nextElementSibling.remove();
  field.ariaDescribedByElements = [hint];
  field.ariaInvalid = 'false';
};

field.addEventListener('blur', () => {
  clearError();
  if (!field.validity.valid) showError('Bitte eine gültige E-Mail-Adresse eingeben.');
});

Feature-Erkennung mit Fallback auf IDs

const describe = (target, ...descriptions) => {
  if ('ariaDescribedByElements' in Element.prototype) {
    target.ariaDescribedByElements = descriptions;
  } else {
    const ids = descriptions.map((el) => {
      el.id ||= `desc-${crypto.randomUUID()}`;
      return el.id;
    });
    target.setAttribute('aria-describedby', ids.join(' '));
  }
};

describe(document.querySelector('#save'), document.querySelector('.save-hint'));

// Wichtig · Fallstricke

Browser-Kompatibilität: Safari unterstützt die Eigenschaft ab 16.4, Chromium ab 135 und Firefox ab 136. Für ältere Browser prüfen Sie mit 'ariaDescribedByElements' in Element.prototype und fallen auf aria-describedby mit IDs zurück.
Das Array ist eingefroren: el.ariaDescribedByElements.push(x) wirft einen TypeError. Weisen Sie immer ein neues Array zu, z. B. el.ariaDescribedByElements = [...(el.ariaDescribedByElements ?? []), x].
Attribut wird nicht synchronisiert: Nach dem Setzen enthält aria-describedby nur einen leeren String und keine IDs. Code oder CSS-Selektoren, die IDs im Attribut erwarten (z. B. [aria-describedby~=\"hint\"]), greifen dann nicht mehr. Wenn Sie das Attribut später per setAttribute() ändern, verwirft der Browser die explizit gesetzten Referenzen.
Shadow-DOM-Grenzen: Referenzen sind nur auf Elemente im selben Baum oder in einem übergeordneten Baum gültig. Elemente in einem tieferen Shadow Root blendet der Getter aus.
Getrennte Elemente: Ist ein referenziertes Element nicht mehr im Dokument, liefert der Getter es nicht zurück. Hängen Sie es wieder ein, taucht es erneut auf, denn die Referenz selbst bleibt (schwach) gespeichert.
Die Beschreibung ist ein Zusatz und ersetzt keinen barrierefreien Namen. Für den Namen verwenden Sie ariaLabelledByElements oder ein <label>.

Siehe auch

Element.ariaLabelledByElements Element.ariaDescription Element.ariaErrorMessageElements Element.ariaControlsElements ElementInternals Element.setAttribute() Element.ariaActiveDescendantElement