Auswahl

Selection.anchorNode Schreibgeschützt

Gibt den Node zurück, in dem die Auswahl beginnt. Kann null zurückgeben, wenn die Auswahl nie im Dokument vorhanden war (z. B. ein iframe, in das nie geklickt 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 in 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 vorhanden war (zum Beispiel in einem iframe, in das nie geklickt 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 in 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-Wert zurück, der angibt, ob die Anfangs- 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()

Kollabiert die aktuelle Auswahl auf einen einzelnen Punkt.

Selection.collapseToEnd()

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

Selection.collapseToStart()

Kollabiert 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, wobei die Eigenschaften anchorNode und focusNode gleich null bleiben 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 Grenzen des Shadow DOM überschreiten kann.

Selection.getRangeAt()

Gibt ein Range-Objekt zurück, das einen der aktuell ausgewählten Bereiche darstellt.

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 aller dazwischen befindlichen Inhalte umfasst.

Selection.setPosition()

Kollabiert die aktuelle Auswahl auf einen einzelnen Punkt.

Selection.toString()

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

Das Aufrufen der Methode Selection.toString() gibt den Text innerhalb der Auswahl zurück, 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 Ranges. Typischerweise enthält es nur einen Bereich, der wie folgt abgerufen wird:

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

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

Wie in der Spezifikation der Selection API angemerkt, wurde die Selection API ursprünglich von Netscape erstellt und erlaubte mehrere Bereiche (zum Beispiel, um dem Benutzer zu ermöglichen, eine Spalte aus einem <table> auszuwählen). Allerdings implementierten andere Browser außer Gecko keine Mehrfachbereiche, und die Spezifikation erfordert auch, dass die Auswahl immer nur einen Bereich hat.

Auswahl und Eingabefokus (angezeigt durch Document.activeElement) haben eine komplexe Beziehung, die je nach Browser variiert. In kompatiblem Code für mehrere Browser 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 programmgesteuert geändert wird; es besteht die Möglichkeit, dass sich dies in Zukunft ändern kann (siehe W3C Bug 14383 und WebKit Bug 38696).

Die Selection API hat ein gemeinsames Verhalten (d. h. zwischen Browsern geteilt), das festlegt, wie sich das Fokusverhalten für Bearbeitungshosts ändert, nachdem bestimmte Methoden aufgerufen wurden.

Das Verhalten ist wie folgt:

1. Ein Bearbeitungshost erhält den Fokus, wenn die vorherige Auswahl außerhalb von ihm war.
2. Eine Methode der Selection API wird aufgerufen, wodurch eine neue Auswahl im Bearbeitungshost vorgenommen wird.
3. Der Fokus wird dann auf den Bearbeitungshost verschoben.

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 wichtige Begriffe, die in diesem Abschnitt verwendet werden.

Anker

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

Bearbeitungshost

Ein bearbeitbares Element (z. B. ein HTML-Element mit aktivierter contenteditable-Eigenschaft oder das HTML-Kind eines Dokuments mit aktiviertem designMode).

Fokus einer Auswahl

Der Fokus einer Auswahl ist der Endpunkt der Auswahl. Wenn eine Auswahl mit der Maus getroffen wird, ist der Fokus der Punkt im Dokument, an dem die Maustaste losgelassen wird. Während 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 (wie ein Teil eines Textknotens) enthalten. Normalerweise wird ein Benutzer nur einen Bereich auf einmal auswählen, aber es ist möglich, dass ein Benutzer mehrere Bereiche auswählt (z. B. durch Verwendung der Steuerung-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 daraus entfernt werden.

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