Selection
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since March 2017.
Ein Selection
-Objekt repräsentiert den vom Benutzer ausgewählten Textbereich oder die aktuelle Position des Cursors. Jedes document
ist mit einem eindeutigen Auswahlobjekt verknüpft, das mit document.getSelection()
oder window.getSelection()
abgerufen und dann geprüft und modifiziert werden kann.
Ein Benutzer kann eine Auswahl von links nach rechts (in Dokumentreihenfolge) oder von rechts nach links (gegen die Dokumentreihenfolge) vornehmen. Der Anker ist der Punkt, an dem der Benutzer die Auswahl begonnen hat, und der Fokus ist der Punkt, an dem der Benutzer die Auswahl beendet. Wenn Sie eine Auswahl mit einer Desktop-Maus treffen, wird der Anker dort platziert, wo Sie die Maustaste gedrückt haben, und der Fokus dort, wo Sie die Maustaste losgelassen haben.
Note: Anker und Fokus sollten nicht mit den Start- und End-Positionen einer Auswahl verwechselt werden. Der Anker kann vor dem Fokus oder umgekehrt platziert werden, je nachdem, in welche Richtung Sie Ihre Auswahl getroffen haben.
Instanz-Eigenschaften
Selection.anchorNode
Nur lesbar-
Gibt den
Node
zurück, in dem die Auswahl beginnt. Kannnull
zurückgeben, wenn die Auswahl nie im Dokument existierte (z.B. ein iframe, das nie angeklickt wurde). Selection.anchorOffset
Nur lesbar-
Gibt eine Zahl zurück, die den Versatz des Ankers der Auswahl innerhalb des
anchorNode
darstellt. WennanchorNode
ein Textknoten ist, ist dies die Anzahl der Zeichen innerhalb des anchorNode vor dem Anker. WennanchorNode
ein Element ist, ist dies die Anzahl der Kindknoten desanchorNode
vor dem Anker. Selection.direction
Nur lesbar-
Ein String, der die Richtung der aktuellen Auswahl beschreibt.
Selection.focusNode
Nur lesbar-
Gibt den
Node
zurück, in dem die Auswahl endet. Kannnull
zurückgeben, wenn die Auswahl nie im Dokument existierte (zum Beispiel in einemiframe
, das nie angeklickt wurde). Selection.focusOffset
Nur lesbar-
Gibt eine Zahl zurück, die den Versatz des Ankers der Auswahl innerhalb des
focusNode
darstellt. WennfocusNode
ein Textknoten ist, ist dies die Anzahl der Zeichen innerhalb desfocusNode
vor dem Fokus. WennfocusNode
ein Element ist, ist dies die Anzahl der Kindknoten desfocusNode
vor dem Fokus. Selection.isCollapsed
Nur lesbar-
Gibt einen booleschen Wert zurück, der anzeigt, ob die Start- und Endpunkte der Auswahl an derselben Position sind.
Selection.rangeCount
Nur lesbar-
Gibt die Anzahl der Bereiche in der Auswahl zurück.
Selection.type
Nur lesbar-
Gibt eine Zeichenfolge zurück, die den Typ der aktuellen Auswahl beschreibt.
Instanz-Methoden
Selection.addRange()
-
Ein
Range
-Objekt, das der Auswahl hinzugefügt wird. Selection.collapse()
-
Faltet die aktuelle Auswahl zu einem einzigen Punkt zusammen.
Selection.collapseToEnd()
-
Faltet die Auswahl zum Ende des letzten Bereichs in der Auswahl zusammen.
Selection.collapseToStart()
-
Faltet die Auswahl zum 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 und setzt die Eigenschaften
anchorNode
undfocusNode
aufnull
, sodass 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, die jeweils eine Auswahl darstellen, die Dom-Schatten-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 eines angegebenen Knotens zur Auswahl hinzu.
Selection.setBaseAndExtent()
-
Setzt die Auswahl zu einem Bereich, der alle oder Teile von zwei angegebenen DOM-Knoten und den dazwischenliegenden Inhalt umfasst.
Selection.setPosition()
-
Faltet die aktuelle Auswahl zu einem einzigen Punkt zusammen.
Selection.toString()
-
Gibt eine Zeichenfolge zurück, die derzeit vom Auswahlobjekt repräsentiert wird, d.h., den aktuell ausgewählten Text.
Anmerkungen
Zeichenfolgenrepräsentation einer Auswahl
Das Aufrufen der Methode Selection.toString()
gibt den Text zurück, der sich innerhalb der Auswahl befindet, z.B.:
const selObj = window.getSelection();
window.alert(selObj);
Beachten Sie, dass das Verwenden eines Auswahlobjekts als Argument von window.alert
die toString
-Methode des Objekts aufruft.
Mehrere Bereiche in einer Auswahl
Ein Auswahlobjekt repräsentiert die von einem Benutzer ausgewählten Range
s. Normalerweise 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-Objektrange
ist einRange
-Objekt
Wie in den Anmerkungen zur Spezifikation der Selection API beschrieben, wurde die Selection API ursprünglich von Netscape erstellt und erlaubte mehrere Bereiche (zum Beispiel, um dem Benutzer das Auswählen einer Spalte aus einem <table>
zu ermöglichen). Andere Browser als Gecko implementierten jedoch keine Mehrfachbereiche, und die Spezifikation erfordert auch, dass die Auswahl immer einen einzelnen Bereich hat.
Auswahl und Eingabefokus
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 mit der Auswahl, wenn die Auswahl programmgesteuert geändert wird; Es ist möglich, dass sich dies in Zukunft ändern könnte (siehe W3C Bug 14383 und Webkit Bug 38696).
Verhalten der Selection API in Bezug auf Fokusänderungen bei Editierhost
Die Selection API hat ein gemeinsames Verhalten (d.h. zwischen Browsern geteilt), das das Fokusverhalten für Editierhosts ändert, nachdem bestimmte Methoden aufgerufen werden.
Das Verhalten ist wie folgt:
- Ein Editierhost erhält Fokus, wenn die vorherige Auswahl außerhalb davon war.
- Eine Selection API-Methode wird aufgerufen, wodurch eine neue Auswahl getroffen wird, mit dem Auswahlbereich innerhalb des Editierhosts.
- Der Fokus wechselt dann zum Editierhost.
Hinweis: Die Methoden der Selection API können den Fokus nur auf einen Editierhost verschieben, nicht auf andere fokussierbare Elemente (z.B. <a>
).
Das oben beschriebene Verhalten gilt für Auswahlen, die mit folgenden Methoden vorgenommen werden:
Selection.collapse()
Selection.collapseToStart()
Selection.collapseToEnd()
Selection.extend()
Selection.selectAllChildren()
Selection.addRange()
Selection.setBaseAndExtent()
Und wenn der Range
mithilfe folgender Methoden geändert wird:
Glossar
Andere in diesem Abschnitt verwendete Schlüsselbegriffe.
- Anker
-
Der Anker einer Auswahl ist der Anfangspunkt der Auswahl. Beim Erstellen 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.
- Editierhost
-
Ein bearbeitbares Element (z.B. ein HTML-Element mit
contenteditable
gesetzt oder das HTML-Kind eines Dokuments, dasdesignMode
aktiviert hat). - Auswahlfokus
-
Der Fokus einer Auswahl ist der Endpunkt der Auswahl. Beim Erstellen 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 enthalten (wie z.B. einen Teil eines Textknotens). Ein Benutzer wählt normalerweise nur einen Bereich gleichzeitig aus, aber es ist möglich, dass ein Benutzer mehrere Bereiche auswählt (z.B. durch Drücken 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.
Spezifikationen
Specification |
---|
Selection API # selection-interface |
Browser-Kompatibilität
BCD tables only load in the browser
Siehe auch
Window.getSelection
,Document.getSelection
,Range
- Auswahlbezogene Ereignisse:
selectionchange
undselectstart
- HTML-Eingaben bieten einfachere Hilfs-APIs für die Arbeit mit Auswahlen (siehe
HTMLInputElement.setSelectionRange()
) Document.activeElement
,HTMLElement.focus
, undHTMLElement.blur