Selection API

Konzepte und Verwendung

Eine Auswahl erfolgt folgendermaßen:

• Zuerst wird die Maustaste an einer Stelle im Dokument gedrückt. Dieser Punkt ist der Anker der Auswahl. Wenn der Benutzer die Auswahl mit der Maus oder der Tastatur verändert, bleibt der Anker an seiner Position.

• Während die Maustaste gedrückt gehalten wird, wird ein weiterer Punkt, der Fokus, mit der Maus oder der Tastatur durch das Dokument bewegt. Er beginnt an der Position des Ankers.

  Hinweis: Dies ist nicht dasselbe wie das fokussierte Element des Dokuments, das document.activeElement zurückgibt.

• Die Maustaste wird losgelassen und die Auswahl damit abgeschlossen. Der Fokus befindet sich an der Position, an der die Maustaste losgelassen wurde.

Zu jedem Zeitpunkt besteht die Auswahl aus einem zusammenhängenden Teil eines Dokuments, der durch ein Range-Objekt dargestellt wird. Ein Bereich kann sowohl vollständige Knoten als auch Teile von Knoten enthalten, beispielsweise einen Teil eines Textknotens. In Browsern, die dies unterstützen, kann eine Auswahl auch mehrere Bereiche enthalten.

Jedes Range-Objekt hat zwei Grenzpunkte. Der in der Baumreihenfolge zuerst liegende Punkt wird als Anfang bezeichnet, der andere als Ende. Da eine Auswahl sowohl vorwärts (beispielsweise in einem von links nach rechts geschriebenen Dokument durch Ziehen der Maus nach rechts innerhalb derselben Zeile) als auch rückwärts erfolgen kann, kann der Anfang entweder der Anker oder der Fokus der Auswahl sein. Dasselbe gilt für das Ende.

String-Darstellung einer Auswahl

Wenn in JavaScript ein Objekt an eine Funktion übergeben wird, die einen String erwartet (etwa window.alert() oder document.write()), wird die Methode toString() des Objekts aufgerufen und ihr Rückgabewert an die Funktion übergeben. Dadurch kann das Objekt bei der Verwendung mit anderen Funktionen wie ein String erscheinen, obwohl es tatsächlich ein Objekt mit Eigenschaften und Methoden ist.

const selection = window.getSelection();
alert(selection); // Shows a string

Allerdings rufen nicht alle Funktionen toString() automatisch auf. Um ein Selection-Objekt in einen String umzuwandeln, rufen Sie seine Methode toString() direkt auf:

const selectedText = selection.toString();

Mehrere Bereiche in einer Auswahl

Die Spezifikation schreibt vor, dass ein Selection-Objekt höchstens einen Range enthalten darf. Auf diesen wird wie folgt zugegriffen:

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

Die Selection-Schnittstelle wurde jedoch so entworfen, als könnte sie mehrere Bereiche enthalten. Wie in der Selection API-Spezifikation erläutert, wurde die Selection API ursprünglich von Netscape entwickelt und erlaubte mehrere Bereiche. Da es dabei jedoch viele Fehler gab, wurde diese Funktion bewusst eingeschränkt. Firefox bietet dennoch eine vollständig funktionsfähige Bedienoberfläche für Mehrfachauswahlen: Sie können in Firefox mehrere Bereiche programmgesteuert hinzufügen oder entfernen sowie durch Gedrückthalten der Taste Strg/Cmd mehrere Bereiche auswählen.

Auswahl und Eingabefokus

Zwischen der Auswahl und dem Eingabefokus (angezeigt durch Document.activeElement) besteht ein komplexer Zusammenhang, der sich je nach Browser unterscheidet. In browserübergreifend kompatiblem Code sollten Sie beides getrennt behandeln.

Safari und Chrome (anders als Firefox) fokussieren derzeit das Element, das die Auswahl enthält, wenn die Auswahl programmgesteuert verändert wird. Dies könnte sich künftig ändern (siehe W3C-Bug 14383 und WebKit-Bug 38696).

Verhalten der Selection API bei Änderungen des Fokus von Bearbeitungshosts

Ein Bearbeitungshost ist ein bearbeitbares Element (z. B. ein HTML-Element mit gesetztem contenteditable oder das HTML-Kindelement eines Dokuments, für das designMode aktiviert ist). Die Selection API weist ein gemeinsames, browserübergreifendes Verhalten auf, das bestimmt, wie sich der Fokus von Bearbeitungshosts nach dem Aufruf bestimmter Methoden ändert.

Das Verhalten ist wie folgt:

1. Die vorherige Auswahl befindet sich außerhalb eines Bearbeitungshosts.
2. Eine Methode der Selection API wird aufgerufen und erzeugt eine neue Auswahl, deren Bereich innerhalb des Bearbeitungshosts liegt.
3. Der Fokus wechselt daraufhin zum Bearbeitungshost.

Dieses Verhalten gilt für Auswahlen, die mit den folgenden Methoden erstellt werden:

• Selection.collapse()
• Selection.collapseToStart()
• Selection.collapseToEnd()
• Selection.extend()
• Selection.selectAllChildren()
• Selection.addRange()
• Selection.setBaseAndExtent()

Es gilt auch, wenn der Range mit einer der folgenden Methoden verändert wird:

• Range.setStart()
• Range.setEnd()
• Range.setStartBefore()
• Range.setStartAfter()
• Range.setEndBefore()
• Range.setEndAfter()
• Range.collapse()
• Range.selectNode()
• Range.selectNodeContents()

Schnittstellen

Selection

Eine Schnittstelle, die den vom Benutzer ausgewählten Teil des Dokuments oder die aktuelle Position des Textcursors darstellt.

Erweiterungen anderer Schnittstellen

Window

Window.getSelection()

Eine Methode, die ein Selection-Objekt zurückgibt, das die aktuelle Auswahl oder die aktuelle Position des Textcursors darstellt.

Document

Document.getSelection()

Eine Methode, die ein Selection-Objekt zurückgibt, das die aktuelle Auswahl oder die aktuelle Position des Textcursors darstellt.

selectionchange

Ein Ereignis, das ausgelöst wird, wenn sich die aktuelle Auswahl ändert.

Node

selectstart

Ein Ereignis, das ausgelöst wird, wenn ein Benutzer eine neue Auswahl beginnt.

Spezifikationen