Selection.collapse() — Methode · JavaScript-Referenz

Signatur

Selection.prototype.collapse(node, offset)

Beschreibung

Selection.collapse() setzt die Auswahl auf einen einzigen Punkt zurück. Danach sind Anfang (anchor) und Ende (focus) der Auswahl identisch. Es wird also kein Text mehr markiert, übrig bleibt nur eine Einfügemarke (Caret). Ein vorher markierter Inhalt wird dabei nicht verändert, nur die Markierung wird aufgehoben.

Gebraucht wird die Methode vor allem bei Editoren mit contenteditable: Dort soll der Cursor gezielt an eine Stelle gesetzt werden, zum Beispiel nach dem Einfügen von Inhalt, beim Fokussieren eines Feldes oder nach einer Formatierung. Der Parameter offset hat je nach Knotentyp eine andere Bedeutung. Bei Textknoten zählt er die Zeichen (genauer: UTF-16-Codeeinheiten), bei Elementknoten die Kindknoten.

Wenn Sie null als Knoten übergeben, wird die Auswahl vollständig entfernt. Das wirkt genauso wie removeAllRanges(). setPosition() ist ein Alias von collapse() mit identischem Verhalten.

Parameter

Name	Typ	Default	Beschreibung
$node Pflicht	Node \| null		Knoten, in dem der Cursor liegen soll. Bei `null` wird die Auswahl vollständig aufgehoben.
$offset	number	0	Position innerhalb von `node`: bei Textknoten die Anzahl der Zeichen, bei Elementknoten die Anzahl der Kindknoten vor der Position.

Beispiele

Cursor ans Ende eines contenteditable-Elements setzen

const editor = document.querySelector('#editor'); // <div contenteditable>
editor.focus();

const selection = window.getSelection();
// Offset = Anzahl der Kindknoten → Position hinter dem letzten Kind
selection.collapse(editor, editor.childNodes.length);

console.log(selection.isCollapsed);

true

Cursor an eine bestimmte Zeichenposition im Text setzen

// <p id="text" contenteditable>Hallo Welt</p>
const p = document.querySelector('#text');
const textNode = p.firstChild; // Textknoten "Hallo Welt"

p.focus();
const sel = document.getSelection();
sel.collapse(textNode, 5); // Cursor direkt hinter "Hallo"

console.log(sel.anchorOffset, sel.focusOffset);

5 5

Markierung aufheben, aber Cursorposition am Auswahlanfang behalten

document.addEventListener('keydown', (event) => {
  if (event.key !== 'Escape') return;
  const sel = window.getSelection();
  if (sel.rangeCount === 0) return;

  const range = sel.getRangeAt(0);
  // Auf den Startpunkt zusammenklappen
  sel.collapse(range.startContainer, range.startOffset);
});

Auswahl komplett entfernen

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

// Wichtig · Fallstricke

IndexSizeError: Ist offset negativ oder größer als die Länge des Knotens (Zeichenanzahl bzw. childNodes.length), wirft die Methode eine DOMException vom Typ IndexSizeError.
InvalidNodeTypeError: Ein DocumentType-Knoten als node führt zu einem Fehler.
Liegt der Knoten in einem anderen Dokument als die Auswahl, ignorieren die meisten Browser den Aufruf, ohne einen Fehler zu melden.
offset zählt UTF-16-Codeeinheiten. Emojis und andere Zeichen außerhalb der BMP belegen zwei Einheiten. Mit einem ungeraden Offset kann der Cursor mitten in einem Zeichen landen.
Damit der Cursor in einem contenteditable-Element sichtbar wird, muss das Element meist vorher mit focus() fokussiert werden. Umgekehrt kann focus() die Auswahl neu setzen. Rufen Sie collapse() deshalb erst nach focus() auf.
Für <input> und <textarea> ist collapse() nicht geeignet. Dort verwenden Sie setSelectionRange().
Kompatibilität: Die Methode wird in allen modernen Browsern unterstützt. Ältere Implementierungen verlangten offset als Pflichtparameter, deshalb sollten Sie ihn immer angeben.

Siehe auch

Selection Range.collapse() Selection.collapseToEnd() Selection.addRange() Selection.collapseToStart()