Document.queryCommandSupported() — Methode · JavaScript-Referenz

Signatur

Document.prototype.queryCommandSupported(command)

Beschreibung

document.queryCommandSupported() gehört zur alten Editing-API rund um document.execCommand(). Die Methode sagt, ob der Browser einen bestimmten Befehl wie "bold", "copy" oder "insertText" grundsätzlich kennt. Damit lässt sich prüfen, ob eine Funktion vorhanden ist, bevor man einen Befehl ausführt oder zum Beispiel einen Toolbar-Button anzeigt.

Wichtig ist der Unterschied zu document.queryCommandEnabled(): queryCommandSupported() sagt nur, dass der Browser den Befehl umsetzen kann. Ob er jetzt gerade ausführbar ist, sagt die Methode nicht. Das hängt zum Beispiel von einer aktiven Auswahl oder einem fokussierten contenteditable-Bereich ab. Für diesen Zustand ist queryCommandEnabled() zuständig.

Die gesamte execCommand-Familie gilt als veraltet und ist nur in einem inoffiziellen Entwurf beschrieben. In neuem Code nutzt man stattdessen moderne APIs, etwa die Clipboard API (navigator.clipboard) zum Kopieren und Einfügen, beforeinput-Events und die Selection/Range-API für Editoren. Als Rückfallebene für ältere Umgebungen ist die Methode weiterhin nützlich.

Parameter

Name	Typ	Default	Beschreibung
$command Pflicht	string		Name des Editorbefehls, z. B. `"bold"`, `"italic"`, `"copy"`, `"cut"`, `"paste"`, `"insertText"`, `"createLink"` oder `"undo"`. Groß- und Kleinschreibung spielt keine Rolle.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Browser den Befehl kennt, sonst false. Bei unbekannten Befehlsnamen kommt false zurück, es wird keine Ausnahme geworfen.

Beispiele

Einfache Prüfung einzelner Befehle

const commands = ['bold', 'copy', 'insertText', 'gibtEsNicht'];

for (const cmd of commands) {
  console.log(`${cmd}: ${document.queryCommandSupported(cmd)}`);
}

bold: true copy: true insertText: true gibtEsNicht: false

Kopieren mit Clipboard API und Rückfallebene execCommand

const copyText = async (text) => {
  // Moderner Weg (sicherer Kontext, also HTTPS nötig)
  if (navigator.clipboard?.writeText) {
    await navigator.clipboard.writeText(text);
    return 'clipboard-api';
  }

  // Rückfallebene für alte Browser
  if (document.queryCommandSupported?.('copy')) {
    const textarea = document.createElement('textarea');
    textarea.value = text;
    textarea.setAttribute('readonly', '');
    textarea.style.position = 'fixed';
    textarea.style.opacity = '0';
    document.body.append(textarea);
    textarea.select();
    const ok = document.execCommand('copy');
    textarea.remove();
    return ok ? 'execCommand' : 'fehlgeschlagen';
  }

  return 'nicht unterstützt';
};

document.querySelector('#copy-btn').addEventListener('click', async () => {
  const method = await copyText('Hallo programmierung.net');
  console.log('Kopiert über:', method);
});

Kopiert über: clipboard-api

Toolbar-Buttons nur für unterstützte Befehle anzeigen

// HTML: <div id="toolbar"><button data-cmd="bold">B</button> ...</div>
//       <div id="editor" contenteditable="true"></div>
const toolbar = document.querySelector('#toolbar');

for (const button of toolbar.querySelectorAll('button[data-cmd]')) {
  const cmd = button.dataset.cmd;
  if (!document.queryCommandSupported(cmd)) {
    button.hidden = true; // Befehl unbekannt: Button ausblenden
    continue;
  }
  button.addEventListener('mousedown', (event) => {
    event.preventDefault(); // Auswahl im Editor nicht verlieren
    if (document.queryCommandEnabled(cmd)) {
      document.execCommand(cmd, false, null);
    }
  });
}

// Wichtig · Fallstricke

Veraltet: Die Methode gehört zur execCommand-API, die nie offiziell standardisiert wurde. Die Browser unterstützen sie noch, in neuen Projekten sollte man aber moderne Alternativen nehmen, z. B. navigator.clipboard und beforeinput/input-Events.
„Unterstützt“ heißt nicht „ausführbar“: queryCommandSupported('paste') kann true liefern, obwohl execCommand('paste') aus Sicherheitsgründen scheitert. Ob ein Befehl gerade ausführbar ist, prüft man mit queryCommandEnabled(), und man wertet immer den Rückgabewert von execCommand() aus.
Nutzeraktion nötig: copy und cut funktionieren in der Regel nur direkt nach einer Nutzeraktion, etwa innerhalb eines Klick-Handlers.
Browser-Unterschiede: Ältere Firefox-Versionen haben bei manchen Befehlen Ausnahmen geworfen (z. B. NS_ERROR_FAILURE, wenn kein Editor aktiv war). Deshalb den Aufruf zur Sicherheit in try/catch packen oder mit optionaler Verkettung (?.) aufrufen, falls die Methode in exotischen Umgebungen fehlt.
Es gibt kein Gegenstück in Node.js, die Methode existiert nur im Browser-DOM.

Siehe auch

Document.execCommand() Document.queryCommandEnabled() Document.queryCommandState() Clipboard.writeText() HTMLElement.contentEditable