CommandEvent.command — Eigenschaft · JavaScript-Referenz

Signatur

CommandEvent.command

Beschreibung

Die Eigenschaft command gehört zum Interface CommandEvent aus der Invoker Commands API. Ein <button> mit den Attributen commandfor und command steuert damit ein anderes Element deklarativ, also ohne eigenes Klick-Skript. Beim Klick wird auf dem Zielelement, also auf dem Element, das in commandfor angegeben ist, ein command-Ereignis ausgelöst. event.command enthält dann den Wert, den das command-Attribut des Buttons in diesem Moment hatte.

Es gibt zwei Arten von Werten:

Eingebaute Befehle wie show-modal, close und request-close für <dialog> sowie show-popover, hide-popover und toggle-popover für Popover-Elemente. Diese Befehle führt der Browser selbst aus.
Eigene Befehle, die mit zwei Bindestrichen beginnen müssen, z. B. --next-slide. Der Browser führt sie nicht aus. Dein Skript muss im Listener anhand von event.command selbst entscheiden, was passiert.

Die Eigenschaft ist vor allem dann nützlich, wenn mehrere Buttons dasselbe Zielelement mit unterschiedlichen Befehlen ansteuern. Ein einziger Listener auf dem Ziel verteilt die Aktionen dann über switch (event.command). Welcher Button das Ereignis ausgelöst hat, steht in event.source.

Rückgabewert

Typ

string

Beschreibung

Der Befehl, der beim Auslösen des Ereignisses festgelegt war, z. B. "show-modal" oder "--refresh". Bei synthetischen Ereignissen ist es der Wert aus dem Konstruktor. Ohne Angabe ist es ein leerer String "".

Beispiele

Eigene Befehle auf einem Zielelement verteilen

// HTML:
// <button commandfor="counter" command="--increment">+1</button>
// <button commandfor="counter" command="--decrement">-1</button>
// <button commandfor="counter" command="--reset">Zurücksetzen</button>
// <output id="counter">0</output>

const counter = document.getElementById('counter');
let value = 0;

counter.addEventListener('command', (event) => {
  switch (event.command) {
    case '--increment': value++; break;
    case '--decrement': value--; break;
    case '--reset':     value = 0; break;
    default: return; // unbekannte Befehle ignorieren
  }
  counter.textContent = value;
  console.log(`Befehl ${event.command} von`, event.source.textContent);
});

Befehl --increment von +1

Eingebaute Dialog-Befehle protokollieren und abfangen

// HTML:
// <button commandfor="dlg" command="show-modal">Öffnen</button>
// <dialog id="dlg">
//   <p>Ungespeicherte Änderungen!</p>
//   <button commandfor="dlg" command="close">Schließen</button>
// </dialog>

const dialog = document.getElementById('dlg');
let hasUnsavedChanges = true;

dialog.addEventListener('command', (event) => {
  console.log('Befehl:', event.command);
  // Schließen verhindern, solange noch Änderungen offen sind
  if (event.command === 'close' && hasUnsavedChanges) {
    event.preventDefault();
    console.log('Schließen abgebrochen – bitte zuerst speichern.');
  }
});

Befehl: show-modal Befehl: close Schließen abgebrochen – bitte zuerst speichern.

Synthetisches CommandEvent erzeugen

const panel = document.createElement('div');

panel.addEventListener('command', (event) => {
  console.log(event instanceof CommandEvent, event.command);
});

const evt = new CommandEvent('command', {
  command: '--toggle-details',
  source: null
});
panel.dispatchEvent(evt);

// Die Eigenschaft ist schreibgeschützt:
evt.command = '--anders';
console.log(evt.command);

true --toggle-details --toggle-details

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an event.command wird im Nicht-Strict-Modus stillschweigend ignoriert. Im Strict-Modus, also auch in ES-Modulen, wirft sie einen TypeError.
Präfix -- für eigene Befehle: Ein unbekannter Wert ohne -- (z. B. command="refresh") gilt als ungültig. Solche Werte sind für künftige eingebaute Befehle reserviert. Verlass dich also nicht darauf, dass ein Ereignis dafür verlässlich ausgelöst wird.
Zeitpunkt: Der Wert wird beim Auslösen festgehalten. Ändert sich das command-Attribut des Buttons später, bleibt event.command gleich.
Das Ereignis wird auf dem Zielelement ausgelöst, nicht auf dem Button. Es steigt nicht auf (bubbelt nicht), lässt sich aber mit preventDefault() abbrechen. Damit kannst du auch eingebaute Aktionen wie close verhindern.
Browserunterstützung: Die Invoker Commands API ist recht neu. Sie wird von Chromium-Browsern ab Version 135 unterstützt, in Firefox und Safari erst in neueren Versionen. Prüfe die Unterstützung mit 'command' in HTMLButtonElement.prototype und sieh für ältere Browser eine Lösung mit click-Listenern vor.

Siehe auch

CommandEvent.source FormDataEvent.formData GamepadEvent.gamepad CloseEvent.code ErrorEvent.colno