Selection

Selection.anchorNode Schreibgeschützt

Gibt den Node zurück, in dem die Auswahl beginnt. Kann null zurückgeben, wenn die Auswahl nie im Dokument existierte (z.B. ein Iframe, das nie angeklickt wurde).

Selection.anchorOffset Schreibgeschützt

Gibt eine Zahl zurück, die den Versatz des Ankers der Auswahl innerhalb des anchorNode darstellt. Wenn anchorNode ein Textknoten ist, ist dies die Anzahl der Zeichen innerhalb des AnchorNode, die dem Anker vorausgehen. Wenn anchorNode ein Element ist, ist dies die Anzahl der Kindknoten des anchorNode, die dem Anker vorausgehen.

Selection.direction Schreibgeschützt

Ein String, der die Richtung der aktuellen Auswahl beschreibt.

Selection.focusNode Schreibgeschützt

Gibt den Node zurück, in dem die Auswahl endet. Kann null zurückgeben, wenn die Auswahl nie im Dokument existierte (zum Beispiel in einem iframe, das nie angeklickt wurde).

Selection.focusOffset Schreibgeschützt

Gibt eine Zahl zurück, die den Versatz des Fokus der Auswahl innerhalb des focusNode darstellt. Wenn focusNode ein Textknoten ist, ist dies die Anzahl der Zeichen innerhalb des focusNode, die dem Fokus vorausgehen. Wenn focusNode ein Element ist, ist dies die Anzahl der Kindknoten des focusNode, die dem Fokus vorausgehen.

Selection.isCollapsed Schreibgeschützt

Gibt einen Boolean zurück, der anzeigt, ob die Start- und Endpunkte der Auswahl an derselben Position sind.

Selection.rangeCount Schreibgeschützt

Gibt die Anzahl der Bereiche in der Auswahl zurück.

Selection.type Schreibgeschützt

Gibt einen String zurück, der den Typ der aktuellen Auswahl beschreibt.

Selection.addRange()

Ein Range-Objekt, das der Auswahl hinzugefügt wird.

Selection.collapse()

Faltet die aktuelle Auswahl zu einem einzelnen Punkt.

Selection.collapseToEnd()

Faltet die Auswahl bis zum Ende des letzten Bereichs in der Auswahl.

Selection.collapseToStart()

Faltet die Auswahl bis zum Anfang des ersten Bereichs in der Auswahl.

Selection.containsNode()

Gibt an, ob ein bestimmter Knoten Teil der Auswahl ist.

Selection.deleteFromDocument()

Löscht den Inhalt der Auswahl aus dem Dokument.

Selection.empty()

Entfernt alle Bereiche aus der Auswahl, sodass die Eigenschaften anchorNode und focusNode gleich null sind und nichts ausgewählt ist.

Selection.extend()

Verschiebt den Fokus der Auswahl zu einem bestimmten Punkt.

Selection.getComposedRanges() Experimentell

Gibt ein Array von StaticRange-Objekten zurück, die jeweils eine Auswahl repräsentieren, die Schatten-DOM-Grenzen überschreiten kann.

Selection.getRangeAt()

Gibt ein Range-Objekt zurück, das einen der derzeit ausgewählten Bereiche repräsentiert.

Selection.modify()

Ändert die aktuelle Auswahl.

Selection.removeRange()

Entfernt einen Bereich aus der Auswahl.

Selection.removeAllRanges()

Entfernt alle Bereiche aus der Auswahl.

Selection.selectAllChildren()

Fügt alle Kindknoten des angegebenen Knotens der Auswahl hinzu.

Selection.setBaseAndExtent()

Setzt die Auswahl auf einen Bereich, der alle oder Teile von zwei angegebenen DOM-Knoten und allen dazwischenliegenden Inhalt umfasst.

Selection.setPosition()

Faltet die aktuelle Auswahl zu einem einzelnen Punkt.

Selection.toString()

Gibt einen String zurück, der derzeit vom Auswahlobjekt repräsentiert wird, d.h. den derzeit ausgewählten Text.

Durch Aufrufen der Methode Selection.toString() wird der Text innerhalb der Auswahl zurückgegeben, z.B.:

const selObj = window.getSelection();
window.alert(selObj);

Beachten Sie, dass die Verwendung eines Auswahlobjekts als Argument für window.alert die toString-Methode des Objekts aufruft.

Ein Auswahlobjekt repräsentiert die vom Benutzer ausgewählten Range-Bereiche. Typischerweise enthält es nur einen Bereich, auf den wie folgt zugegriffen wird:

const selObj = window.getSelection();
const range = selObj.getRangeAt(0);

• selObj ist ein Selection-Objekt
• range ist ein Range-Objekt

Wie die Selection API-Spezifikation anmerkt, wurde die Selection API ursprünglich von Netscape erstellt und erlaubte mehrere Bereiche (um beispielsweise dem Benutzer zu erlauben, eine Spalte aus einem <table> auszuwählen). Allerdings implementierten Browser außer Gecko keine Mehrfachbereiche, und die Spezifikation erfordert auch, dass die Auswahl immer einen einzigen Bereich hat.

Auswahl und Eingabefokus (angezeigt durch Document.activeElement) haben eine komplexe Beziehung, die je nach Browser variiert. In plattformübergreifend kompatiblem Code ist es besser, sie separat zu behandeln.

Safari und Chrome (im Gegensatz zu Firefox) fokussieren derzeit das Element, das die Auswahl enthält, wenn die Auswahl programmatisch geändert wird; es ist möglich, dass sich dies in Zukunft ändern könnte (siehe W3C Bug 14383 und WebKit Bug 38696).

Die Selection API hat ein gemeinsames Verhalten (d.h. zwischen Browsern geteilt), das regelt, wie sich das Fokusverhalten für Bearbeitungs-Hosts nach dem Aufrufen bestimmter Methoden ändert.

Das Verhalten ist wie folgt:

1. Ein Bearbeitungs-Host erhält den Fokus, wenn die vorherige Auswahl außerhalb davon lag.
2. Eine Methode der Selection API wird aufgerufen, wodurch eine neue Auswahl mit dem Auswahlbereich innerhalb des Bearbeitungs-Hosts getroffen wird.
3. Der Fokus bewegt sich dann zum Bearbeitungs-Host.

Das oben genannte Verhalten gilt für Auswahlen, die mit den folgenden Methoden getroffen werden:

• Selection.collapse()
• Selection.collapseToStart()
• Selection.collapseToEnd()
• Selection.extend()
• Selection.selectAllChildren()
• Selection.addRange()
• Selection.setBaseAndExtent()

Und wenn das Range mit den folgenden Methoden geändert wird:

• Range.setStart()
• Range.setEnd()
• Range.setStartBefore()
• Range.setStartAfter()
• Range.setEndBefore()
• Range.setEndAfter()
• Range.collapse()
• Range.selectNode()
• Range.selectNodeContents()

Andere Schlüsselbegriffe, die in diesem Abschnitt verwendet werden.

Anker

Der Anker einer Auswahl ist der Anfangspunkt der Auswahl. Beim Treffen einer Auswahl mit der Maus ist der Anker der Punkt im Dokument, an dem die Maustaste zuerst gedrückt wird. Wenn der Benutzer die Auswahl mit der Maus oder der Tastatur ändert, bewegt sich der Anker nicht.

Bearbeitungs-Host

Ein bearbeitbares Element (z.B. ein HTML-Element, bei dem contenteditable gesetzt ist, oder das HTML-Kind eines Dokuments, bei dem designMode aktiviert ist).

Fokus einer Auswahl

Der Fokus einer Auswahl ist der Endpunkt der Auswahl. Beim Treffen einer Auswahl mit der Maus ist der Fokus der Punkt im Dokument, an dem die Maustaste losgelassen wird. Wenn der Benutzer die Auswahl mit der Maus oder der Tastatur ändert, ist der Fokus das Ende der Auswahl, das sich bewegt.

Hinweis: Dies ist nicht dasselbe wie das fokussierte Element des Dokuments, wie es von document.activeElement zurückgegeben wird.

Bereich

Ein Bereich ist ein zusammenhängender Teil eines Dokuments. Ein Bereich kann ganze Knoten sowie Teile von Knoten (z.B. einen Teil eines Textknotens) enthalten. Ein Benutzer wird normalerweise nur einen einzigen Bereich auf einmal auswählen, aber es ist möglich, dass ein Benutzer mehrere Bereiche auswählt (z.B. mit der Steuerung-Taste). Ein Bereich kann aus einer Auswahl als range-Objekt abgerufen werden. Bereichsobjekte können auch über das DOM erstellt und programmatisch zu einer Auswahl hinzugefügt oder daraus entfernt werden.

• Window.getSelection, Document.getSelection, Range
• Auswahlbezogene Ereignisse: selectionchange und selectstart
• HTML-Eingaben bieten einfachere Hilfs-APIs für die Arbeit mit Auswahlen (siehe HTMLInputElement.setSelectionRange())
• Document.activeElement, HTMLElement.focus, und HTMLElement.blur