Dokument: execCommand()-Methode

Syntax

execCommand(commandName, showDefaultUI, valueArgument)

Parameter

commandName

Ein String, der den Namen des auszuführenden Befehls angibt. Die folgenden Befehle sind spezifiziert:

backColor

Ändert die Hintergrundfarbe des Dokuments. Im styleWithCss-Modus wirkt es sich stattdessen auf die Hintergrundfarbe des enthaltenden Blocks aus. Dies erfordert einen <color>-Wert als Argument.

bold

Schaltet Fettung für die Auswahl oder an der Einfügemarke ein/aus.

contentReadOnly

Macht das Inhaltsdokument entweder schreibgeschützt oder bearbeitbar. Dies erfordert einen Booleschen Wert true/false als Argument.

copy

Kopiert die aktuelle Auswahl in die Zwischenablage. Die Bedingungen, unter denen dieses Verhalten aktiviert ist, variieren von Browser zu Browser und haben sich im Laufe der Zeit entwickelt. Überprüfen Sie die Kompatibilitätstabelle, um festzustellen, ob Sie es in Ihrem Fall verwenden können.

createLink

Erstellt einen Hyperlink aus der Auswahl, aber nur, wenn eine Auswahl vorhanden ist. Erfordert eine URI-Zeichenfolge als Wertargument für den href des Hyperlinks. Der URI muss mindestens ein Zeichen enthalten, das Leerzeichen sein kann.

cut

Entfernt die aktuelle Auswahl und kopiert sie in die Zwischenablage. Wann dieses Verhalten aktiviert ist, variiert zwischen den Browsern und die Bedingungen haben sich im Laufe der Zeit entwickelt. Überprüfen Sie die Kompatibilitätstabelle für Nutzungshinweise.

decreaseFontSize

Fügt ein <small>-Tag um die Auswahl oder an der Einfügemarke hinzu.

defaultParagraphSeparator

Ändert den Absatztrenner, der beim Erstellen neuer Absätze in bearbeitbaren Textbereichen verwendet wird.

delete

Löscht die aktuelle Auswahl.

enableAbsolutePositionEditor

Aktiviert oder deaktiviert den Greifer, mit dem absolut positionierte Elemente verschoben werden können. Der Greifer ist standardmäßig seit Firefox 64 (Firefox-Fehler 1490641) deaktiviert.

enableInlineTableEditing

Aktiviert oder deaktiviert die Steuerelemente zum Einfügen und Löschen von Tabellenzeilen/-spalten. Die Steuerelemente sind standardmäßig seit Firefox 64 (Firefox-Fehler 1490641) deaktiviert.

enableObjectResizing

Aktiviert oder deaktiviert die Größenanpassungsgriffe für Bilder, Tabellen und absolut positionierte Elemente sowie andere skalierbare Objekte. Die Griffe sind standardmäßig seit Firefox 64 (Firefox-Fehler 1490641) deaktiviert.

fontName

Ändert den Schriftartnamen für die Auswahl oder an der Einfügemarke. Dies erfordert eine Schriftartnamen-String (wie "Arial") als Argument.

fontSize

Ändert die Schriftgröße für die Auswahl oder an der Einfügemarke. Dies erfordert eine ganze Zahl von 1 - 7 als Argument.

foreColor

Ändert die Schriftfarbe für die Auswahl oder an der Einfügemarke. Dies erfordert einen hexadezimalen Farbwert als Argument.

formatBlock

Fügt ein HTML-Blockelement um die Zeile mit der aktuellen Auswahl hinzu und ersetzt dabei das Blockelement, das die Zeile enthält (in Firefox ist <blockquote> eine Ausnahme - es umschließt jedes enthaltende Blockelement). Erfordert einen Tag-Name-String als Argument. Nahezu alle Blockelemente können verwendet werden. (Legacy Edge unterstützt nur die Überschrift-Tags H1 – H6, ADDRESS und PRE, die in spitze Klammern gesetzt sein müssen, z.B. "<H1>".)

forwardDelete

Löscht das Zeichen vor der Cursorposition, identisch mit dem Drücken der Entf-Taste auf einer Windows-Tastatur.

heading

Fügt ein Überschriftselement um eine Auswahl oder Einfügemarken-Zeile hinzu. Erfordert den Tag-Namen-String als Argument (z.B. "H1", "H6"). (Nicht von Safari unterstützt.)

highlightColor

Ändert die Hintergrundfarbe für die Auswahl oder an der Einfügemarke. Erfordert einen Farbwert als Argument. useCSS muss true sein, damit dies funktioniert.

increaseFontSize

Fügt einen <big>-Tag um die Auswahl oder an der Einfügemarke hinzu.

indent

Rückt die Zeile mit der Auswahl oder Einfügemarke ein. In Firefox werden bei Auswahl mehrerer Zeilen auf verschiedenen Einrückungsebenen nur die am wenigsten eingerückten Zeilen in der Auswahl eingerückt.

insertBrOnReturn

Steuert, ob die Eingabetaste ein <br>-Element einfügt oder das aktuelle Blockelement in zwei teilt.

insertHorizontalRule

Fügt ein <hr>-Element an der Einfügemarke ein oder ersetzt die Auswahl damit.

insertHTML

Fügt eine TrustedHTML-Instanz oder HTML-Markup-String an der Einfügemarke ein (löscht Auswahl). Dies erfordert gültiges HTML-Markup.

Warnung: Die Eingabe wird als HTML geparst und in das DOM geschrieben. Solche APIs sind als Injection-Sinks bekannt und sind potenziell ein Vektor für Cross-Site-Scripting (XSS)-Angriffe, wenn die Eingabe ursprünglich von einem Angreifer stammt.

Sie können dieses Risiko mindern, indem Sie immer TrustedHTML-Objekte anstelle von Strings zuweisen und vertrauenswürdige Typen erzwingen. Weitere Informationen finden Sie in der Trusted Types API.

insertImage

Fügt ein Bild an der Einfügemarke ein (löscht Auswahl). Erfordert eine URL-String für den src des Bildes als Argument. Die Anforderungen an diesen String sind die gleichen wie bei createLink.

insertOrderedList

Erstellt eine nummerierte geordnete Liste für die Auswahl oder an der Einfügemarke.

insertUnorderedList

Erstellt eine Aufzählungsliste für die Auswahl oder an der Einfügemarke.

insertParagraph

Fügt einen Absatz um die Auswahl oder die aktuelle Zeile hinzu.

insertText

Fügt den angegebenen reinen Text an der Einfügemarke ein (löscht Auswahl).

italic

Schaltet Kursivierung für die Auswahl oder an der Einfügemarke ein/aus.

justifyCenter

Zentriert die Auswahl oder die Einfügemarke.

justifyFull

Blocksatzausrichtung für die Auswahl oder die Einfügemarke.

justifyLeft

Linksbündige Ausrichtung für die Auswahl oder die Einfügemarke.

justifyRight

Rechtsbündige Ausrichtung für die Auswahl oder die Einfügemarke.

outdent

Hängt die Zeile mit der Auswahl oder Einfügemarke aus.

paste

Fügt den Inhalt der Zwischenablage an der Einfügemarke ein (ersetzt die aktuelle Auswahl).

Diese Funktion ist für Webinhalt standardmäßig deaktiviert, wurde jedoch in einigen Browsern über die Clipboard API implementiert. In diesen Browsern erfordert die Funktion transiente Aktivierung und die Bestätigung eines Popup-UIs beim Einfügen von Inhalten aus verschiedenen Ursprungskontexten. Siehe die Browser-Kompatibilitätstabelle für weitere Informationen.

redo

Wiederholt den letzten Rückgängig-Befehl.

removeFormat

Entfernt alle Formatierungen aus der aktuellen Auswahl.

selectAll

Wählt den gesamten Inhalt des bearbeitbaren Bereichs aus.

strikeThrough

Schaltet Durchstreichung für die Auswahl oder an der Einfügemarke ein/aus.

subscript

Schaltet Tiefstelligkeit für die Auswahl oder an der Einfügemarke ein/aus.

superscript

Schaltet Hochstelligkeit für die Auswahl oder an der Einfügemarke ein/aus.

underline

Schaltet Unterstreichung für die Auswahl oder an der Einfügemarke ein/aus.

undo

Macht den letzten ausgeführten Befehl rückgängig.

unlink

Entfernt das Ankerelement von einem ausgewählten Hyperlink.

useCSS Veraltet

Schaltet die Verwendung von HTML-Tags oder CSS für das generierte Markup um. Erfordert einen booleschen true/false als Argument.

Hinweis: Dieses Argument ist logischerweise rückwärts (d.h. verwenden Sie false, um CSS zu verwenden, true, um HTML zu verwenden). Dies wurde zugunsten von styleWithCSS veraltet.

styleWithCSS

Ersetzt den Befehl useCSS. true ändert/erzeugt style-Attribute im Markup, false erzeugt Präsentationselemente.

AutoUrlDetect

Ändert das automatische Verlinkungs-Verhalten des Browsers.

showDefaultUI

Ein boolescher Wert, der angibt, ob die standardmäßige Benutzeroberfläche angezeigt werden soll. Dies ist in Mozilla nicht verfügbar.

valueArgument

Für Befehle, die ein Eingabeargument erfordern, ist dies ein String, der diese Information bereitstellt. Zum Beispiel benötigt insertImage die URL des einzufügenden Bildes. Geben Sie null an, wenn kein Argument erforderlich ist.

Rückgabewert

Ein boolescher Wert, der false ist, wenn der Befehl nicht unterstützt oder deaktiviert ist.

Beispiele

Verwendung von insertText

Dieses Beispiel zeigt zwei sehr einfache HTML-Editoren, einen mit einem <textarea>-Element und einen mit einem <pre>-Element, das das contenteditable-Attribut gesetzt hat.

Das Klicken auf die Schaltflächen "Fett" oder "Kursiv" fügt die entsprechenden Tags im Element ein, wobei insertText verwendet wird, um die Bearbeitungshistorie beizubehalten, sodass der Benutzer die Aktion rückgängig machen kann.

HTML

<h2>textarea</h2>

<div class="actions" data-for="textarea">
  <button data-el="b">Bold</button>
  <button data-el="i">Italic</button>
</div>

<textarea class="editarea">Some text.</textarea>

<h2>contenteditable</h2>

<div class="actions" data-for="pre">
  <button data-el="b">Bold</button>
  <button data-el="i">Italic</button>
</div>

<pre contenteditable="true" class="editarea">Some text.</pre>

JavaScript

// Prepare action buttons
const buttonContainers = document.querySelectorAll(".actions");

for (const buttonContainer of buttonContainers) {
  const buttons = buttonContainer.querySelectorAll("button");
  const pasteTarget = buttonContainer.getAttribute("data-for");

  for (const button of buttons) {
    const elementName = button.getAttribute("data-el");
    button.addEventListener("click", () =>
      insertText(`<${elementName}></${elementName}>`, pasteTarget),
    );
  }
}

// Inserts text at cursor, or replaces selected text
function insertText(newText, selector) {
  const textarea = document.querySelector(selector);
  textarea.focus();

  let pasted = true;
  try {
    if (!document.execCommand("insertText", false, newText)) {
      pasted = false;
    }
  } catch (e) {
    console.error("error caught:", e);
    pasted = false;
  }

  if (!pasted) {
    console.error("paste unsuccessful, execCommand not supported");
  }
}

Ergebnis

Verwendung von paste

Dieses Beispiel enthält ein <textarea>-Element und ein <button>-Element, das verwendet werden kann, um Inhalte in dieses einzufügen.

HTML

<button id="paste">Paste</button>
<hr />
<textarea id="text_box">Some text.</textarea>

JavaScript

const pasteButton = document.querySelector("#paste");
const textBox = document.querySelector("#text_box");

pasteButton.addEventListener("click", () => {
  textBox.focus();

  let pasted = document.execCommand("paste", false);
  if (!pasted) {
    textBox.textContent = "paste unsuccessful, execCommand not supported";
  }
});

Ergebnis

In Browsern, die diese Funktion mithilfe der Clipboard API implementieren, sollten Sie in der Lage sein, Inhalte aus dem gleichen Ursprungsbereich, wie Text aus dem Textbereich, zu kopieren und dann einzufügen, um den ausgewählten Inhalt zu ersetzen. Wenn Sie versuchen, Inhalte aus fremden Ursprungskontexten einzufügen, wie z.B. Text, der von einer anderen Seite oder einem anderen Ort kopiert wurde, müssen Sie zuerst die "Einfügen"-UI auswählen, die angezeigt wird.

Spezifikationen

Diese Funktion ist Teil keiner aktuellen Spezifikation. Sie ist nicht mehr auf dem Weg, ein Standard zu werden. Es gibt einen inoffiziellen W3C execCommand Spec-Entwurf.

Browser-Kompatibilität

Siehe auch

• Clipboard API
• MDN-Beispiel: execCommands in Ihrem Browser unterstützt
• HTMLElement.contentEditable
• document.designMode
• document.queryCommandEnabled()
• document.queryCommandState()
• document.queryCommandSupported()