ElementInternals.ariaErrorMessageElements — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaErrorMessageElements

Beschreibung

Die Eigenschaft ariaErrorMessageElements des ElementInternals-Interfaces legt fest, welche Elemente die Fehlermeldung für ein autonomes Custom Element enthalten. Sie ist das Gegenstück zum Attribut aria-errormessage. Statt ID-Referenzen als Zeichenkette erwartet sie aber direkte Referenzen auf Elementobjekte in einem Array.

Die Werte, die über ElementInternals gesetzt werden, sind Standardsemantik des Elements. Sie erscheinen nicht als Attribut im DOM. Setzt ein Seitenautor am Host-Element selbst aria-errormessage oder ariaErrorMessageElements, hat dieser Wert Vorrang. So kann eine Komponente ein sinnvolles Standardverhalten mitbringen, das sich trotzdem überschreiben lässt.

Gedacht ist die Eigenschaft für formularähnliche Custom Elements, also Komponenten mit static formAssociated = true und eigener Validierung. Assistive Technologien lesen die referenzierte Fehlermeldung nur vor, wenn das Element gleichzeitig als ungültig markiert ist, z. B. über internals.ariaInvalid = "true".

Ein großer Vorteil der Elementreferenzen: Sie funktionieren in bestimmten Fällen auch über Shadow-DOM-Grenzen hinweg. ID-Referenzen können das nicht. Ein referenziertes Element muss dabei im selben Baum wie das Host-Element liegen oder in einem übergeordneten Baum (Light DOM bzw. Dokument). Elemente aus dem eigenen Shadow Root werden beim Auslesen nicht zurückgegeben.

Parameter

Name	Typ	Default	Beschreibung
$value	Array<Element> \| null	null	Beim Setzen: Array der Elemente mit der Fehlermeldung. `null` entfernt die Standardzuordnung.

Rückgabewert

Typ

Array<Element> | null

Beschreibung

Ein eingefrorenes Array der gültig referenzierten Elemente oder null, wenn nichts gesetzt ist. Nicht erreichbare Elemente (z. B. aus einem tieferen Shadow Root) werden herausgefiltert.

Beispiele

Fehlermeldung aus dem Light DOM zuordnen

class RatingInput extends HTMLElement {
  static formAssociated = true;
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'spinbutton';
  }

  connectedCallback() {
    // Das Fehler-Element steht im Dokument neben der Komponente
    const errorEl = document.getElementById(this.getAttribute('error-id'));
    if (errorEl) {
      this.#internals.ariaErrorMessageElements = [errorEl];
    }
  }

  setError(message) {
    const [errorEl] = this.#internals.ariaErrorMessageElements ?? [];
    if (errorEl) errorEl.textContent = message;
    this.#internals.ariaInvalid = message ? 'true' : 'false';
    this.#internals.setValidity(message ? { customError: true } : {}, message);
  }
}

customElements.define('rating-input', RatingInput);

// HTML: <rating-input error-id="rating-error"></rating-input>
//       <p id="rating-error"></p>
const el = document.querySelector('rating-input');
el.setError('Bitte eine Bewertung zwischen 1 und 5 wählen.');
console.log(document.getElementById('rating-error').textContent);

Bitte eine Bewertung zwischen 1 und 5 wählen.

Wert auslesen und zurücksetzen

class MyField extends HTMLElement {
  constructor() {
    super();
    this.internals = this.attachInternals();
  }
}
customElements.define('my-field', MyField);

const field = document.createElement('my-field');
const hint = document.createElement('span');
hint.id = 'field-error';
document.body.append(field, hint);

field.internals.ariaErrorMessageElements = [hint];
console.log(field.internals.ariaErrorMessageElements.map((e) => e.id));

// Standardzuordnung wieder entfernen
field.internals.ariaErrorMessageElements = null;
console.log(field.internals.ariaErrorMessageElements);

["field-error"] null

Autor überschreibt den Standardwert

// Ausgehend vom vorherigen Beispiel: Komponente mit Standardzuordnung
const field = document.querySelector('my-field');
const custom = document.createElement('div');
custom.textContent = 'Eigene Fehlermeldung';
document.body.append(custom);

// Eigenschaft am Host-Element hat Vorrang vor ElementInternals
field.ariaErrorMessageElements = [custom];
console.log(field.ariaErrorMessageElements[0].textContent);

Eigene Fehlermeldung

// Wichtig · Fallstricke

Nur zusammen mit ariaInvalid wirksam: Screenreader kündigen die Fehlermeldung nur an, wenn das Element als ungültig gilt (ariaInvalid = "true").
Keine Attribut-Spiegelung: Anders als Element.ariaErrorMessageElements erzeugt der Wert kein aria-errormessage-Attribut im DOM. In den DevTools sieht man ihn nur im Barrierefreiheitsbaum.
Shadow-DOM-Grenzen: Elemente aus dem eigenen Shadow Root der Komponente werden beim Auslesen herausgefiltert. Fehlertexte innerhalb der Komponente verknüpft man besser direkt an einem inneren Element mit aria-errormessage oder aria-describedby.
Neues Array zuweisen: Das zurückgegebene Array ist eingefroren. Ein push() wirft deshalb im strikten Modus einen TypeError. Zum Ändern immer ein neues Array zuweisen.
Unterstützung durch Screenreader: aria-errormessage wird uneinheitlich unterstützt. Als Rückfalllösung zusätzlich ariaDescribedByElements oder eine Live-Region verwenden.
Browserunterstützung: Die Eigenschaft ist erst seit Kurzem in allen großen Browsern verfügbar (Safari früher, Chromium ab 135, Firefox ab 136). Vorher per 'ariaErrorMessageElements' in ElementInternals.prototype prüfen.

Siehe auch

ElementInternals.ariaLabel ElementInternals.ariaControlsElements ElementInternals.ariaOwnsElements ElementInternals.ariaDescribedByElements ElementInternals.ariaDetailsElements