Selection.collapseToStart() — Methode · JavaScript-Referenz

Signatur

Selection.prototype.collapseToStart()

Beschreibung

collapseToStart() macht aus einer Textauswahl einen einfachen Cursor. Er steht danach am Anfang des ersten Bereichs der Auswahl. Ankerpunkt (anchorNode/anchorOffset) und Fokuspunkt (focusNode/focusOffset) liegen dann an derselben Stelle, und selection.isCollapsed ist true.

Die Richtung, in der die Nutzerin oder der Nutzer markiert hat, spielt keine Rolle. Auch bei einer Auswahl von rechts nach links landet der Cursor am Anfang im Dokument, also am startContainer/startOffset des Bereichs. Das Gegenstück ist collapseToEnd().

Typische Anwendungsfälle:

Rich-Text-Editoren mit contenteditable: Nach einer Aktion soll der Cursor vor dem zuvor markierten Text stehen.
Tastaturnavigation, z. B. soll die linke Pfeiltaste eine Auswahl aufheben und an den Anfang springen.
Eine Markierung aufheben, ohne dass die Position im Text verloren geht.

Die Methode ändert nur die Auswahl, nicht den Inhalt des Dokuments. Sie löst das Ereignis selectionchange am document aus.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Wenn die Auswahl leer ist (rangeCount === 0), wird eine DOMException vom Typ InvalidStateError geworfen.

Beispiele

Auswahl auf den Anfang reduzieren

// Den Inhalt eines Absatzes auswählen und dann auf den Anfang zusammenziehen
const p = document.createElement('p');
p.textContent = 'Hallo Welt';
document.body.append(p);

const selection = window.getSelection();
selection.selectAllChildren(p);
console.log(selection.toString(), selection.isCollapsed);

selection.collapseToStart();
console.log(selection.isCollapsed, selection.anchorOffset);

Hallo Welt false true 0

Sicherer Aufruf mit Prüfung auf eine leere Auswahl

const cursorAnDenAnfang = () => {
  const selection = document.getSelection();
  // Ohne Bereich würde InvalidStateError geworfen
  if (!selection || selection.rangeCount === 0) {
    console.log('Keine Auswahl vorhanden');
    return false;
  }
  selection.collapseToStart();
  return true;
};

document.getSelection()?.removeAllRanges();
console.log(cursorAnDenAnfang());

Keine Auswahl vorhanden false

Editor: Pfeil links hebt die Markierung auf und springt an den Anfang

// <div id="editor" contenteditable="true">Beispieltext zum Markieren</div>
const editor = document.querySelector('#editor');

editor.addEventListener('keydown', (event) => {
  const selection = document.getSelection();
  if (
    event.key === 'ArrowLeft' &&
    !event.shiftKey &&
    selection.rangeCount > 0 &&
    !selection.isCollapsed
  ) {
    event.preventDefault(); // Standardverhalten unterdrücken
    selection.collapseToStart();
  }
});

Werkzeugleisten-Button, der den Fokus nicht stiehlt

// <button id="toStart">Cursor an Auswahlanfang</button>
const button = document.querySelector('#toStart');

// mousedown verhindern, sonst verliert der Editor Fokus und Auswahl
button.addEventListener('mousedown', (event) => event.preventDefault());
button.addEventListener('click', () => {
  const selection = document.getSelection();
  if (selection.rangeCount > 0) selection.collapseToStart();
});

// Wichtig · Fallstricke

Leere Auswahl: Wenn rangeCount gleich 0 ist, wirft die Methode InvalidStateError. Prüfen Sie deshalb vorher selection.rangeCount > 0.
Formularfelder: Eine Textauswahl in <input> und <textarea> lässt sich darüber nicht steuern. Verwenden Sie dort el.setSelectionRange(el.selectionStart, el.selectionStart).
Mehrere Bereiche: Nur Firefox unterstützt mehrere Bereiche gleichzeitig (z. B. per Strg-Klick). In diesem Fall zählt der erste Bereich, alle anderen werden entfernt. Andere Browser kennen höchstens einen Bereich.
Fokusverlust: Ein Klick auf einen Button kann die Auswahl im Editor aufheben, bevor der click-Handler läuft. Abhilfe schafft preventDefault() bei mousedown.
Kompatibilität: Die Methode wird seit Langem von allen modernen Browsern unterstützt (Baseline). In Node.js gibt es sie nicht, nur in DOM-Umgebungen wie jsdom (eingeschränkt).

Siehe auch

Selection.collapse() Range.collapse() Selection Selection.collapseToEnd() Selection.containsNode()