ElementInternals.ariaAutoComplete — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaAutoComplete

Beschreibung

Die Eigenschaft ariaAutoComplete des ElementInternals-Interfaces gehört zur ARIA-Reflexion für autonome Custom Elements. Damit teilt ein Web Component Hilfstechnologien wie Screenreadern mit, ob eine Eingabe Vorschläge macht und in welcher Form. Die Eigenschaft entspricht dem ARIA-Attribut aria-autocomplete.

Anders als Element.ariaAutoComplete schreibt die Variante auf ElementInternals kein sichtbares Attribut in das DOM. Sie legt nur die Standard-Semantik der Komponente fest. Setzt jemand, der die Komponente verwendet, selbst ein aria-autocomplete-Attribut auf das Host-Element, hat dieses Attribut Vorrang. So bleibt das Markup sauber und lässt sich trotzdem überschreiben.

Erlaubt sind diese Werte:

"inline": Der vorgeschlagene Rest des Textes wird direkt im Eingabefeld eingefügt und markiert.
"list": Vorschläge erscheinen in einer separaten Liste, zum Beispiel einer Listbox.
"both": Kombination aus inline und list.
"none": keine automatische Vervollständigung (Standardverhalten).

Sinnvoll ist die Eigenschaft vor allem zusammen mit internals.role = "combobox", "textbox" oder "searchbox". Den Zugriff auf ElementInternals erhält man über this.attachInternals() im Konstruktor des Custom Elements.

Rückgabewert

Typ

string | null

Beschreibung

Einer der Werte "inline", "list", "both" oder "none", bzw. null, wenn kein Wert gesetzt ist. Beim Schreiben entfernt null die Standard-Semantik wieder.

Beispiele

Custom Combobox mit Vorschlagsliste

class CityPicker extends HTMLElement {
  #internals;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    // Standard-Semantik festlegen, ohne Attribute ins DOM zu schreiben
    this.#internals.role = 'combobox';
    this.#internals.ariaAutoComplete = 'list';
    this.#internals.ariaExpanded = 'false';
  }

  get autoCompleteMode() {
    return this.#internals.ariaAutoComplete;
  }
}

customElements.define('city-picker', CityPicker);

const picker = document.createElement('city-picker');
document.body.append(picker);
console.log(picker.autoCompleteMode);
console.log(picker.hasAttribute('aria-autocomplete'));

list false

Modus zur Laufzeit umschalten

class SmartInput extends HTMLElement {
  static observedAttributes = ['inline-hint'];
  #internals = this.attachInternals();

  connectedCallback() {
    this.#internals.role = 'combobox';
    this.#update();
  }

  attributeChangedCallback() {
    this.#update();
  }

  #update() {
    // Mit Inline-Hinweis: 'both', sonst nur Liste
    this.#internals.ariaAutoComplete =
      this.hasAttribute('inline-hint') ? 'both' : 'list';
    console.log('Modus:', this.#internals.ariaAutoComplete);
  }
}

customElements.define('smart-input', SmartInput);

const el = document.createElement('smart-input');
document.body.append(el);
el.setAttribute('inline-hint', '');

Modus: list Modus: both

Host-Attribut überschreibt die Standard-Semantik

class SearchField extends HTMLElement {
  constructor() {
    super();
    const internals = this.attachInternals();
    internals.role = 'searchbox';
    internals.ariaAutoComplete = 'list';
  }
}

customElements.define('search-field', SearchField);

// Wer die Komponente nutzt, kann den Wert per Attribut überschreiben
document.body.insertAdjacentHTML(
  'beforeend',
  '<search-field aria-autocomplete="none"></search-field>'
);

const field = document.querySelector('search-field');
console.log(field.getAttribute('aria-autocomplete'));
// Der Accessibility-Baum meldet jetzt "none" statt "list"

none

// Wichtig · Fallstricke

Keine Attribut-Reflexion am Host: Wenn man internals.ariaAutoComplete setzt, entsteht kein aria-autocomplete-Attribut. Auch element.ariaAutoComplete auf dem Host liefert weiterhin null. Ein explizit gesetztes Host-Attribut hat immer Vorrang.
Kein Wertvergleich: Der Browser prüft den Wert nicht auf Gültigkeit. Ein Tippfehler wie "lists" wird gespeichert, Hilfstechnologien ignorieren ihn aber. Verwende ausschließlich inline, list, both oder none.
Nur Semantik, kein Verhalten: Die Eigenschaft beschreibt nur, wie sich die Komponente verhält. Die Vervollständigung selbst, die Tastatursteuerung und die Verknüpfung mit der Liste (z. B. über ariaControlsElements oder ariaActiveDescendantElement) musst du selbst umsetzen.
attachInternals() funktioniert nur bei autonomen Custom Elements und nur einmal pro Element. Ein zweiter Aufruf wirft eine NotSupportedError-DOMException.
Kompatibilität: ARIA-Reflexion auf ElementInternals gibt es in Chromium seit Version 81, in Safari seit 16.4 und in Firefox seit 119. Für ältere Browser kannst du mit 'ariaAutoComplete' in ElementInternals.prototype prüfen, ob die Eigenschaft vorhanden ist, und sonst auf setAttribute('aria-autocomplete', …) ausweichen.

Siehe auch

ElementInternals.ariaFlowToElements ElementInternals.ariaAtomic ElementInternals.ariaColCount ElementInternals.ariaMultiLine ElementInternals.ariaPosInSet