HTMLTextAreaElement.setRangeText() — Methode · JavaScript-Referenz

Signatur

HTMLTextAreaElement.prototype.setRangeText(replacement[, start, end[, selectMode]])

Beschreibung

Mit setRangeText() ersetzen Sie gezielt einen Teil des Inhalts eines <textarea>-Elements. Das ist komfortabler und robuster, als value per String-Slicing neu zusammenzusetzen, denn Sie müssen dabei weder selectionStart noch selectionEnd von Hand zurücksetzen.

Die Methode hat zwei Aufrufformen:

setRangeText(replacement) ersetzt die aktuelle Auswahl (selectionStart bis selectionEnd). Ist nichts ausgewählt, wird an der Cursorposition eingefügt.
setRangeText(replacement, start, end, selectMode) ersetzt den Bereich von start (inklusive) bis end (exklusive).

Typische Einsatzfälle sind Markdown- oder BBCode-Editoren (Auswahl in **…** einschließen), das Einfügen von Textbausteinen oder Emojis an der Cursorposition und Suchen-und-Ersetzen innerhalb eines Eingabefelds.

Mit dem Parameter selectMode legen Sie fest, wo Auswahl bzw. Cursor nach dem Ersetzen stehen: den neuen Text markieren ("select"), den Cursor davor ("start") oder dahinter ("end") setzen oder die bisherige Auswahl möglichst erhalten ("preserve", Standardwert).

Parameter

Name	Typ	Default	Beschreibung
$replacement Pflicht	string		Der Text, der eingefügt wird. Ein leerer String löscht den Bereich.
$start	number	selectionStart	Nullbasierter Index des ersten zu ersetzenden Zeichens. Wird nur zusammen mit `end` ausgewertet.
$end	number	selectionEnd	Index direkt nach dem letzten zu ersetzenden Zeichen (exklusiv). Werte größer als die Textlänge werden auf die Länge begrenzt.
$selectMode	"select" \| "start" \| "end" \| "preserve"	"preserve"	Legt die Auswahl nach dem Ersetzen fest: `"select"` markiert den neuen Text, `"start"` setzt den Cursor davor, `"end"` dahinter. `"preserve"` versucht, die bisherige Auswahl zu erhalten, und passt sie an die veränderte Textlänge an.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Methode ändert value sowie selectionStart/selectionEnd des Elements direkt.

Beispiele

Auswahl fett formatieren (Markdown-Editor)

const editor = document.querySelector('#editor');
const boldBtn = document.querySelector('#bold');

boldBtn.addEventListener('click', () => {
  const { selectionStart: start, selectionEnd: end, value } = editor;
  const selected = value.slice(start, end) || 'fetter Text';
  // Ersetzt die Auswahl und markiert das Ergebnis
  editor.setRangeText(`**${selected}**`, start, end, 'select');
  editor.focus();
});

Textbaustein an der Cursorposition einfügen

const textarea = document.querySelector('textarea');

const insertAtCursor = (el, text) => {
  el.setRangeText(text, el.selectionStart, el.selectionEnd, 'end');
  // Frameworks wie React/Vue über die Änderung informieren
  el.dispatchEvent(new Event('input', { bubbles: true }));
  el.focus();
};

document.querySelector('#signatur').addEventListener('click', () => {
  insertAtCursor(textarea, '\n\nMit freundlichen Grüßen\nMax Mustermann');
});

Festen Bereich ersetzen und selectMode vergleichen

const ta = document.createElement('textarea');
ta.value = 'Hallo Welt';
document.body.append(ta);

// Zeichen 6 bis 10 ("Welt") ersetzen
ta.setRangeText('JavaScript', 6, 10, 'select');
console.log(ta.value);
console.log(ta.selectionStart, ta.selectionEnd);

// Ohne Positionen: ersetzt die aktuelle Auswahl
ta.setRangeText('Web');
console.log(ta.value);

Hallo JavaScript 6 16 Hallo Web

Alle Vorkommen eines Worts ersetzen (von hinten nach vorn)

const ta = document.querySelector('textarea');
const search = 'foo';
const replacement = 'bar';

const positions = [...ta.value.matchAll(new RegExp(search, 'g'))].map(m => m.index);
// Von hinten nach vorn, damit frühere Indizes gültig bleiben
for (const pos of positions.reverse()) {
  ta.setRangeText(replacement, pos, pos + search.length, 'preserve');
}
console.log(`${positions.length} Ersetzungen`);

z. B. "3 Ersetzungen"

// Wichtig · Fallstricke

Kein input-Event: setRangeText() löst weder input noch change aus. Frameworks mit Datenbindung (React, Vue, Angular) bemerken die Änderung daher nicht. Lösen Sie bei Bedarf manuell el.dispatchEvent(new Event('input', { bubbles: true })) aus.
Kein Rückgängig-Verlauf: Programmatische Änderungen landen in den meisten Browsern nicht im Undo-Stack, Strg+Z macht sie also nicht rückgängig. Wenn die Undo-Funktion erhalten bleiben muss, bleibt nur das veraltete document.execCommand('insertText', …) als Notlösung.
Fehler: Ist start größer als end, wirft die Methode eine DOMException vom Typ IndexSizeError.
Indizes zählen UTF-16-Codeeinheiten: Emojis und andere Zeichen außerhalb der BMP belegen zwei Positionen. Ungünstig gewählte Grenzen können Surrogatpaare zerteilen.
Fokus: Die Methode setzt den Fokus nicht. Rufen Sie danach focus() auf, damit Cursor und Auswahl sichtbar werden.
Kompatibilität: Wird von allen modernen Browsern unterstützt, nicht aber vom Internet Explorer. Dieselbe Methode gibt es auch auf HTMLInputElement, dort allerdings nur für die Typen text, search, url, tel und password.

Siehe auch

HTMLTextAreaElement.select() HTMLTextAreaElement.reportValidity() HTMLTextAreaElement.checkValidity() HTMLTextAreaElement.setCustomValidity() HTMLTextAreaElement.setSelectionRange()