Auswahl
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 Bereich des vom Benutzer ausgewählten Textes oder die aktuelle Position des Cursors. Jedes document
ist mit einem einzigartigen Auswahlobjekt verknüpft, das durch document.getSelection()
oder window.getSelection()
abgerufen und dann untersucht und modifiziert werden kann.
Ein Benutzer kann eine Auswahl von links nach rechts (in Dokumentreihenfolge) oder von rechts nach links (umgekehrte Dokumentreihenfolge) vornehmen. Der Anker ist der Punkt, an dem der Benutzer die Auswahl beginnt, 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 Endpositionen einer Auswahl verwechselt werden. Der Anker kann vor dem Fokus oder umgekehrt platziert werden, abhängig von der Richtung, in der Sie Ihre Auswahl getroffen haben.
Instanzeigenschaften
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. einiframe
, das nie angeklickt wurde). Selection.anchorOffset
Nur lesbar-
Gibt eine Zahl zurück, die den Versatz des Ankers innerhalb des
anchorNode
der Auswahl darstellt. WennanchorNode
ein Textknoten ist, ist dies die Anzahl der Zeichen innerhalb vonanchorNode
vor dem Anker. WennanchorNode
ein Element ist, ist dies die Anzahl der untergeordneten Knoten 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 Fokus innerhalb des
focusNode
der Auswahl darstellt. WennfocusNode
ein Textknoten ist, ist dies die Anzahl der Zeichen innerhalb vonfocusNode
vor dem Fokus. WennfocusNode
ein Element ist, ist dies die Anzahl der untergeordneten Knoten desfocusNode
vor dem Fokus. Selection.isCollapsed
Nur lesbar-
Gibt einen Boolean zurück, der anzeigt, ob die Start- und Endpunkte der Auswahl sich an derselben Position befinden.
Selection.rangeCount
Nur lesbar-
Gibt die Anzahl der Bereiche (ranges) in der Auswahl zurück.
Selection.type
Nur lesbar-
Gibt einen String zurück, der den Typ der aktuellen Auswahl beschreibt.
Instanzmethoden
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 (range) in der Auswahl.
Selection.collapseToStart()
-
Kollabiert die Auswahl zum Anfang des ersten Bereichs (range) 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
undfocusNode
gleichnull
und nichts ausgewählt ist. Selection.extend()
-
Verschiebt den Fokus der Auswahl an einen bestimmten Punkt.
Selection.getComposedRanges()
Experimentell-
Gibt ein Array von
StaticRange
Objekten zurück, die jeweils eine Auswahl repräsentieren, die möglicherweise Schatten-DOM-Grenzen überschreitet. 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 allen dazwischen liegenden Inhalten umfasst.
Selection.setPosition()
-
Kollabiert die aktuelle Auswahl zu einem einzigen Punkt.
Selection.toString()
-
Gibt einen String zurück, der derzeit vom Auswahlobjekt repräsentiert wird, d. h. den derzeit ausgewählten Text.
Anmerkungen
String-Repräsentation einer Auswahl
Der Aufruf der Methode Selection.toString()
gibt den im Auswahlbereich enthaltenen Text 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.
Mehrere Bereiche in einer Auswahl
Ein Auswahlobjekt repräsentiert die Range
, die der Benutzer ausgewählt hat. Normalerweise 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-Objektrange
ist einRange
Objekt
Wie in den Selection API Spezifikationen 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). Andere Browser als Gecko haben jedoch keine Mehrfachbereiche implementiert, und die Spezifikation erfordert auch, dass die Auswahl immer nur einen Bereich hat.
Auswahl und Eingabefokus
Auswahl und Eingabefokus (angezeigt durch Document.activeElement
) haben eine komplexe Beziehung, die je nach Browser variiert. In plattformunabhängigem 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 ändert (siehe W3C bug 14383 und WebKit bug 38696).
Verhalten der Selection API in Bezug auf Änderungen des Fokus des Editierhosts
Die Selection API hat ein gemeinsames Verhalten (d. h. geteiltes Verhalten zwischen Browsern), das regelt, wie sich der Fokus für Editierhosts ändert, nachdem bestimmte Methoden aufgerufen wurden.
Das Verhalten ist wie folgt:
- Ein Editierhost erlangt den Fokus, wenn die vorherige Auswahl außerhalb davon war.
- Eine Selection API-Methode wird aufgerufen, wodurch eine neue Auswahl innerhalb des Editierhosts erstellt wird.
- Der Fokus verschiebt sich dann auf den 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 den folgenden Methoden getroffen werden:
Selection.collapse()
Selection.collapseToStart()
Selection.collapseToEnd()
Selection.extend()
Selection.selectAllChildren()
Selection.addRange()
Selection.setBaseAndExtent()
Und wenn der Range
mittels folgender Methoden modifiziert wird:
Glossar
Weitere Schlüsselbegriffe, die in diesem Abschnitt verwendet werden.
- Anker
-
Der Anker einer Auswahl ist der Anfangspunkt der Auswahl. Bei einer Auswahl mit der Maus ist der Anker der Ort 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 dem Attribut
contenteditable
gesetzt oder das HTML-Child eines Dokuments, dasdesignMode
aktiviert hat). - Fokus einer Auswahl
-
Der Fokus einer Auswahl ist der Endpunkt der Auswahl. Bei einer Auswahl mit der Maus ist der Fokus der Ort 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 (wie einen Teil eines Textknotens) enthalten. Normalerweise wählt ein Benutzer nur einen einzelnen Bereich gleichzeitig aus, aber es ist möglich, dass ein Benutzer mehrere Bereiche auswählt (z.B. durch Verwendung der Control-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 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 zur Arbeit mit Auswahlen (siehe
HTMLInputElement.setSelectionRange()
) Document.activeElement
,HTMLElement.focus
undHTMLElement.blur