ElementInternals.ariaKeyShortcuts — Eigenschaft · JavaScript-Referenz

Signatur

ElementInternals.ariaKeyShortcuts

Beschreibung

Die Eigenschaft ariaKeyShortcuts des ElementInternals-Interfaces entspricht dem ARIA-Attribut aria-keyshortcuts. Sie teilt assistiven Technologien (z. B. Screenreadern) mit, welche Tastaturkürzel der Autor implementiert hat, um ein Element zu aktivieren oder den Fokus darauf zu setzen. Der Wert ist ein String mit einem oder mehreren Kürzeln, getrennt durch Leerzeichen, z. B. "Alt+Shift+A" oder "Control+S Meta+S".

Anders als Element.ariaKeyShortcuts bzw. das HTML-Attribut setzt die Variante auf ElementInternals die Standard-Semantik eines autonomen Custom Elements. Es wird kein Attribut im DOM erzeugt – der Nutzer der Komponente bleibt frei, per aria-keyshortcuts-Attribut einen eigenen Wert anzugeben, der dann Vorrang hat. So lassen sich barrierefreie Web Components bauen, ohne das Light DOM des Hosts zu „verschmutzen“.

Die Eigenschaft ist rein deklarativ: Sie beschreibt nur Kürzel, sie registriert keine. Die tatsächliche Tastaturbehandlung (z. B. per keydown-Listener) muss die Komponente selbst implementieren.

Man erhält das ElementInternals-Objekt über this.attachInternals() im Konstruktor eines Custom Elements.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: durch Leerzeichen getrennte Liste von Tastaturkürzeln; Modifikatoren und Taste werden mit `+` verbunden (z. B. `"Control+Shift+F"`). Tastennamen folgen den `KeyboardEvent.key`-Werten. `null` entfernt die Standard-Semantik.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuell über ElementInternals gesetzte Kürzel-String oder null, wenn nichts gesetzt wurde. Ein vom Nutzer gesetztes aria-keyshortcuts-Attribut wird hier nicht gespiegelt.

Beispiele

Standard-Kürzel in einem Custom Element setzen

class SaveButton extends HTMLElement {
  #internals;
  constructor() {
    super();
    this.#internals = this.attachInternals();
    this.#internals.role = 'button';
    this.#internals.ariaKeyShortcuts = 'Control+S Meta+S';
    this.tabIndex = 0;
  }
  get shortcuts() {
    return this.#internals.ariaKeyShortcuts;
  }
}
customElements.define('save-button', SaveButton);

const btn = document.createElement('save-button');
btn.textContent = 'Speichern';
document.body.append(btn);
console.log(btn.shortcuts);
console.log(btn.hasAttribute('aria-keyshortcuts'));

Control+S Meta+S false

Kürzel beschreiben UND tatsächlich implementieren

class SearchBox extends HTMLElement {
  #internals = this.attachInternals();
  #onKey = (e) => {
    if (e.altKey && e.shiftKey && e.key.toUpperCase() === 'F') {
      e.preventDefault();
      this.shadowRoot.querySelector('input').focus();
    }
  };
  constructor() {
    super();
    this.attachShadow({ mode: 'open' }).innerHTML = '<input type="search" aria-label="Suche">';
    this.#internals.role = 'search';
    this.#internals.ariaKeyShortcuts = 'Alt+Shift+F';
  }
  connectedCallback() {
    document.addEventListener('keydown', this.#onKey);
  }
  disconnectedCallback() {
    document.removeEventListener('keydown', this.#onKey);
  }
}
customElements.define('search-box', SearchBox);

Kürzel dynamisch ändern und entfernen

class ToggleItem extends HTMLElement {
  #internals = this.attachInternals();
  static observedAttributes = ['shortcut'];
  attributeChangedCallback(name, _old, value) {
    // leerer/fehlender Wert entfernt die Standard-Semantik
    this.#internals.ariaKeyShortcuts = value || null;
    console.log('Kürzel:', this.#internals.ariaKeyShortcuts);
  }
}
customElements.define('toggle-item', ToggleItem);

const item = document.createElement('toggle-item');
item.setAttribute('shortcut', 'Alt+T');
item.removeAttribute('shortcut');

Kürzel: Alt+T Kürzel: null

// Wichtig · Fallstricke

Nur Beschreibung: Die Eigenschaft löst keine Tastaturbehandlung aus. Ohne eigenen keydown-Handler ist die Angabe irreführend für Nutzer von Screenreadern.
Vorrang: Ein explizites aria-keyshortcuts-Attribut am Host-Element überschreibt den Wert aus ElementInternals.
Kollisionen vermeiden: Kürzel wie Control+S, Control+W oder Screenreader-Tasten (z. B. Insert-/CapsLock-Kombinationen) können mit Browser, Betriebssystem oder assistiver Technik kollidieren. Auf macOS Meta statt Control zusätzlich angeben.
Syntax: Modifikatoren zuerst, Taste zuletzt; Tastennamen nach KeyboardEvent.key (z. B. ArrowUp, Space als \" \" ist unzulässig – stattdessen Space). Der Browser validiert den String nicht.
attachInternals() funktioniert nur für autonome Custom Elements und darf pro Element nur einmal aufgerufen werden, sonst NotSupportedError.
Kompatibilität: ARIA-Reflection auf ElementInternals ist erst ab Firefox 119 und Safari 16.4 verfügbar; für ältere Browser per Feature-Test ('ariaKeyShortcuts' in ElementInternals.prototype) auf das Attribut zurückfallen.

Siehe auch

ElementInternals.ariaHasPopup ElementInternals.ariaSort ElementInternals.ariaOwnsElements ElementInternals.ariaAtomic ElementInternals.ariaAutoComplete