Selection

Selection.anchorNode Schreibgeschützt

Gibt den Node zurück, in dem die Auswahl beginnt. Kann null zurückgeben, wenn nie eine Auswahl im Dokument vorhanden war (z.B. ein iframe, auf das nie geklickt wurde).

Selection.anchorOffset Schreibgeschützt

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

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 nie eine Auswahl im Dokument vorhanden war (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 angibt. Wenn focusNode ein Textknoten ist, ist dies die Anzahl der Zeichen innerhalb von focusNode vor dem Fokus. Wenn focusNode ein Element ist, ist dies die Anzahl der Kindknoten des focusNode vor dem Fokus.

Selection.isCollapsed Schreibgeschützt

Gibt einen Boolean-Wert zurück, der angibt, 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 zur Auswahl hinzugefügt wird.

Selection.collapse()

Bricht die aktuelle Auswahl auf einen einzigen Punkt zusammen.

Selection.collapseToEnd()

Bricht die Auswahl am Ende des letzten Bereichs in der Auswahl zusammen.

Selection.collapseToStart()

Bricht die Auswahl am Anfang des ersten Bereichs in der Auswahl zusammen.

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 anchorNode und focusNode-Eigenschaften gleich null sind und nichts ausgewählt ist.

Selection.extend()

Verschiebt den Fokus der Auswahl an einen angegebenen Punkt.

Selection.getComposedRanges() Experimentell

Gibt ein Array von StaticRange-Objekten zurück, von denen jedes eine Auswahl darstellt, die DOM-Grenzen überschreiten könnte.

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 Kinder des angegebenen Knotens zur Auswahl hinzu.

Selection.setBaseAndExtent()

Setzt die Auswahl auf einen Bereich, der alle oder Teile von zwei angegebenen DOM-Knoten und alle dazwischen liegenden Inhalte umfasst.

Selection.setPosition()

Bricht die aktuelle Auswahl auf einen einzigen Punkt zusammen.

Selection.toString()

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

Das Aufrufen der Methode Selection.toString() gibt den Text zurück, der innerhalb der Auswahl enthalten ist, z.B.:

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

Beachten Sie, dass das Verwenden eines Auswahlobjekts als Argument für window.alert die toString-Methode des Objekts aufrufen wird.

Ein Auswahlobjekt repräsentiert die vom Benutzer ausgewählten Ranges. In der Regel hält es nur einen Bereich, der wie folgt angesprochen wird:

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

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

Wie im Selection API specification notes festgehalten, wurde die Selection API ursprünglich von Netscape erstellt und erlaubte mehrere Bereiche (zum Beispiel, um dem Benutzer zu erlauben, eine Spalte aus einem <table> auszuwählen). Andere Browser als Gecko haben jedoch keine Mehrfachbereichsunterstützung implementiert, und die Spezifikation verlangt auch, dass eine Auswahl immer nur einen Bereich haben sollte.

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

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

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

Das Verhalten ist wie folgt:

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

Das oben beschriebene 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 der Range mit den folgenden Methoden modifiziert 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. Wenn Sie eine Auswahl mit der Maus treffen, ist der Anker der Punkt im Dokument, an dem die Maustaste zuerst gedrückt wird. Wenn der Benutzer die Auswahl mithilfe der Maus oder der Tastatur ändert, bewegt sich der Anker nicht.

Bearbeitungshost

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

Fokus einer Auswahl

Der Fokus einer Auswahl ist der Endpunkt der Auswahl. Wenn Sie eine Auswahl mit der Maus treffen, ist der Fokus der Punkt im Dokument, an dem die Maustaste losgelassen wird. Wenn der Benutzer die Auswahl mithilfe 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, das durch document.activeElement zurückgegeben wird.

Bereich

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

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