AbstractRange.collapsed — Eigenschaft · JavaScript-Referenz

Signatur

AbstractRange.collapsed

Beschreibung

Die Eigenschaft collapsed ist auf dem abstrakten Basis-Interface AbstractRange definiert und steht damit sowohl auf Range- als auch auf StaticRange-Objekten zur Verfügung. Sie liefert true, wenn startContainer und endContainer derselbe Knoten sind und startOffset gleich endOffset ist. Ein solcher „zusammengefallener“ Bereich enthält keinen Inhalt und entspricht einer reinen Einfügeposition, etwa der blinkenden Schreibmarke in einem editierbaren Element.

In der Praxis nutzt man collapsed vor allem, um zu unterscheiden, ob der Nutzer tatsächlich Text markiert hat oder nur den Cursor irgendwo platziert hat. Typische Anwendungsfälle sind Rich-Text-Editoren, Kontextmenüs für Markierungen („Zitieren“, „Teilen“) oder die Auswertung von beforeinput-Events über getTargetRanges(), die StaticRange-Objekte liefern.

Ein frisch mit document.createRange() oder new Range() erzeugter Bereich ist immer zusammengefallen (Start und Ende liegen am Anfang des Dokuments). Nach einem Aufruf von Range.prototype.collapse() ist collapsed ebenfalls true.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn Start- und Endpunkt des Bereichs übereinstimmen (leerer Bereich), sonst false.

Beispiele

Neuer Range ist zusammengefallen

const range = new Range();
console.log(range.collapsed); // Start = Ende

const p = document.createElement('p');
p.textContent = 'Hallo Welt';
range.selectNodeContents(p);
console.log(range.collapsed);

range.collapse(true); // auf Startpunkt zusammenziehen
console.log(range.collapsed);

true false true

Prüfen, ob der Nutzer Text markiert hat

document.addEventListener('selectionchange', () => {
  const selection = document.getSelection();
  if (!selection || selection.rangeCount === 0) return;

  const range = selection.getRangeAt(0);
  if (range.collapsed) {
    console.log('Nur Cursor gesetzt – keine Markierung');
  } else {
    console.log(`Markiert: "${range.toString()}"`);
  }
});

Nur Cursor gesetzt – keine Markierung Markiert: "Beispieltext"

StaticRange aus beforeinput auswerten

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

editor.addEventListener('beforeinput', (event) => {
  const [target] = event.getTargetRanges(); // StaticRange[]
  if (!target) return;

  if (target.collapsed) {
    console.log(`Einfügen an Position ${target.startOffset}`);
  } else {
    console.log('Ersetzt eine bestehende Auswahl');
  }
});

Einfügen an Position 5

StaticRange manuell erzeugen

const text = document.createTextNode('JavaScript');

const leer = new StaticRange({
  startContainer: text, startOffset: 4,
  endContainer: text, endOffset: 4
});
const teil = new StaticRange({
  startContainer: text, startOffset: 0,
  endContainer: text, endOffset: 4
});

console.log(leer.collapsed, teil.collapsed);

true false

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie range.collapsed = true hat keine Wirkung (im Strict Mode TypeError). Zum Zusammenziehen Range.prototype.collapse() verwenden.
Leer ≠ ohne sichtbaren Inhalt: Ein Bereich kann collapsed === false sein und trotzdem nur z. B. ein leeres Element oder Leerraum umfassen. range.toString() === '' ist daher nicht dasselbe wie collapsed.
StaticRange wird nicht aktualisiert: Bei StaticRange spiegelt collapsed den Zustand zum Erzeugungszeitpunkt wider; DOM-Änderungen danach werden nicht berücksichtigt. Ein Range dagegen passt sich live an.
Für die aktuelle Auswahl gibt es mit Selection.isCollapsed eine Abkürzung, ohne erst getRangeAt(0) aufzurufen.
Kompatibilität: Range.collapsed funktioniert in allen Browsern; das gemeinsame Basis-Interface AbstractRange und StaticRange gibt es in modernen Browsern (Chrome 90+, Firefox 69+, Safari 14.1+).

Siehe auch

Range Range.prototype.collapse() AbstractRange.endOffset AbstractRange.endContainer AbstractRange.startOffset