CommandEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface CommandEvent extends Event

Beschreibung

CommandEvent gehört zur Invoker Commands API. Hat ein <button> die Attribute commandfor (ID des Ziel-Elements) und command (Name des Befehls), löst ein Klick auf den Button auf dem Ziel-Element ein command-Ereignis aus. Ereignisobjekt ist ein CommandEvent. So kann man Dialoge, Popovers und eigene Komponenten ganz ohne eigene Klick-Handler auf den Buttons steuern.

Das Interface ergänzt Event um zwei schreibgeschützte Eigenschaften:

command: der Wert des command-Attributs des Buttons, z. B. "show-modal" oder ein eigener Befehl wie "--rotate".
source: das Element, das den Befehl ausgelöst hat (in der Regel der Button).

Eingebaute Befehle sind show-modal, close und request-close für <dialog> sowie show-popover, hide-popover und toggle-popover für Popovers. Eigene Befehle müssen mit zwei Bindestrichen beginnen (--mein-befehl). Für die setzt der Browser keine Standardaktion um, Sie verarbeiten sie selbst in einem Listener. Das Ereignis lässt sich abbrechen: preventDefault() verhindert die eingebaute Aktion.

Einen Listener registrieren Sie mit element.addEventListener("command", handler) oder über die Eigenschaft element.oncommand. Per Skript setzen Sie das Ziel mit button.commandForElement und den Befehl mit button.command.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses für den Konstruktor `new CommandEvent(type, options)`. Normalerweise `"command"`.
$options	object	{}	Optional. Ein `EventInit`-Objekt (`bubbles`, `cancelable`, `composed`) mit zwei zusätzlichen Feldern: `command` (`string`, Standard `""`) und `source` (`Element \| null`, Standard `null`).

Rückgabewert

Typ

CommandEvent

Beschreibung

Der Konstruktor gibt ein neues CommandEvent-Objekt zurück. Es hat die schreibgeschützten Eigenschaften command (string) und source (Element | null).

Beispiele

Eigenen Befehl verarbeiten (addEventListener)

// HTML:
// <button commandfor="bild" command="--drehen">Drehen</button>
// <img id="bild" src="foto.jpg" alt="Foto">

const bild = document.getElementById('bild');
let winkel = 0;

bild.addEventListener('command', (event) => {
  if (event.command === '--drehen') {
    winkel = (winkel + 90) % 360;
    bild.style.rotate = `${winkel}deg`;
    console.log(`Gedreht von <${event.source.tagName.toLowerCase()}>: ${winkel}°`);
  }
});

Gedreht von <button>: 90°

Eingebauten Befehl abfangen: Schließen eines Dialogs bestätigen

// HTML:
// <button commandfor="formular" command="show-modal">Öffnen</button>
// <dialog id="formular">
//   <textarea></textarea>
//   <button commandfor="formular" command="close">Schließen</button>
// </dialog>

const dialog = document.getElementById('formular');

dialog.oncommand = (event) => {
  if (event.command !== 'close') return;
  const text = dialog.querySelector('textarea').value;
  if (text && !confirm('Ungespeicherte Eingaben verwerfen?')) {
    event.preventDefault(); // Dialog bleibt offen
  }
};

Button per Skript verdrahten mit Feature-Erkennung

const menue = document.getElementById('menue'); // Element mit popover-Attribut
const button = document.createElement('button');
button.textContent = 'Menü';

if ('commandForElement' in HTMLButtonElement.prototype) {
  button.commandForElement = menue;
  button.command = 'toggle-popover';
} else {
  // Rückfallebene für ältere Browser
  button.addEventListener('click', () => menue.togglePopover());
}

document.body.append(button);

CommandEvent selbst erzeugen und auslösen

const player = document.getElementById('player');

player.addEventListener('command', (e) => {
  console.log(e instanceof CommandEvent, e.command, e.source?.id);
});

const ausloeser = document.getElementById('play-knopf');
player.dispatchEvent(new CommandEvent('command', {
  command: '--abspielen',
  source: ausloeser,
  cancelable: true
}));

true --abspielen play-knopf

// Wichtig · Fallstricke

Ziel-Element, nicht Button: Das Ereignis wird auf dem Element ausgelöst, auf das commandfor zeigt. Ein Listener auf dem Button empfängt es nicht. Das Ereignis steigt nicht auf (bubbles: false), deshalb funktioniert Event-Delegation am document nur in der Capture-Phase.
Eigene Befehle mit --: Unbekannte Befehle ohne das Präfix -- sind ungültig. Für sie wird kein Ereignis ausgelöst. Nutzen Sie das Präfix für eigene Befehle, damit spätere eingebaute Befehle nicht mit Ihren Namen kollidieren.
Nur <button>: commandfor/command wirken nur auf <button>-Elemente, nicht auf <a> oder <input type="button">. Buttons in Formularen sollten type="button" haben, damit sie das Formular nicht zusätzlich absenden.
Shadow DOM: source wird über Shadow-Grenzen hinweg umgeleitet (retargeting) und zeigt dann auf den Shadow-Host statt auf den inneren Button.
Kompatibilität: Die API ist recht neu (Chromium 135, Firefox 144, Safari 26.2). Prüfen Sie ihre Verfügbarkeit mit 'commandForElement' in HTMLButtonElement.prototype und sehen Sie für ältere Browser eine Rückfallebene über click-Handler vor. Ein Polyfill ist verfügbar (invokers-polyfill).
Selbst erzeugte Ereignisse (dispatchEvent) lösen keine eingebaute Aktion aus: Ein synthetisches show-modal öffnet also keinen Dialog.

Siehe auch

Event Comment FormDataEvent GamepadEvent ClipboardEvent