HTMLButtonElement.command — Eigenschaft · JavaScript-Referenz

Signatur

HTMLButtonElement.command

Beschreibung

Die Eigenschaft command spiegelt das HTML-Attribut command eines <button> wider. Sie gehört zur Invoker Commands API. Mit ihr steuert ein Button ein anderes Element, zum Beispiel einen <dialog> oder ein Popover, rein deklarativ und ohne eigenen Klick-Handler. Welches Element gesteuert wird, legst du über das Attribut commandfor (ID des Ziels) oder die Eigenschaft commandForElement fest.

Diese Werte sind eingebaut:

"show-modal", "close", "request-close" – für <dialog>-Elemente
"show-popover", "hide-popover", "toggle-popover" – für Elemente mit dem Attribut popover
Eigene Befehle: beliebige Zeichenketten, die mit zwei Bindestrichen beginnen, z. B. "--rotate". Der Browser führt dafür keine eigene Aktion aus. Du wertest sie selbst im Ereignis command des Zielelements aus.

Bei jedem Klick wird auf dem Zielelement ein CommandEvent (Typ "command") ausgelöst. Es enthält den Befehl (event.command) und den auslösenden Button (event.source). Rufst du im Handler preventDefault() auf, wird auch die eingebaute Aktion unterdrückt.

Parameter

Name	Typ	Default	Beschreibung
$value	string	""	Beim Setzen: ein eingebauter Befehl (Groß-/Kleinschreibung egal) oder ein eigener Befehl mit dem Präfix `--`. Der Wert wird in das Attribut `command` geschrieben.

Rückgabewert

Typ

string

Beschreibung

Der eingebaute Befehl in Kleinbuchstaben oder der eigene Befehl unverändert. Fehlt das Attribut oder ist der Wert ungültig (z. B. "foo" ohne --), ist das Ergebnis ein leerer String "".

Beispiele

Dialog per Button öffnen und schließen

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

const openBtn = document.querySelector('#open');
console.log(openBtn.command);                // "show-modal"
console.log(openBtn.commandForElement.id);   // "dlg"

show-modal dlg

Befehl per JavaScript setzen und Popover umschalten

const menu = document.createElement('div');
menu.id = 'menu';
menu.popover = 'auto';
menu.textContent = 'Menüinhalt';

const btn = document.createElement('button');
btn.type = 'button';
btn.textContent = 'Menü';
btn.commandForElement = menu;
btn.command = 'TOGGLE-POPOVER'; // Schreibweise egal

document.body.append(btn, menu);
console.log(btn.command);                     // normalisiert
console.log(btn.getAttribute('command'));     // Originalwert

toggle-popover TOGGLE-POPOVER

Eigener Befehl mit dem command-Ereignis

// HTML:
// <button commandfor="img" command="--rotate-left">⟲</button>
// <button commandfor="img" command="--rotate-right">⟳</button>
// <img id="img" src="foto.jpg" alt="Foto">

const img = document.querySelector('#img');
let angle = 0;

img.addEventListener('command', (event) => {
  if (event.command === '--rotate-left') angle -= 90;
  if (event.command === '--rotate-right') angle += 90;
  img.style.rotate = `${angle}deg`;
  console.log(`${event.source.textContent} → ${angle}°`);
});

⟳ → 90°

Ungültige Werte und Feature-Erkennung

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

if ('command' in HTMLButtonElement.prototype) {
  btn.command = 'rotate';      // fehlendes "--" → ungültig
  console.log(JSON.stringify(btn.command));
  btn.command = '--rotate';
  console.log(btn.command);
} else {
  console.log('Invoker Commands werden nicht unterstützt');
}

"" --rotate

// Wichtig · Fallstricke

Browserunterstützung: Die Eigenschaft ist neu (Chrome/Edge 135, Firefox 144, Safari 26.2). In älteren Browsern passiert beim Klick nichts. Prüfe die Unterstützung mit 'command' in HTMLButtonElement.prototype und sieh bei Bedarf einen Klick-Handler als Rückfall vor oder nutze ein Polyfill.
Eigene Befehle brauchen --: Werte ohne dieses Präfix, die kein eingebauter Befehl sind, gelten als ungültig. Die Eigenschaft liefert dann "", und das command-Ereignis wird nicht ausgelöst. So bleiben Namen für künftige eingebaute Befehle frei.
Passender Zieltyp: "show-modal" wirkt nur auf <dialog>, die Popover-Befehle nur auf Elemente mit popover. Passt der Befehl nicht zum Ziel, geschieht nichts, und es gibt keine Fehlermeldung.
Formulare: Ein Button mit command oder commandfor sendet laut Spezifikation kein Formular ab. Setze trotzdem ausdrücklich type="button", dann verhält er sich auch in älteren Browsern richtig.
Das Ziel muss im selben Baum liegen: Eine ID in commandfor wird nicht über Shadow-DOM-Grenzen hinweg gefunden. In diesem Fall setzt du commandForElement direkt.
Der Rückgabewert von command ist normalisiert (Kleinbuchstaben). getAttribute('command') liefert dagegen den Wert genau so, wie er im Attribut steht.

Siehe auch

HTMLButtonElement.commandForElement HTMLButtonElement.form HTMLButtonElement.formMethod HTMLButtonElement.name HTMLButtonElement.disabled