Selection.addRange() — Methode · JavaScript-Referenz

Signatur

Selection.prototype.addRange(range)

Beschreibung

Mit Selection.addRange() legen Sie per Skript fest, welcher Teil des Dokuments ausgewählt ist. Zuerst erzeugen Sie mit document.createRange() einen Range und legen seine Grenzen fest, zum Beispiel mit selectNodeContents(), setStart() oder setEnd(). Danach übergeben Sie ihn an die Selection, die Sie über window.getSelection() erhalten.

Typische Einsatzfälle sind „Alles markieren“-Schaltflächen für Codeblöcke, das Hervorheben von Suchtreffern, das Wiederherstellen einer gespeicherten Cursorposition in contenteditable-Editoren und das Vorbereiten von Text für die Zwischenablage.

In der Praxis sollten Sie vor addRange() fast immer removeAllRanges() aufrufen. Die meisten Browser unterstützen nur einen Range pro Selection. Ist schon ein Range vorhanden, wird der neue Aufruf dort ignoriert. Nur Firefox erlaubt mehrere Ranges gleichzeitig, etwa für Tabellenzellen oder Mehrfachauswahl mit Strg.

Parameter

Name	Typ	Default	Beschreibung
$range Pflicht	Range		Der `Range`, der zur Auswahl hinzugefügt wird. Er muss zu einem Dokument gehören, das mit der Selection verbunden ist.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Die Methode verändert die Selection direkt.

Beispiele

Inhalt eines Codeblocks per Klick markieren

const button = document.querySelector('#select-code');
const codeBlock = document.querySelector('pre code');

button.addEventListener('click', () => {
  const range = document.createRange();
  range.selectNodeContents(codeBlock);

  const selection = window.getSelection();
  selection.removeAllRanges(); // bestehende Auswahl entfernen
  selection.addRange(range);

  console.log(`Markiert: ${selection.toString().length} Zeichen`);
});

Markiert: 142 Zeichen

Cursor in contenteditable ans Ende setzen

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

const placeCaretAtEnd = (el) => {
  el.focus();
  const range = document.createRange();
  range.selectNodeContents(el);
  range.collapse(false); // auf das Ende zusammenfalten

  const sel = window.getSelection();
  sel.removeAllRanges();
  sel.addRange(range);
};

placeCaretAtEnd(editor);
console.log(window.getSelection().isCollapsed);

true

Ein Wort innerhalb eines Textknotens markieren

const p = document.querySelector('p'); // <p>Hallo schöne Welt</p>
const textNode = p.firstChild;
const word = 'schöne';
const start = textNode.textContent.indexOf(word);

if (start !== -1) {
  const range = document.createRange();
  range.setStart(textNode, start);
  range.setEnd(textNode, start + word.length);

  const sel = window.getSelection();
  sel.removeAllRanges();
  sel.addRange(range);
  console.log(sel.toString());
}

schöne

Auswahl speichern und später wiederherstellen

let savedRange = null;

const saveSelection = () => {
  const sel = window.getSelection();
  if (sel.rangeCount > 0) savedRange = sel.getRangeAt(0).cloneRange();
};

const restoreSelection = () => {
  if (!savedRange) return;
  const sel = window.getSelection();
  sel.removeAllRanges();
  sel.addRange(savedRange);
};

document.addEventListener('selectionchange', saveSelection);
document.querySelector('#restore').addEventListener('click', restoreSelection);

// Wichtig · Fallstricke

Mehrere Ranges: Nur Firefox unterstützt mehrere Ranges pro Selection. Chrome, Edge und Safari ignorieren addRange(), solange schon ein Range vorhanden ist. Rufen Sie deshalb vorher removeAllRanges() auf.
Referenz statt Kopie: Je nach Browser speichert die Selection eine Referenz auf den übergebenen Range. Spätere Änderungen am Range können also die sichtbare Auswahl verändern. Wenn das nicht gewollt ist, übergeben Sie range.cloneRange().
Eingabefelder: Für Text in <input> und <textarea> ist addRange() ungeeignet. Verwenden Sie dort setSelectionRange() oder select().
Fokus: In contenteditable-Elementen sollten Sie das Element vorher mit focus() fokussieren. Sonst erscheint der Cursor unter Umständen nicht oder die Auswahl geht verloren.
Soll nur eine Auswahl zwischen zwei Punkten gesetzt werden, ist Selection.setBaseAndExtent() oft die kürzere Alternative.
Ein Range aus einem anderen Dokument, etwa einem iframe, wird ignoriert. Verwenden Sie dort die Selection des jeweiligen Dokuments.

Siehe auch

Selection.removeAllRanges() Selection.removeRange() Selection.getRangeAt() Selection.setBaseAndExtent() Document.createRange() Window.getSelection() Range Selection