Selection.setPosition() — Methode · JavaScript-Referenz

Signatur

Selection.prototype.setPosition(node, offset)

Beschreibung

Selection.setPosition() ist ein Alias für Selection.collapse(). Die Methode entfernt alle vorhandenen Bereiche aus der Auswahl und setzt stattdessen einen zusammengefallenen Bereich. Anfang und Ende liegen dabei auf demselben Punkt. In editierbaren Elementen (contenteditable) wird dort die Einfügemarke (der Cursor) angezeigt.

Wie offset ausgewertet wird, hängt vom Knotentyp ab: Bei Textknoten (Text, Comment, CDATASection) zählt er die Zeichen, genauer die UTF-16-Codeeinheiten. Bei allen anderen Knoten zählt er die Kindknoten. setPosition(el, 0) setzt den Cursor also vor das erste Kind von el. setPosition(el, el.childNodes.length) setzt ihn hinter das letzte Kind.

Typische Einsatzfälle sind Rich-Text-Editoren, Chat-Eingabefelder auf Basis von contenteditable und das Wiederherstellen einer Cursorposition, nachdem der Inhalt per Programm geändert wurde. Wenn Sie als node den Wert null übergeben, wird die Auswahl vollständig aufgehoben. Das entspricht removeAllRanges().

Parameter

Name	Typ	Default	Beschreibung
$node Pflicht	Node \| null		Knoten, in dem die Einfügemarke liegen soll. Bei `null` wird die Auswahl aufgehoben.
$offset	number	0	Position innerhalb von `node`. Bei Textknoten ist das die Anzahl der Zeichen (UTF-16-Codeeinheiten), bei anderen Knoten der Index unter den Kindknoten.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Cursor ans Ende eines contenteditable-Elements setzen

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

const selection = window.getSelection();
// Hinter das letzte Kind setzen
selection.setPosition(editor, editor.childNodes.length);

console.log(selection.isCollapsed, selection.type);

true "Caret"

Cursor an eine bestimmte Zeichenposition im Text setzen

// HTML: <p id="text" contenteditable>JavaScript ist toll</p>
const p = document.getElementById('text');
const textNode = p.firstChild; // Textknoten

p.focus();
// Cursor hinter "JavaScript" (10 Zeichen)
window.getSelection().setPosition(textNode, 10);

const sel = window.getSelection();
console.log(sel.anchorNode === textNode, sel.anchorOffset);

true 10

Cursorposition nach dem Neurendern wiederherstellen

const editor = document.querySelector('[contenteditable]');

const formatiere = () => {
  const sel = window.getSelection();
  // Aktuelle Position als Zeichenanzahl merken
  const range = sel.getRangeAt(0).cloneRange();
  range.selectNodeContents(editor);
  range.setEnd(sel.anchorNode, sel.anchorOffset);
  const pos = range.toString().length;

  // Inhalt neu setzen (z. B. nach Bereinigung)
  editor.textContent = editor.textContent.replace(/\s{2,}/g, ' ');

  // Position wiederherstellen (auf Textlänge begrenzen)
  const text = editor.firstChild;
  if (text) sel.setPosition(text, Math.min(pos, text.length));
};

editor.addEventListener('input', formatiere);

Auswahl vollständig aufheben

const sel = window.getSelection();
sel.setPosition(null);
console.log(sel.rangeCount);

// Wichtig · Fallstricke

Alias: setPosition() und collapse() verhalten sich identisch. Im Code ist collapse() verbreiteter, beide werden in allen modernen Browsern unterstützt.
IndexSizeError: Ist offset größer als die Länge des Knotens (bei Textknoten die Zeichenanzahl, sonst die Anzahl der Kindknoten), wird ein DOMException vom Typ IndexSizeError geworfen. Begrenzen Sie den Wert deshalb vorher, zum Beispiel mit Math.min().
Element oder Textknoten: Ein häufiger Fehler ist, ein Element statt seines Textknotens zu übergeben. Dann zählt offset die Kindknoten und nicht die Zeichen.
Fokus: Damit der Cursor sichtbar ist, muss das editierbare Element fokussiert sein. Rufen Sie also vorher element.focus() auf.
Formularfelder: Für <input> und <textarea> ist die Methode nicht geeignet. Dort verwenden Sie setSelectionRange().
Knoten in einem anderen Dokument: Gehört node zu einem anderen Dokument, ignorieren die Browser den Aufruf.
Emojis und Zeichen außerhalb der BMP: Solche Zeichen belegen zwei UTF-16-Codeeinheiten. Ein Offset in der Mitte eines Surrogat-Paars ist möglich, führt aber zu unerwartetem Verhalten.

Siehe auch

Selection.collapse() Selection.extend() Range Selection.toString() Selection.empty()