HTMLButtonElement.commandForElement — Eigenschaft · JavaScript-Referenz

Signatur

HTMLButtonElement.commandForElement

Beschreibung

commandForElement gehört zur Invoker Commands API. Die Eigenschaft enthält einen direkten Verweis auf das Zielelement, das eine Schaltfläche steuert. Das kann zum Beispiel ein <dialog>, ein Popover oder ein beliebiges Element mit einem eigenen Befehl sein. Welche Aktion ausgelöst wird, bestimmt die Eigenschaft command (Attribut command), also zum Beispiel "show-modal", "close", "request-close", "toggle-popover", "show-popover", "hide-popover" oder ein eigener Befehl mit dem Präfix --.

Beim Lesen löst der Browser das Attribut commandfor auf. Er gibt das Element mit der passenden id im selben Dokument bzw. in derselben Shadow-Root zurück. Gibt es kein solches Element, ist der Wert null. Beim Schreiben weist du direkt ein Element-Objekt zu. Das ist praktisch, wenn das Ziel keine id hat oder dynamisch erzeugt wird. Mit einem Element aus einer umgebenden (Vorfahren-)Shadow-Root funktioniert das sogar über Shadow-DOM-Grenzen hinweg.

Klickt jemand auf die Schaltfläche, löst der Browser am Zielelement ein command-Ereignis (CommandEvent) aus und führt anschließend die eingebaute Aktion aus. Deklarative Steuerungen wie „Dialog öffnen“ oder „Popover umschalten“ brauchen deshalb oft gar kein JavaScript mehr. Mit commandForElement kannst du solche Verknüpfungen aber per Skript herstellen, prüfen oder ändern.

Parameter

Name	Typ	Default	Beschreibung
$value	Element \| null	null	Beim Setzen: das Zielelement, das die Schaltfläche steuern soll. `null` entfernt die Verknüpfung.

Rückgabewert

Typ

Element | null

Beschreibung

Das gesteuerte Element oder null, wenn kein gültiges Ziel gesetzt ist oder das Attribut commandfor auf keine vorhandene id verweist.

Beispiele

Deklarativ verknüpftes Ziel auslesen

// HTML:
// <button id="open" type="button" commandfor="settings" command="show-modal">Einstellungen</button>
// <dialog id="settings">…</dialog>

const button = document.getElementById('open');
console.log(button.commandForElement);           // das <dialog>-Element
console.log(button.commandForElement?.id);       // Ziel-ID
console.log(button.command);                     // gewählter Befehl

<dialog id="settings">…</dialog> settings show-modal

Dynamisch erzeugten Dialog ohne id verknüpfen

const dialog = document.createElement('dialog');
dialog.innerHTML = '<p>Wirklich löschen?</p>';
document.body.append(dialog);

const openBtn = document.createElement('button');
openBtn.type = 'button';
openBtn.textContent = 'Löschen …';
openBtn.command = 'show-modal';
openBtn.commandForElement = dialog; // direkte Referenz statt id
document.body.append(openBtn);

const closeBtn = document.createElement('button');
closeBtn.type = 'button';
closeBtn.textContent = 'Abbrechen';
closeBtn.command = 'close';
closeBtn.commandForElement = dialog;
dialog.append(closeBtn);

console.log(openBtn.getAttribute('commandfor'));

"" (leerer String – das Attribut spiegelt keine Element-Referenz wider)

Eigener Befehl mit command-Ereignis

// HTML:
// <button type="button" commandfor="counter" command="--increment">+1</button>
// <output id="counter">0</output>

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

counter.addEventListener('command', (event) => {
  if (event.command === '--increment') {
    counter.value = String(Number(counter.value) + 1);
    console.log('Ausgelöst von:', event.source.textContent);
  }
});

// Das Ziel lässt sich später per Skript auf ein anderes Element umhängen:
const btn = document.querySelector('[command="--increment"]');
console.log(btn.commandForElement === counter);

true Ausgelöst von: +1 (nach Klick)

Verfügbarkeit prüfen und Rückfallebene nutzen

const supportsCommands = 'commandForElement' in HTMLButtonElement.prototype;

if (!supportsCommands) {
  // Rückfallebene: klassischer Klick-Handler
  document.querySelectorAll('button[commandfor][command="show-modal"]').forEach((btn) => {
    btn.addEventListener('click', () => {
      document.getElementById(btn.getAttribute('commandfor'))?.showModal();
    });
  });
}
console.log('Invoker Commands unterstützt:', supportsCommands);

Invoker Commands unterstützt: true

// Wichtig · Fallstricke

Browser-Unterstützung: Die Eigenschaft ist neu (Chrome/Edge ab 135, Firefox ab 144, Safari ab 26.2). Für ältere Browser brauchst du eine Funktionsprüfung ('commandForElement' in HTMLButtonElement.prototype) oder ein Polyfill (z. B. invokers-polyfill).
Verhalten des Attributs: Wenn du commandForElement ein Element zuweist, wird das Attribut commandfor auf einen leeren String gesetzt – es enthält nicht die id des Ziels. Wer das Attribut ausliest, sieht also die Verknüpfung nicht.
Shadow DOM: Ein Ziel in einer untergeordneten Shadow-Root (also im Inneren einer anderen Komponente) wird nicht akzeptiert – der Getter liefert dann null. Erlaubt sind Elemente im selben oder in einem umgebenden Baum.
Nur mit command: Ohne gültigen Wert für command passiert beim Klick nichts. Unbekannte Befehle ohne das Präfix -- werden ignoriert.
Formulare: Gib in Formularen trotzdem ausdrücklich type="button" an. Nur so bist du sicher, dass kein Formular abgeschickt wird – auch nicht in Browsern ohne Unterstützung.
Deaktivierte Schaltflächen: Ist die Schaltfläche disabled, wird der Befehl nicht ausgelöst. Das gilt auch für <input type="button">: Dort gibt es die Eigenschaft nicht, sie existiert nur an <button>.

Siehe auch

HTMLButtonElement.formNoValidate HTMLButtonElement.interestForElement HTMLButtonElement.command HTMLButtonElement.popoverTargetElement HTMLButtonElement.formAction