Document.queryCommandState() — Methode · JavaScript-Referenz

Signatur

Document.prototype.queryCommandState(command)

Beschreibung

document.queryCommandState() gehört zur alten Editing-API rund um document.execCommand(). Die Methode gibt an, ob ein bestimmter Formatierungsbefehl, etwa bold, italic oder insertOrderedList, an der aktuellen Auswahl oder Cursorposition in einem editierbaren Bereich (contenteditable oder designMode = "on") aktiv ist.

Typischer Einsatz sind WYSIWYG-Editoren: Die Buttons einer Werkzeugleiste (F, K, U) sollen hervorgehoben werden, wenn der Text unter dem Cursor bereits so formatiert ist. Dazu fragt man bei jedem selectionchange-Ereignis den Zustand der betroffenen Befehle ab.

Die Methode funktioniert nur bei Befehlen, die einen Zustand haben, also an- oder ausgeschaltet sein können. Bei Befehlen mit einem Wert, etwa fontName oder foreColor, nimmt man stattdessen queryCommandValue(). Mit queryCommandSupported() und queryCommandEnabled() prüft man, ob ein Befehl überhaupt bekannt bzw. gerade ausführbar ist.

Parameter

Name	Typ	Default	Beschreibung
$command Pflicht	string		Name des `execCommand()`-Befehls, z. B. `"bold"`, `"italic"`, `"underline"`, `"strikeThrough"`, `"insertUnorderedList"`, `"justifyCenter"`. Groß- und Kleinschreibung spielt keine Rolle.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Befehl an der aktuellen Auswahl aktiv ist, sonst false. Bei unbekannten oder nicht zustandsbehafteten Befehlen liefern Browser meist false. Ältere Browser gaben in manchen Fällen auch null zurück oder warfen eine Ausnahme.

Beispiele

Einfache Abfrage: Ist der markierte Text fett?

// HTML: <div id="editor" contenteditable="true">Hallo <b>Welt</b></div>
const editor = document.getElementById('editor');
editor.focus();

// Das Wort „Welt“ markieren
const range = document.createRange();
range.selectNodeContents(editor.querySelector('b'));
const sel = window.getSelection();
sel.removeAllRanges();
sel.addRange(range);

console.log(document.queryCommandState('bold'));
console.log(document.queryCommandState('italic'));

true false

Werkzeugleiste passend zur Cursorposition hervorheben

// HTML:
// <div id="toolbar">
//   <button data-cmd="bold">F</button>
//   <button data-cmd="italic">K</button>
//   <button data-cmd="underline">U</button>
// </div>
// <div id="editor" contenteditable="true">Text hier bearbeiten …</div>
const toolbar = document.getElementById('toolbar');
const editor = document.getElementById('editor');
const buttons = [...toolbar.querySelectorAll('button[data-cmd]')];

const updateToolbar = () => {
  // Nur reagieren, wenn die Auswahl im Editor liegt
  const sel = document.getSelection();
  if (!sel.rangeCount || !editor.contains(sel.anchorNode)) return;

  for (const btn of buttons) {
    const active = document.queryCommandState(btn.dataset.cmd);
    btn.classList.toggle('active', active);
    btn.setAttribute('aria-pressed', String(active));
  }
};

toolbar.addEventListener('mousedown', (e) => e.preventDefault()); // Fokus im Editor halten
toolbar.addEventListener('click', (e) => {
  const cmd = e.target.dataset.cmd;
  if (!cmd) return;
  document.execCommand(cmd);
  updateToolbar();
});

document.addEventListener('selectionchange', updateToolbar);

Befehl umschalten, aber nur wenn er unterstützt wird

const toggleCommand = (cmd) => {
  if (!document.queryCommandSupported?.(cmd)) {
    console.warn(`Befehl „${cmd}“ wird nicht unterstützt`);
    return false;
  }
  const vorher = document.queryCommandState(cmd);
  document.execCommand(cmd);
  const nachher = document.queryCommandState(cmd);
  console.log(`${cmd}: ${vorher} → ${nachher}`);
  return nachher;
};

// Aufruf mit markiertem, nicht formatiertem Text im contenteditable-Bereich
toggleCommand('bold');

bold: false → true

// Wichtig · Fallstricke

Veraltet: Die ganze execCommand-Familie ist als deprecated eingestuft und nie vollständig standardisiert worden. Chrome, Edge, Firefox und Safari unterstützen sie zwar weiter, die Ergebnisse unterscheiden sich aber je nach Browser, z. B. bei gemischten Auswahlen wie „teilweise fett“. Für neue Projekte besser die Selection- und Range-API, beforeinput-Ereignisse oder einen fertigen Editor (ProseMirror, Lexical, TipTap) nehmen.
Nur in editierbaren Bereichen sinnvoll: Liegt die Auswahl außerhalb von contenteditable bzw. designMode, ist das Ergebnis normalerweise false, auch wenn der Text sichtbar fett ist.
CSS wird teils nicht erkannt: Ob Formatierung über CSS-Klassen (z. B. font-weight: 700) als aktiv zählt, hängt vom Browser ab. Mit execCommand('styleWithCSS', false, true) ändert sich zusätzlich das erzeugte Markup.
Werte-Befehle: Für fontSize, foreColor, formatBlock usw. ist queryCommandValue() die richtige Methode, queryCommandState() liefert dort nichts Brauchbares.
Fokus: Ein Klick auf einen Toolbar-Button nimmt dem Editor oft den Fokus und hebt die Auswahl auf. Deshalb bei mousedown preventDefault() aufrufen.
Firefox warf früher bei unbekannten Befehlen eine Ausnahme. Wer ältere Browser unterstützen muss, setzt einen try…catch um den Aufruf.

Siehe auch

Document.execCommand() Document.queryCommandEnabled() Document.queryCommandSupported() Document.designMode HTMLElement.contentEditable Selection