WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Selection.getRangeAt — einen Auswahlbereich abrufen

Selection.getRangeAt(0) gibt das Range-Objekt zurück, das mit der Dokumentauswahl verknüpft ist, nicht eine Kopie davon.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

selection.getRangeAt(index)

selection.getRangeAt(index) stellt den Bereich der Auswahl bereit. Dies ist eine browserbasierte Web-API und kein ECMAScript-Feature; Node 24 belegt keine Unterstützung.

Prüfe vor dem Aufruf mit Index 0, ob selection !== null und selection.rangeCount > 0 gelten. Laut Spezifikation muss die Methode IndexSizeError auslösen, wenn der Index nicht 0 ist, die Auswahl leer ist oder einer ihrer Endpunkte außerhalb des Dokumentbaums liegt. Browser halten sich nicht immer an diese Regel: Firefox kann mehrere Auswahlbereiche bereitstellen, sodass auch ein Index ungleich 0 funktionieren kann. Liegt ein Endpunkt in einem Shadow Tree, kannst du nicht davon ausgehen, dass der Browser diese Ausnahme auslöst. Auch eine auf einen Einfügecursor reduzierte Auswahl kann weiterhin einen Bereich haben.

Das Ergebnis ist eine Referenz: Änderungen am Bereich wirken sich auf die Auswahl aus, solange beide miteinander verknüpft bleiben. Wiederholte Aufrufe mit demselben Index geben dasselbe Objekt zurück, sofern der Bereich nicht ersetzt oder entfernt wurde. Die Spezifikation ist ein Working Draft und keine Browser-Kompatibilitätstabelle.

Beispiele

(() => {
  const selection = window.getSelection();
  if (!selection || !document.body) {
    throw new Error("An active browser document is required.");
  }

  const element = document.createElement("p");
  element.textContent = "Hello world";
  document.body.append(element);

  try {
    selection.removeAllRanges();
    const range = document.createRange();
    range.setStart(element.firstChild, 0);
    range.setEnd(element.firstChild, 5);
    selection.addRange(range);

    if (selection.rangeCount === 0) {
      throw new Error("No selection range is available.");
    }
    const selectedRange = selection.getRangeAt(0);
    console.log(selectedRange.toString());
    console.log(selectedRange === selection.getRangeAt(0));
  } finally {
    selection.removeAllRanges();
    element.remove();
  }
})();

Ergebnis

Hello
true

Code und Ausgabe wurden in einer isolierten Chromium-Umgebung überprüft. Das Beispiel ruft den einzigen Bereich mit Index `0` ab und prüft, ob der zweite Aufruf dasselbe Objekt zurückgibt. Andere Indizes und Endpunkte in einem Shadow Tree werden nicht getestet.

Quellen