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, 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 Zeichenfolgenwert, 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 (z. B. ein 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 Booleschen Wert zurück, der angibt, ob die Start- und Endpunkte der Auswahl an der gleichen Position sind.

Selection.rangeCount Schreibgeschützt

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

Selection.type Schreibgeschützt

Gibt eine Zeichenfolge zurück, die die Art der aktuellen Auswahl beschreibt.

Selection.addRange()

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

Selection.collapse()

Kollabiert die aktuelle Auswahl zu einem einzigen Punkt.

Selection.collapseToEnd()

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

Selection.collapseToStart()

Kollabiert die Auswahl 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 und setzt die Eigenschaften anchorNode und focusNode auf null, sodass nichts ausgewählt ist.

Selection.extend()

Bewegt den Fokus der Auswahl zu einem bestimmten Punkt.

Selection.getComposedRanges()

Gibt ein Array von StaticRange-Objekten zurück, von denen jedes eine Auswahl darstellt, die auch DOM-Schatten-Grenzen überschreiten kann.

Selection.getRangeAt()

Gibt ein Range-Objekt zurück, das einen der aktuell 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 der Auswahl alle Kinder des angegebenen Knotens hinzu.

Selection.setBaseAndExtent()

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

Selection.setPosition()

Kollabiert die aktuelle Auswahl zu einem einzigen Punkt.

Selection.toString()

Gibt eine Zeichenfolge zurück, die derzeit vom Auswahlobjekt repräsentiert wird, also den aktuell ausgewählten Text.

Das Aufrufen der Selection.toString()-Methode gibt den Text zurück, der sich innerhalb der Auswahl befindet, 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 Ranges, die der Benutzer ausgewählt hat. In der Regel enthält es nur einen Bereich, der wie folgt abgerufen werden kann:

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

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

Wie in den Speziellen Anmerkungen zur 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 einer <table> auszuwählen). Allerdings haben andere Browser als Gecko keine mehrfachen Bereiche implementiert, und die Spezifikation verlangt auch, dass die Auswahl immer nur einen Bereich haben soll.

Auswahl und Eingabefokus (angezeigt durch Document.activeElement) haben eine komplexe Beziehung, die je nach Browser variiert. In browserübergreifendem 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 programmgesteuert geändert wird; es ist möglich, dass sich dies in Zukunft ändern könnte (siehe W3C-Fehler 14383 und WebKit-Fehler 38696).

Die Selection API weist ein gemeinsames Verhalten auf (d.h. zwischen den Browsern geteilt), das bestimmt, wie sich das Fokusverhalten für Editierhosts nach dem Aufrufen bestimmter Methoden ändert.

Das Verhalten ist wie folgt:

1. Ein Editierhost 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 Editierhosts erstellt wird.
3. Der Fokus bewegt sich dann zum Editierhost.

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 der Range mit 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 Beginn der Auswahl. Beim Erstellen einer Auswahl mit einer 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.

Editierhost

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

Fokus einer Auswahl

Der Fokus einer Auswahl ist der Endpunkt der Auswahl. Beim Erstellen einer Auswahl mit einer 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, 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 einen Teil eines Textknotens) enthalten. Normalerweise wählt ein Benutzer nur einen Bereich gleichzeitig aus, aber es ist möglich, dass ein Benutzer mehrere Bereiche auswählt (z.B. durch 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 daraus entfernt werden.

• Window.getSelection, Document.getSelection, Range
• Auswahlbezogene Ereignisse: selectionchange und selectstart
• HTML-Eingaben bieten einfachere Hilfs-APIs zur Bearbeitung der Auswahl (siehe HTMLInputElement.setSelectionRange())
• Document.activeElement, HTMLElement.focus, und HTMLElement.blur