Document.getSelection() — Methode · JavaScript-Referenz

Signatur

Document.prototype.getSelection()

Beschreibung

document.getSelection() liefert das Selection-Objekt, das zu diesem Dokument gehört. Es beschreibt, welchen Text die Nutzerin markiert hat oder wo die Einfügemarke (der Cursor) in bearbeitbaren Inhalten steht. Eine Auswahl kann aus einem oder mehreren Range-Objekten bestehen. In der Praxis unterstützt aber nur Firefox mehrere Bereiche.

Die Methode verhält sich wie window.getSelection(). Für das Hauptdokument geben beide dasselbe Objekt zurück. Nützlich ist sie für Funktionen wie „markierten Text zitieren“, Kontext-Toolbars in Editoren, eigene Kopier-Logik oder wenn man die Auswahl per Code setzen oder aufheben will (addRange(), removeAllRanges(), selectAllChildren()).

Wichtig: Das zurückgegebene Objekt ist live. Es ist bei jedem Aufruf dasselbe Objekt und zeigt immer die aktuelle Auswahl. Wer einen bestimmten Zustand festhalten will, muss sich den Text (toString()) oder eine Kopie des Bereichs (getRangeAt(0).cloneRange()) sichern.

Rückgabewert

Typ

Selection | null

Beschreibung

Das live aktualisierte Selection-Objekt des Dokuments. Kann null sein, etwa bei einem Dokument ohne Browsing-Kontext (z. B. ein iframe mit display: none in Firefox oder ein per DOMParser erzeugtes Dokument).

Beispiele

Markierten Text auslesen

document.addEventListener('mouseup', () => {
  const selection = document.getSelection();
  const text = selection?.toString().trim() ?? '';
  if (text) {
    console.log(`Markiert: "${text}" (${selection.rangeCount} Bereich/e)`);
  }
});

Markiert: "Hallo Welt" (1 Bereich/e)

Auswahl beobachten mit selectionchange

const info = document.querySelector('#auswahl-info');

document.addEventListener('selectionchange', () => {
  const sel = document.getSelection();
  if (!sel || sel.isCollapsed) {
    info.textContent = 'Keine Auswahl';
    return;
  }
  info.textContent = `${sel.toString().length} Zeichen markiert`;
});

Inhalt eines Elements per Code markieren und kopieren

const selectCode = async (element) => {
  const sel = document.getSelection();
  sel.removeAllRanges();
  sel.selectAllChildren(element);

  await navigator.clipboard.writeText(sel.toString());
  console.log('In die Zwischenablage kopiert:', sel.toString());
};

document.querySelector('#copy-btn')
  .addEventListener('click', () => selectCode(document.querySelector('pre code')));

In die Zwischenablage kopiert: const x = 1;

Auswahl sichern und später wiederherstellen

let gespeicherterBereich = null;

const auswahlSichern = () => {
  const sel = document.getSelection();
  if (sel && sel.rangeCount > 0) {
    // Kopie anlegen, da Selection live ist
    gespeicherterBereich = sel.getRangeAt(0).cloneRange();
  }
};

const auswahlWiederherstellen = () => {
  if (!gespeicherterBereich) return;
  const sel = document.getSelection();
  sel.removeAllRanges();
  sel.addRange(gespeicherterBereich);
};

// z. B. vor dem Öffnen eines Dialogs sichern, danach wiederherstellen
auswahlSichern();
auswahlWiederherstellen();

// Wichtig · Fallstricke

Formularfelder: In <input> und <textarea> liefert getSelection().toString() in Firefox (und je nach Kontext auch anderswo) einen leeren String. Nutze dort selectionStart/selectionEnd des Elements, z. B. el.value.slice(el.selectionStart, el.selectionEnd).
Live-Objekt: Mehrere Aufrufe geben dasselbe Objekt zurück. Wer einen Zustand festhalten will, muss den Text oder eine Kopie des Bereichs (cloneRange()) sichern.
Fokusverlust: Ein Klick auf einen Button kann die Auswahl aufheben. Sichere sie deshalb bei mousedown/selectionchange oder verhindere den Fokuswechsel mit event.preventDefault() im mousedown-Handler.
Shadow DOM: Bei Auswahlen innerhalb eines Shadow Trees zeigt document.getSelection() auf den Host-Knoten. Mit selection.getComposedRanges() (neuere Browser) bekommt man die Bereiche im Shadow Tree.
Mehrere Bereiche: Nur Firefox unterstützt mehrere Bereiche (Strg+Auswahl). Andere Browser haben höchstens einen Bereich (rangeCount ist 0 oder 1).
Rückgabe null: Vor dem Zugriff mit optionaler Verkettung (?.) prüfen, besonders bei iframe-Dokumenten.
Sicherheit: Markierten Text nie ungeprüft per innerHTML einfügen. Verwende textContent, um XSS zu vermeiden.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Das Event selectionchange ist ebenfalls breit verfügbar.

Siehe auch

Window.getSelection() Selection Range Selection.getRangeAt() Selection.removeAllRanges() HTMLInputElement.selectionStart