new CommandEvent() — Methode · JavaScript-Referenz

Signatur

new CommandEvent(type, options)

Beschreibung

Der Konstruktor CommandEvent() gehört zur Invoker Commands API. Normalerweise erzeugt der Browser ein CommandEvent selbst: Klickt man einen <button> mit den Attributen commandfor und command an, wird auf dem Zielelement ein Event vom Typ command ausgelöst. Dazu braucht man kein JavaScript.

Mit dem Konstruktor kannst du so ein Event auch selbst erzeugen und per dispatchEvent() auslösen. Das ist nützlich für Unit-Tests, für eigene Komponenten, die auf command-Events hören, oder wenn ein Befehl aus einem anderen Kontext kommen soll, etwa über ein Tastenkürzel oder eine WebSocket-Nachricht.

Wichtig: Ein selbst ausgelöstes CommandEvent führt keine eingebauten Aktionen aus, zum Beispiel show-modal bei einem <dialog>. Es ruft nur deine Listener auf. Eigene Befehle müssen mit zwei Bindestrichen beginnen (z. B. --rotate), damit sie nicht mit künftigen eingebauten Befehlen kollidieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Events. Für die Invoker Commands API ist das in der Regel `"command"`.
$options	object	{}	Optionales Objekt mit folgenden Feldern: `command` (`string`, Standard `""`): der Befehl, z. B. `"show-modal"` oder `"--mein-befehl"`. `source` (`Element \| null`, Standard `null`): das Element, das den Befehl ausgelöst hat. Dazu die Felder aus `EventInit`: `bubbles`, `cancelable`, `composed` (jeweils Standard `false`).

Rückgabewert

Typ

CommandEvent

Beschreibung

Ein neues CommandEvent-Objekt. Die Werte aus options stehen danach in den schreibgeschützten Eigenschaften command und source.

Beispiele

Event erzeugen und Eigenschaften auslesen

const button = document.createElement('button');

const event = new CommandEvent('command', {
  command: '--toggle-theme',
  source: button,
  cancelable: true
});

console.log(event.type);                // Event-Typ
console.log(event.command);             // übergebener Befehl
console.log(event.source === button);   // auslösendes Element
console.log(event.cancelable);

command --toggle-theme true true

Eigenen Befehl programmatisch auslösen (z. B. per Tastenkürzel)

// HTML: <div id="bild"></div>
//       <button commandfor="bild" command="--rotate">Drehen</button>
const bild = document.getElementById('bild');
let winkel = 0;

bild.addEventListener('command', (e) => {
  if (e.command === '--rotate') {
    winkel = (winkel + 90) % 360;
    bild.style.transform = `rotate(${winkel}deg)`;
    console.log(`Gedreht auf ${winkel}° durch`, e.source?.tagName ?? 'Code');
  }
});

// Taste "r" löst denselben Befehl aus wie der Button
document.addEventListener('keydown', (e) => {
  if (e.key === 'r') {
    bild.dispatchEvent(new CommandEvent('command', { command: '--rotate' }));
  }
});

Gedreht auf 90° durch Code

Komponente im Test ansprechen, mit Feature-Erkennung

const dialog = document.createElement('dialog');
document.body.append(dialog);

const empfangen = [];
dialog.addEventListener('command', (e) => empfangen.push(e.command));

if (typeof CommandEvent === 'function') {
  dialog.dispatchEvent(new CommandEvent('command', { command: 'show-modal' }));
  console.log(empfangen);   // Listener wurde aufgerufen
  console.log(dialog.open); // Dialog bleibt aber geschlossen!
} else {
  console.log('Invoker Commands API wird nicht unterstützt');
}

["show-modal"] false

// Wichtig · Fallstricke

Keine eingebauten Aktionen: Ein selbst ausgelöstes Event mit command: \"show-modal\", \"close\", \"toggle-popover\" usw. öffnet oder schließt nichts. Es werden nur die Listener aufgerufen. Für die eigentliche Aktion brauchst du direkte Aufrufe wie dialog.showModal() oder button.click() auf einem Button, der die Attribute command/commandfor hat.
Eigene Befehle müssen mit -- beginnen. Befehle ohne dieses Präfix, die der Browser nicht kennt, ignoriert er bei deklarativer Nutzung über HTML-Attribute.
bubbles ist standardmäßig false, genau wie beim nativen command-Event. Delegierte Listener auf Elternelementen erreicht das Event nur, wenn du bubbles: true setzt.
isTrusted ist bei selbst erzeugten Events immer false. Sicherheitsrelevante Logik kann daran erkennen, ob das Event vom Nutzer kam.
Kompatibilität: Die API ist neu und steht erst in aktuellen Browserversionen zur Verfügung. Ältere Browser kennen CommandEvent gar nicht, dort löst der Aufruf einen ReferenceError aus. Prüfe deshalb vorher mit typeof CommandEvent === 'function' bzw. 'command' in HTMLButtonElement.prototype, oder verwende ein Polyfill.

Siehe auch

new Comment() new FormDataEvent() new GamepadEvent() new ClipboardEvent() new CloseEvent()