ElementInternals.ariaHasPopup — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaHasPopup

Beschreibung

Die Eigenschaft ariaHasPopup des ElementInternals-Interfaces entspricht dem ARIA-Attribut aria-haspopup. Sie teilt assistiven Technologien wie Screenreadern mit, dass ein Element ein interaktives Popup öffnen kann, und gibt dessen Typ an: "menu", "listbox", "tree", "grid" oder "dialog". Mit "true" ist ein Menü gemeint, mit "false" gibt es kein Popup.

Im Unterschied zu Element.ariaHasPopup bzw. dem HTML-Attribut ändert ElementInternals.ariaHasPopup das DOM nicht. Der Wert gilt nur als Standardsemantik des Custom Elements. Setzt die Person, die die Komponente verwendet, selbst ein aria-haspopup-Attribut am Host, hat dieses Vorrang. So kann ein Web Component seine eigene Barrierefreiheit festlegen, ohne sichtbare Attribute in das Markup des Nutzers zu schreiben.

Typisch ist der Einsatz in eigenen Buttons, Comboboxen oder Menü-Triggern, die als autonome Custom Elements gebaut werden. Den Zugriff auf das ElementInternals-Objekt bekommt man im Konstruktor über this.attachInternals(). Meist setzt man ariaHasPopup zusammen mit role und ariaExpanded.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen einer der Werte `"false"`, `"true"`, `"menu"`, `"listbox"`, `"tree"`, `"grid"`, `"dialog"`. Mit `null` wird der Standardwert wieder entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell gesetzte Standardwert als Zeichenkette oder null, wenn keiner gesetzt ist. Ein aria-haspopup-Attribut am Host-Element wird dabei nicht berücksichtigt.

Beispiele

Custom-Button mit Menü-Popup

class MenuButton extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'button';
    this.#internals.ariaHasPopup = 'menu';
    this.#internals.ariaExpanded = 'false';
    this.tabIndex = 0;
  }
}
customElements.define('menu-button', MenuButton);

const btn = document.createElement('menu-button');
document.body.append(btn);
console.log(btn.hasAttribute('aria-haspopup'));

false

Combobox mit Listbox-Popup, Zustand umschalten

class MyCombo extends HTMLElement {
  #internals = this.attachInternals();
  #open = false;
  constructor() {
    super();
    this.#internals.role = 'combobox';
    this.#internals.ariaHasPopup = 'listbox';
    this.#internals.ariaExpanded = 'false';
    this.addEventListener('click', () => this.toggle());
  }
  toggle() {
    this.#open = !this.#open;
    this.#internals.ariaExpanded = String(this.#open);
    console.log(this.#internals.ariaHasPopup, this.#internals.ariaExpanded);
  }
}
customElements.define('my-combo', MyCombo);

const combo = document.createElement('my-combo');
document.body.append(combo);
combo.click();

listbox true

Popup-Typ je nach Attribut wechseln und zurücksetzen

class PopupTrigger extends HTMLElement {
  static observedAttributes = ['popup-type'];
  #internals = this.attachInternals();
  attributeChangedCallback(name, _old, value) {
    // value null => Standardsemantik entfernen
    this.#internals.ariaHasPopup = value;
    console.log('ariaHasPopup:', this.#internals.ariaHasPopup);
  }
}
customElements.define('popup-trigger', PopupTrigger);

const t = document.createElement('popup-trigger');
t.setAttribute('popup-type', 'dialog');
t.removeAttribute('popup-type');

ariaHasPopup: dialog ariaHasPopup: null

// Wichtig · Fallstricke

Nur für Custom Elements: attachInternals() gibt es nur für autonome Custom Elements. Bei eingebauten Elementen oder einem zweiten Aufruf wird ein NotSupportedError geworfen.
Vorrang: Ein aria-haspopup-Attribut am Host überschreibt den Wert aus ElementInternals. Der Getter zeigt trotzdem weiter nur den internen Wert an.
Keine Prüfung der Werte: Der Browser nimmt jede Zeichenkette an. Ungültige Werte behandeln assistive Technologien wie "false".
Nur Semantik: Die Eigenschaft beschreibt das Popup nur. Tastaturbedienung, Fokus-Verwaltung und ariaExpanded muss die Komponente selbst umsetzen.
Die Rolle muss zum Popup passen. aria-haspopup ist z. B. bei button, combobox, menuitem und link sinnvoll.
Browser: Firefox unterstützt die ARIA-Reflection auf ElementInternals erst seit Version 119. Für ältere Browser kann man ersatzweise this.setAttribute('aria-haspopup', …) verwenden.

Siehe auch

ElementInternals.ariaHidden ElementInternals.ariaAtomic ElementInternals.ariaSort ElementInternals.ariaBusy ElementInternals.ariaColCount