new Range() — Methode · JavaScript-Referenz

Signatur

new Range()

Beschreibung

Der Konstruktor new Range() erzeugt ein neues Range-Objekt. Ein Range beschreibt einen zusammenhängenden Ausschnitt des DOM-Baums zwischen einem Start- und einem Endpunkt (jeweils Knoten + Offset). Direkt nach dem Erzeugen ist der Range zusammengefallen (collapsed === true): Anfang und Ende liegen beide bei Offset 0 des globalen document.

Man verwendet einen Range, um Textstellen oder Knotengruppen gezielt zu markieren, zu kopieren (cloneContents()), zu verschieben (extractContents()), zu löschen (deleteContents()), neue Knoten einzufügen (insertNode()) oder die Position eines Ausschnitts zu messen (getBoundingClientRect()). Zusammen mit der Selection-API lassen sich auch Benutzerauswahlen programmatisch setzen.

Funktional entspricht new Range() dem älteren document.createRange(). Der Unterschied: Der Konstruktor ist immer an das globale document des aktuellen Fensters gebunden, während createRange() auf jedem beliebigen Dokument (z. B. einem per DOMParser erzeugten oder dem Dokument eines iframes) aufgerufen werden kann. Nach dem Erzeugen legt man mit setStart()/setEnd(), selectNode() oder selectNodeContents() die tatsächlichen Grenzen fest.

Rückgabewert

Typ

Range

Beschreibung

Ein neues Range-Objekt, dessen startContainer und endContainer das globale document sind und dessen Offsets beide 0 betragen.

Beispiele

Range erzeugen und Ausgangszustand prüfen

const range = new Range();

console.log(range.startContainer === document); // Start liegt im Dokument
console.log(range.startOffset, range.endOffset);
console.log(range.collapsed); // Anfang == Ende

true 0 0 true

Textteil eines Absatzes hervorheben

// HTML: <p id="intro">Hallo schöne Welt</p>
const textNode = document.querySelector('#intro').firstChild;

const range = new Range();
range.setStart(textNode, 6);  // vor "schöne"
range.setEnd(textNode, 12);   // nach "schöne"

console.log(range.toString());

// Ausgewählten Text in <mark> einschließen
const mark = document.createElement('mark');
range.surroundContents(mark);
console.log(document.querySelector('#intro').innerHTML);

schöne Hallo <mark>schöne</mark> Welt

Inhalt eines Elements programmatisch auswählen

// z. B. für einen "Code markieren"-Button
const selectAll = (element) => {
  const range = new Range();
  range.selectNodeContents(element);

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

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

Position eines Textausschnitts messen

const heading = document.querySelector('h1');

const range = new Range();
range.selectNodeContents(heading);

// Tatsächliche Textbreite, unabhängig von der Elementbreite
const rect = range.getBoundingClientRect();
console.log(`Textbreite: ${Math.round(rect.width)}px`);

Textbreite: 312px

// Wichtig · Fallstricke

Gebunden an das globale Dokument: new Range() erzeugt immer einen Range im document des aktuellen Fensters. Für fremde Dokumente (iframe, DOMParser, document.implementation.createHTMLDocument()) stattdessen otherDoc.createRange() verwenden – sonst wird der Range beim ersten setStart() implizit umgehängt, was verwirrend sein kann.
Offsets hängen vom Knotentyp ab: Bei Text-, Kommentar- und CDATA-Knoten zählt der Offset Zeichen (UTF-16-Code-Units – Emojis zählen doppelt!), bei Elementen dagegen Kindknoten. Ein Offset außerhalb des gültigen Bereichs wirft eine IndexSizeError-DOMException.
surroundContents() wirft einen InvalidStateError, wenn der Range nur Teile eines Nicht-Text-Knotens umfasst; in diesem Fall extractContents() + appendChild() + insertNode() verwenden.
Ranges sind live: Wird das DOM verändert, passen sich die Grenzpunkte automatisch an. Für unveränderliche, performante Bereiche gibt es StaticRange.
Kompatibilität: Der Konstruktor wird von allen modernen Browsern unterstützt, nicht aber vom Internet Explorer – dort nur document.createRange() (ab IE 9). In Node.js steht Range nur mit DOM-Implementierungen wie jsdom zur Verfügung.

Siehe auch

Range Selection new CSSSkew() new Image() new File()