Selection.rangeCount — Eigenschaft · JavaScript-Referenz

Signatur

Selection.rangeCount

Beschreibung

Selection.rangeCount liefert die Anzahl der Bereiche (Range-Objekte), aus denen eine Auswahl besteht. Nach dem Laden der Seite ist der Wert meist 0, solange der Nutzer nichts angeklickt oder markiert hat. Sobald der Nutzer irgendwo in das Dokument klickt, ist der Wert in der Regel 1 – auch wenn die Auswahl zugeklappt ist (nur ein Textcursor ohne markierten Text).

Wichtig ist die Eigenschaft vor allem als Schutzprüfung vor getRangeAt(): Ruft man selection.getRangeAt(0) bei rangeCount === 0 auf, wird ein IndexSizeError ausgelöst. Deshalb prüft man zuerst rangeCount > 0, bevor man auf einen Bereich zugreift, etwa um markierten Text hervorzuheben, einen Rich-Text-Editor zu steuern oder die Cursor-Position zu speichern.

Laut Spezifikation kann eine Auswahl höchstens einen Bereich enthalten; der Wert ist also praktisch immer 0 oder 1. Nur Firefox unterstützt Mehrfachauswahlen (z. B. mit gedrückter Strg-Taste oder beim Markieren von Tabellenspalten) und kann daher Werte größer als 1 liefern.

Rückgabewert

Typ

number

Beschreibung

Eine nicht-negative ganze Zahl: 0, wenn keine Auswahl existiert, sonst die Anzahl der Bereiche (in Chrome/Safari höchstens 1, in Firefox auch mehr).

Beispiele

Sicherer Zugriff auf den ersten Bereich

const getSelectedRange = () => {
  const selection = window.getSelection();
  // Ohne diese Prüfung wirft getRangeAt(0) einen IndexSizeError
  if (!selection || selection.rangeCount === 0) return null;
  return selection.getRangeAt(0);
};

const range = getSelectedRange();
console.log(range ? `Markiert: "${range.toString()}"` : 'Keine Auswahl vorhanden');

Keine Auswahl vorhanden

Markierten Text beim Loslassen der Maus hervorheben

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

  const range = selection.getRangeAt(0);
  const mark = document.createElement('mark');
  try {
    range.surroundContents(mark);
  } catch (err) {
    // surroundContents scheitert, wenn der Bereich Elementgrenzen schneidet
    console.warn('Auswahl überspannt mehrere Elemente:', err.message);
  }
  selection.removeAllRanges();
});

Alle Bereiche durchlaufen (Mehrfachauswahl in Firefox)

const logAllRanges = () => {
  const selection = window.getSelection();
  console.log(`Anzahl Bereiche: ${selection.rangeCount}`);
  for (let i = 0; i < selection.rangeCount; i++) {
    console.log(`Bereich ${i}:`, selection.getRangeAt(i).toString());
  }
};

document.querySelector('#analyse')?.addEventListener('click', logAllRanges);

Anzahl Bereiche: 1 Bereich 0: markierter Text

Cursor-Position speichern und wiederherstellen

let savedRange = null;

const saveCaret = () => {
  const sel = window.getSelection();
  savedRange = sel.rangeCount > 0 ? sel.getRangeAt(0).cloneRange() : null;
};

const restoreCaret = () => {
  if (!savedRange) return;
  const sel = window.getSelection();
  sel.removeAllRanges();
  sel.addRange(savedRange);
  console.log('Wiederhergestellt, rangeCount =', sel.rangeCount);
};

const editor = document.querySelector('[contenteditable]');
editor?.addEventListener('blur', saveCaret);
editor?.addEventListener('focus', restoreCaret);

Wiederhergestellt, rangeCount = 1

// Wichtig · Fallstricke

Nicht mit isCollapsed verwechseln: Ein reiner Textcursor ergibt rangeCount === 1, obwohl kein Text markiert ist. Wer markierten Text braucht, prüft zusätzlich selection.isCollapsed oder selection.toString() !== ''.
getRangeAt() nur nach Prüfung aufrufen: Bei rangeCount === 0 wirft getRangeAt(0) eine DOMException (IndexSizeError).
Mehrfachauswahl: Nur Firefox liefert Werte größer als 1. Chrome und Safari ignorieren weitere Aufrufe von addRange(), solange schon ein Bereich existiert; vorher also removeAllRanges() aufrufen.
Formularfelder: Markierungen innerhalb von <input> und <textarea> lassen sich darüber nicht zuverlässig auslesen – hier selectionStart/selectionEnd verwenden.
Shadow DOM: Bei Auswahlen in Shadow Roots können die Bereiche je nach Browser auf den Host umgebogen sein; ggf. getComposedRanges() nutzen, wo verfügbar.
Die Eigenschaft wird von allen modernen Browsern unterstützt; window.getSelection() kann in einem iframe mit display: none in Firefox null liefern – daher optional verketten.

Siehe auch

Selection Selection.getRangeAt() Selection.addRange() Selection.removeAllRanges() Selection.isCollapsed Window.getSelection() Range