ElementInternals.ariaPressed — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaPressed

Beschreibung

Die Eigenschaft ariaPressed des ElementInternals-Interfaces entspricht dem ARIA-Zustand aria-pressed. Er gibt an, ob ein Umschaltknopf (Toggle-Button) gerade „gedrückt“ ist. Erlaubt sind die Zeichenketten "true", "false", "mixed" (teilweise gedrückt, z. B. bei einer Gruppe) und "undefined" (Element kann nicht umgeschaltet werden).

Anders als element.ariaPressed bzw. das HTML-Attribut aria-pressed legt ElementInternals.ariaPressed die Standard-Semantik eines autonomen Custom Elements fest. Dabei erscheint kein Attribut im DOM, der Zustand ist also im Markup unsichtbar. Screenreader lesen ihn trotzdem über den Barrierefreiheitsbaum aus. Setzt der Nutzer der Komponente selbst ein aria-pressed-Attribut am Host-Element, hat dieses Vorrang.

Typisch ist der Einsatz in Web Components, die sich wie ein Toggle-Button verhalten sollen: Im Konstruktor holt man sich per this.attachInternals() das ElementInternals-Objekt und setzt role = "button". Anschließend aktualisiert man ariaPressed bei jedem Umschalten. So bleibt die Komponente in sich geschlossen und verändert nicht die Attribute, die der Nutzer der Komponente gesetzt hat.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: `"true"`, `"false"`, `"mixed"` oder `"undefined"`. Mit `null` entfernen Sie den Standardwert.

Rückgabewert

Typ

string | null

Beschreibung

Den aktuell gesetzten Standardwert als Zeichenkette ("true", "false", "mixed", "undefined") oder null, wenn kein Wert gesetzt ist.

Beispiele

Toggle-Button als Custom Element

class ToggleButton extends HTMLElement {
  #internals;
  #pressed = false;

  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'button';
    this.#internals.ariaPressed = 'false';
    this.tabIndex = 0;

    this.addEventListener('click', () => this.toggle());
    this.addEventListener('keydown', (e) => {
      if (e.key === ' ' || e.key === 'Enter') {
        e.preventDefault();
        this.toggle();
      }
    });
  }

  toggle() {
    this.#pressed = !this.#pressed;
    this.#internals.ariaPressed = String(this.#pressed);
    this.toggleAttribute('data-pressed', this.#pressed);
  }
}

customElements.define('toggle-button', ToggleButton);
// <toggle-button>Fett</toggle-button>

Wert auslesen und prüfen

class MuteButton extends HTMLElement {
  static formAssociated = false;
  constructor() {
    super();
    this.internals = this.attachInternals();
    this.internals.role = 'button';
    this.internals.ariaPressed = 'true';
  }
}
customElements.define('mute-button', MuteButton);

const btn = document.createElement('mute-button');
console.log(btn.internals.ariaPressed);        // Standard-Semantik
console.log(btn.getAttribute('aria-pressed')); // kein Attribut im DOM

true null

Zustand „mixed“ für eine Gruppe von Optionen

class GroupToggle extends HTMLElement {
  #internals = this.attachInternals();

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

  update(states) {
    const active = states.filter(Boolean).length;
    this.#internals.ariaPressed =
      active === 0 ? 'false' : active === states.length ? 'true' : 'mixed';
    return this.#internals.ariaPressed;
  }
}
customElements.define('group-toggle', GroupToggle);

const g = document.createElement('group-toggle');
console.log(g.update([true, false, true]));

mixed

// Wichtig · Fallstricke

Nur zusammen mit passender Rolle: aria-pressed gilt nur für die Rolle button. Ohne internals.role = "button" ignorieren Hilfstechnologien den Wert oft.
Zeichenketten, keine Booleans: Der Wert wird als String gespeichert. ariaPressed = true ergibt zwar "true", beim Auslesen kommt aber immer ein String zurück. Deshalb ist if (internals.ariaPressed) auch bei "false" wahr.
Attribut hat Vorrang: Ein vom Nutzer gesetztes aria-pressed-Attribut am Host-Element überschreibt den Wert aus ElementInternals.
Nicht mit aria-checked/aria-selected verwechseln: Für Schalter mit der Rolle switch oder für Checkboxen ist ariaChecked richtig.
Kein CSS-Selektor: Da kein Attribut entsteht, greift [aria-pressed="true"] nicht. Verwenden Sie für das Styling eigene Attribute oder CustomStateSet (:state()).
Kompatibilität: attachInternals() funktioniert nur bei autonomen Custom Elements. Die ARIA-Spiegelung in ElementInternals unterstützt Firefox erst ab Version 119, ältere Browser brauchen ein Fallback über das Attribut.

Siehe auch

ElementInternals.ariaChecked ElementInternals.ariaLevel ElementInternals.ariaPosInSet ElementInternals.ariaRequired ElementInternals.ariaSelected