ElementInternals.ariaDescribedByElements — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaDescribedByElements

Beschreibung

Mit ariaDescribedByElements legt ein autonomes Custom Element über sein ElementInternals-Objekt fest, welche Elemente es für assistive Technologien wie Screenreader beschreiben. Die Eigenschaft nimmt ein Array von Element-Referenzen entgegen. Deren Textinhalt wird, in der angegebenen Reihenfolge verkettet, als accessible description des Custom Elements angesagt.

Anders als das Attribut aria-describedby erscheint diese Einstellung nicht im DOM. Sie wirkt als Standardsemantik des Elements. Setzt der Nutzer der Komponente selbst aria-describedby oder element.ariaDescribedByElements, hat dieser Wert Vorrang. Die Komponente beschreibt sich also selbst sinnvoll, und Nutzer können das trotzdem überschreiben.

Weil die Eigenschaft direkte Objektreferenzen statt ID-Strings verwendet, braucht das beschreibende Element keine id. Es gelten aber die Regeln der Shadow-DOM-Kapselung: Das referenzierte Element muss im selben Baum liegen wie das Host-Element oder in einem umschließenden (Light-DOM-)Baum. Elemente innerhalb des eigenen Shadow Roots sind aus Sicht des Hosts ebenfalls zulässig, da sie ihm untergeordnet sind.

Beim Lesen erhält man ein eingefrorenes Array der aktuell gültigen Elemente oder null, wenn nichts gesetzt wurde. Mit null entfernt man die Zuordnung wieder.

Parameter

Name	Typ	Default	Beschreibung
$value	Array<Element> \| null	null	Beim Setzen: ein Array von Elementen, deren Text die Beschreibung bildet. Mit `null` entfernt man die Standardbeschreibung.

Rückgabewert

Typ

ReadonlyArray<Element> | null

Beschreibung

Ein eingefrorenes Array der gültigen beschreibenden Elemente oder null, wenn keine gesetzt sind. Elemente, die außerhalb des erlaubten Geltungsbereichs liegen, werden herausgefiltert.

Beispiele

Custom Element mit Beschreibung aus dem eigenen Shadow DOM

class HelpButton extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'button';

    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = `
      <slot></slot>
      <span class="hint" hidden>Öffnet die Hilfe in einem Dialog</span>
    `;

    // Versteckter Hinweistext dient als Standardbeschreibung
    const hint = shadow.querySelector('.hint');
    this.#internals.ariaDescribedByElements = [hint];
  }
  connectedCallback() {
    this.tabIndex = 0;
  }
}
customElements.define('help-button', HelpButton);

// HTML: <help-button>Hilfe</help-button>
// Screenreader: „Hilfe, Schaltfläche, Öffnet die Hilfe in einem Dialog“

Mehrere Beschreibungen kombinieren und auslesen

class PasswordField extends HTMLElement {
  static formAssociated = true;
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'textbox';
    const shadow = this.attachShadow({ mode: 'open' });
    shadow.innerHTML = `
      <div contenteditable="true"></div>
      <p id="rules">Mindestens 12 Zeichen.</p>
      <p id="error"></p>
    `;
    this.rules = shadow.querySelector('#rules');
    this.error = shadow.querySelector('#error');
    this.internals.ariaDescribedByElements = [this.rules];
  }
  showError(msg) {
    this.error.textContent = msg;
    // Reihenfolge = Reihenfolge der Ansage
    this.internals.ariaDescribedByElements = [this.error, this.rules];
  }
}
customElements.define('password-field', PasswordField);

const field = document.createElement('password-field');
document.body.append(field);
field.showError('Passwort zu kurz.');
console.log(field.internals.ariaDescribedByElements.map((el) => el.id));

["error", "rules"]

Beschreibung entfernen und Überschreiben durch den Nutzer

const el = document.querySelector('help-button');

// Nutzer-Attribut hat Vorrang vor der internen Standardsemantik
const note = document.createElement('p');
note.textContent = 'Eigene Beschreibung';
document.body.append(note);
el.ariaDescribedByElements = [note];

// In der Komponente: Standardbeschreibung zurücksetzen
// this.#internals.ariaDescribedByElements = null;
console.log(el.ariaDescribedByElements[0].textContent);

Eigene Beschreibung

// Wichtig · Fallstricke

Browserunterstützung: Safari unterstützt die Eigenschaft seit 16.4, Chromium seit Version 135. In Firefox ist sie noch nicht allgemein verfügbar. Vorher per Feature-Test prüfen: 'ariaDescribedByElements' in ElementInternals.prototype.
Geltungsbereich: Elemente in einem anderen Shadow Root, der nicht dem Host oder einem seiner Vorfahren gehört, werden stillschweigend ignoriert und fehlen im Getter-Ergebnis. Es wird keine Exception geworfen.
Neu zuweisen statt verändern: Das zurückgegebene Array ist eingefroren, push() schlägt fehl. Zum Ändern immer ein neues Array zuweisen.
Keine Attribut-Spiegelung: Anders als bei Element.ariaDescribedByElements entsteht kein aria-describedby-Attribut im DOM. In den DevTools ist die Zuordnung nur im Barrierefreiheitsbaum sichtbar.
attachInternals() funktioniert nur bei autonomen Custom Elements und darf pro Element nur einmal aufgerufen werden.
Die Beschreibung ist eine Ergänzung. Für den eigentlichen Namen eines Elements ariaLabelledByElements verwenden.

Siehe auch

ElementInternals.ariaDetailsElements ElementInternals.ariaLabelledByElements ElementInternals.ariaControlsElements ElementInternals.ariaErrorMessageElements ElementInternals.ariaFlowToElements