Range.collapse() — Methode · JavaScript-Referenz

Signatur

Range.prototype.collapse(toStart)

Beschreibung

collapse() setzt eine Range auf einen einzelnen Punkt im Dokument zusammen. Danach sind Start- und Endpunkt identisch, und die Eigenschaft collapsed liefert true. Mit toStart = true wird der Endpunkt auf den Startpunkt verschoben, mit false (Standard) der Startpunkt auf den Endpunkt.

Typische Einsatzfälle sind Texteditoren und contenteditable-Bereiche: Man platziert den Cursor (Caret) gezielt an den Anfang oder das Ende eines Elements, oder hebt eine Auswahl auf, ohne die Position zu verlieren. Ebenso nützlich ist die Methode, um nach insertNode() eine Einfügeposition hinter dem eingefügten Knoten zu setzen.

Eine zusammengefallene Range umfasst keinen Inhalt – toString() liefert dann einen leeren String und deleteContents() bewirkt nichts. Die Methode verändert die Range direkt und gibt nichts zurück.

Parameter

Name	Typ	Default	Beschreibung
$toStart	boolean	false	`true` fällt auf den Startpunkt zusammen, `false` auf den Endpunkt.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined); die Range wird direkt verändert.

Beispiele

Range auf Anfang bzw. Ende zusammenfallen lassen

const p = document.createElement('p');
p.textContent = 'Hallo Welt';
document.body.append(p);

const range = document.createRange();
range.selectNodeContents(p);
console.log(range.toString(), range.collapsed);

range.collapse(true); // auf den Anfang
console.log(range.toString() === '', range.collapsed, range.startOffset);

Hallo Welt false true true 0

Cursor ans Ende eines contenteditable-Elements setzen

const placeCaretAtEnd = (el) => {
  el.focus();
  const range = document.createRange();
  range.selectNodeContents(el);
  range.collapse(false); // auf das Ende
  const sel = window.getSelection();
  sel.removeAllRanges();
  sel.addRange(range);
};

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

Nach dem Einfügen hinter den neuen Knoten springen

const insertAtCaret = (node) => {
  const sel = window.getSelection();
  if (!sel.rangeCount) return;
  const range = sel.getRangeAt(0);
  range.deleteContents();
  range.insertNode(node);
  range.setStartAfter(node);
  range.collapse(true); // Caret direkt hinter dem Knoten
  sel.removeAllRanges();
  sel.addRange(range);
};

insertAtCaret(document.createTextNode('😀'));

// Wichtig · Fallstricke

Der Standardwert von toStart ist false. Sehr alte Browser (Legacy-Gecko) verlangten den Parameter zwingend – für maximale Kompatibilität besser immer explizit angeben.
Eine Range aus Selection.getRangeAt() ist live mit der Auswahl verknüpft; wie sich Änderungen an dieser Range auf die sichtbare Auswahl auswirken, unterscheidet sich je nach Browser. Nach der Änderung sicherheitshalber mit removeAllRanges() und addRange() neu setzen.
Für eine Auswahl gibt es ähnliche Methoden: Selection.collapse(), collapseToStart() und collapseToEnd().
Wird in allen modernen Browsern unterstützt.

Siehe auch

Range Selection.collapse() Range.isPointInRange() Range.cloneRange() Range.compareNode()