HTMLTextAreaElement.setSelectionRange() — Methode · JavaScript-Referenz

Signatur

HTMLTextAreaElement.prototype.setSelectionRange(selectionStart, selectionEnd, selectionDirection)

Beschreibung

Mit setSelectionRange() wählen Sie in einem <textarea> einen bestimmten Textbereich aus oder setzen den Cursor an eine bestimmte Stelle, ohne dass der Benutzer eingreifen muss. Ein Cursor ist dabei eine Auswahl, bei der Start und Ende gleich sind.

Die Positionen sind nullbasierte Indizes in UTF-16-Codeeinheiten innerhalb von textarea.value. Die Auswahl umfasst die Zeichen von selectionStart (einschließlich) bis selectionEnd (ausschließlich). Ist selectionEnd kleiner als selectionStart, werden beide auf selectionEnd gesetzt. Werte größer als die Textlänge werden auf die Länge begrenzt.

Typische Einsatzgebiete sind Editoren mit Formatierungs-Schaltflächen (z. B. Markdown-Toolbar), das Setzen des Cursors ans Textende nach dem Fokussieren, das Hervorheben von Suchtreffern oder Validierungsfehlern und das Wiederherstellen der Cursorposition nach programmatischen Änderungen am Wert.

Die Methode löst ein select-Ereignis aus. Damit die Auswahl sichtbar ist, sollte das Element in der Regel vorher mit focus() fokussiert werden.

Parameter

Name	Typ	Default	Beschreibung
$selectionStart Pflicht	number		Index des ersten ausgewählten Zeichens (nullbasiert). Werte größer als `value.length` werden auf die Länge begrenzt.
$selectionEnd Pflicht	number		Index nach dem letzten ausgewählten Zeichen. Ist der Wert kleiner als `selectionStart`, wird er als `selectionStart` behandelt.
$selectionDirection	"forward" \| "backward" \| "none"	"none"	Richtung der Auswahl, d. h. an welchem Ende der Cursor steht. Auf Plattformen ohne Richtungsunterscheidung verhält sich `"none"` meist wie `"forward"`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Cursor beim Fokussieren ans Textende setzen

const textarea = document.querySelector('#kommentar');
textarea.value = 'Hallo Welt,\nich schreibe weiter …';

textarea.focus();
const ende = textarea.value.length;
textarea.setSelectionRange(ende, ende);

console.log(textarea.selectionStart, textarea.selectionEnd);

30 30

Markdown-Toolbar: markierten Text fett machen

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

boldButton.addEventListener('click', () => {
  const { selectionStart: start, selectionEnd: end, value } = editor;
  const auswahl = value.slice(start, end) || 'fetter Text';

  editor.value = `${value.slice(0, start)}**${auswahl}**${value.slice(end)}`;

  // Eingefügten Text (ohne Sternchen) erneut auswählen
  editor.focus();
  editor.setSelectionRange(start + 2, start + 2 + auswahl.length);
});

Suchbegriff finden und rückwärts markieren

const textarea = document.querySelector('textarea');
textarea.value = 'Fehler: Die Variable x ist nicht definiert.';

const suchbegriff = 'Variable';
const index = textarea.value.indexOf(suchbegriff);

if (index !== -1) {
  textarea.focus();
  textarea.setSelectionRange(index, index + suchbegriff.length, 'backward');
  console.log(textarea.selectionDirection, textarea.value.substring(textarea.selectionStart, textarea.selectionEnd));
}

backward Variable

// Wichtig · Fallstricke

Fokus erforderlich für Sichtbarkeit: Ohne vorheriges focus() wird die Auswahl zwar gespeichert, ist aber meist nicht sichtbar. Manche Browser scrollen erst nach dem Fokussieren zur Auswahl.
Zeilenumbrüche: Im value werden Zeilenumbrüche immer als \n (ein Zeichen) gezählt, auch wenn beim Absenden \r\n übertragen wird.
UTF-16-Indizes: Emojis und andere Zeichen außerhalb der BMP belegen zwei Codeeinheiten. Wer mitten in ein Surrogatpaar schneidet, erzeugt eine fehlerhafte Auswahl.
Wert zuweisen setzt Cursor zurück: Nach textarea.value = … steht der Cursor am Ende. Merken Sie sich selectionStart/selectionEnd vorher und stellen Sie sie danach mit setSelectionRange() wieder her. Beachten Sie auch, dass direkte Wertzuweisungen den Undo-Verlauf zerstören – setRangeText() ist oft die bessere Wahl.
Löst ein select-Ereignis aus; Endlosschleifen vermeiden, wenn Sie in einem select-Handler erneut die Auswahl setzen.
Kompatibilität: Von allen modernen Browsern unterstützt. Auf iOS Safari wird die Auswahl teils nur innerhalb einer Benutzerinteraktion (z. B. Klick-Handler) angezeigt.

Siehe auch

HTMLTextAreaElement.selectionStart HTMLTextAreaElement.selectionEnd HTMLTextAreaElement.selectionDirection HTMLTextAreaElement.setRangeText() HTMLTextAreaElement.select() HTMLInputElement.setSelectionRange()