Range | NN 6 IE nicht zutreffend DOM 2 | |||||||||||||||||||||||
Das Range-Objekt des W3C-DOMs ähnelt vom Konzept her dem TextRange-Objekt von IE und repräsentiert eine Textzeichenfolge aus null oder mehr Zeichen, die in einem Dokument dargestellt werden. Ein aus null Zeichen bestehender Textbereich stellt einen Einfügepunkt zwischen zwei Zeichen (oder vor dem ersten bzw. hinter dem letzen Zeichen des Dokuments) dar. Das Range-Objekt überwacht automatisch die Node- und Zeichen-Offset-Referenzen für den Start- und den Endpunkt des Bereichs, sodass seine Methoden vorhandene Inhalte kopieren, Bereichsinhalte löschen oder neue Inhalte (in Form von Nodes) in den vorhandenen Bereich einfügen können, ohne die Integrität des Dokumentbaums zu gefährden. Das Nodemodell ist eine wichtige Voraussetzung für das Range-Objekt, doch mit den meisten damit verbundenen Problemen werden Sie als Skriptersteller gar nicht erst konfrontiert. |
||||||||||||||||||||||||
Ein Range-Objekt wird entweder mithilfe der Methode document.createTextRange( ) erstellt oder mithilfe der Methode window.getSelection( ).getRangeAt(0) aus einer Textauswahl des Benutzers gebildet. Nachdem ein Textbereich erstellt wurde, verwenden Sie seine Methoden, um den Start- und Endpunkt zu definieren und so das gewünschte Textsegment einzurichten. Anschließend können Sie verschiedene weitere Methoden auf den Bereich anwenden. Weitere Informationen sowie Beispiele für die Verwendung des Range-Objekts und die syntaktischen Unterschiede gegenüber dem IE-Objekt TextRange finden Sie in Kapitel 5. |
||||||||||||||||||||||||
Objektmodellreferenz | ||||||||||||||||||||||||
document.createRange( ) |
||||||||||||||||||||||||
Objektspezifische Eigenschaften | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
Objektspezifische Methoden | ||||||||||||||||||||||||
|
||||||||||||||||||||||||
Objektspezifische Ereignisbehandlungsroutineneigenschaften | ||||||||||||||||||||||||
Keine. |
collapsed | NN 6 IE nicht zutreffend DOM 2 |
Schreibgeschützt | |
Gibt den Booleschen Wert true zurück, wenn die Positionen des Start- und Endpunkts des Bereichs identisch sind, der Bereich also keine Zeichen umfasst. Ein solcher Bereich kann sich an einer beliebigen Stelle innerhalb des Dokuments befinden. |
|
Beispiel | |
if (rng.collapsed) { // act on collapsed text range } |
|
Wert | |
Boolescher Wert: true | false. |
|
Standardwert | |
Keiner. |
commonAncestorContainer | NN 6 IE nicht zutreffend DOM 2 |
Schreibgeschützt | |
Gibt eine Referenz auf eine Node im Dokumentbaum zurück, die den nächstäußeren Container darstellt, der den Start- und Endpunkt des aktuellen Bereichs umfasst. Wenn sich der Start- und der Endpunkt in derselben Node befinden (z. B. in derselben Textnode), gibt die Eigenschaft commonAncestorContainer eine Referenz auf die Parent-Node dieser Node zurück. Da IE-TextRange-Äquivalent ist parentElement( ). |
|
Beispiel | |
var containingElem = rng.commonAncestorContainer; |
|
Wert | |
Referenz auf ein Nodeobjekt (im Allgemeinen ein Elementnodetyp). |
|
Standardwert | |
Keiner. |
endContainer | NN 6 IE nicht zutreffend DOM 2 |
Schreibgeschützt | |
Gibt eine Referenz auf eine Node im Dokumentbaum zurück, die den Endpunkt des aktuellen Bereichs enthält. |
|
Beispiel | |
var containingElemRight = rng.endContainer; |
|
Wert | |
Referenz auf ein Nodeobjekt. |
|
Standardwert | |
Keiner. |
endOffset | NN 6 IE nicht zutreffend DOM 2 | |||||||||||||||||
Schreibgeschützt | ||||||||||||||||||
Gibt die Position des Endpunkts innerhalb der Node laut der Eigenschaft endContainer in Form einer Ganzzahl zurück, die die Anzahl der Zeichen oder Nodes angibt. Wenn es sich beim endContainer um eine Textnode handelt, zählt die endOffset-Eigenschaft die Zeichen rechts neben dem ersten Zeichen dieser Textnode. Handelt es sich beim endContainer um eine Elementnode, zählt die endOffset-Eigenschaft die Nodes zwischen dem Anfang des Inhalts der übergeordneten Node und dem Endpunkt. |
||||||||||||||||||
Nehmen wir als Beispiel den folgenden Dokumentabschnitt, der einen Textbereich in Fettschrift enthält, dessen Start- und Endpunkt durch senkrechte Striche gekennzeichnet sind. <>One paragraph with |pa<span> nested</spa>| element inside.</p>n |
||||||||||||||||||
Beachten Sie, dass sich der Startpunkt innerhalb einer Textnode befindet, während der Endpunkt gerade außerhalb des End-Tags des span-Elements liegt. Die Eigenschaften des Range-Objekts melden die in der folgenden Tabelle dargestellten Werte: |
||||||||||||||||||
|
||||||||||||||||||
Beispiel | ||||||||||||||||||
var rngEndOff = rng.endOffset; |
||||||||||||||||||
Wert | ||||||||||||||||||
Eine ganze Zahl. |
||||||||||||||||||
Standardwert | ||||||||||||||||||
Keiner. |
startContainer | NN 6 IE nicht zutreffend DOM 2 |
Schreibgeschützt | |
Gibt eine Referenz auf eine Node im Dokumentbaum zurück, die den Startpunkt des aktuellen Bereichs enthält. |
|
Beispiel | |
var containingElemLeft = rng.startContainer; |
|
Wert | |
Referenz auf ein Nodeobjekt. |
|
Standardwert | |
Keiner. |
startOffset | NN 6 IE nicht zutreffend DOM 2 |
Schreibgeschützt | |
Gibt die Position des Startpunkts innerhalb der Node laut der Eigenschaft startContainer in Form einer Ganzzahl zurück, die die Anzahl der Zeichen oder Nodes angibt. Wenn es sich beim startContainer um eine Textnode handelt, zählt die startOffset-Eigenschaft die Zeichen rechts neben dem ersten Zeichen dieser Textnode. Handelt es sich beim startContainer um eine Elementnode, zählt die startOffset-Eigenschaft die Nodes zwischen dem Anfang des Inhalts der übergeordneten Node und dem Startpunkt. Weitere Details finden Sie unter endOffset. |
|
Beispiel | |
var rngStartOff = rng.startOffset; |
|
Wert | |
Eine ganze Zahl. |
|
Standardwert | |
Keiner. |
cloneContents( ) | NN 7 IE nicht zutreffend DOM 2 |
Gibt eine DocumentFragment-Node zurück, die eine Kopie des Inhalts aus dem aktuellen Bereich enthält. Im Rahmen des Klonvorgangs werden alle losen Nodes aufgelöst. |
|
Parameter | |
Keine. |
|
Zurückgegebener Wert | |
Referenz auf eine Node eines Dokumentfragmenttyps. |
cloneRange( ) | NN 6 IE nicht zutreffend DOM 2 |
Gibt ein Range-Objekt zurück, bei dem es sich um eine Kopie des aktuellen Bereichs einschließlich der Referenzen zu den verknüpften Containern handelt. Mithilfe dieser Methode können Sie eine Kopie der Spezifikationen eines Range-Objekts beibehalten, während Sie ein neues Range-Objekt erstellen. Ähnelt der Methode duplicate( ) des IE-TextRange-Objekts. |
|
Parameter | |
Keine. |
|
Zurückgegebener Wert | |
Referenz auf ein Range-Objekt. |
collapse( ) | NN 6 IE nicht zutreffend DOM 2 |
collapse(toStartFlag) | |
Verkürzt den aktuellen Bereich zu einem Einfügepunkt (Start- und Endpunkt des Bereichs liegen in derselben Node beim selben Offset). Der Boolesche Parameter steuert, ob sich der Bereich zum Startpunkt (true) oder zum Endpunkt (false) des aktuellen Bereichs hin verkürzt. Ein Skript, das sich durch ein Dokument arbeitet (indem es z. B. mit der String.indexOf( )-Methode nach der jeweils nächsten Instanz einer Zeichenfolge sucht), verkürzt einen Bereich in der Regel zum Endpunkt hin, bevor es diesen dann an das Ende des Body-Texts verschiebt und die nächste String.indexOf( )-Suche durchführt. |
|
Parameter | |
|
|
Zurückgegebener Wert | |
Keiner. |
compareBoundaryPoints( ) | NN 6 IE nicht zutreffend DOM 2 | |||||||||
compareBoundaryPoints(compareType, sourceRangeRef) | ||||||||||
Gibt einen ganzzahligen Code zurück, der die relative Positionierung eines Begrenzungspunkts des aktuellen Bereichs in Bezug auf einen Begrenzungspunkt eines anderen Textbereichs angibt. Im einfachsten Fall befinden sich beide Endpunkte (jeweils verschiedener Bereiche) im selben übergeordneten Container. In einem solchen Fall bestimmt der erste Parameter, welche Endpunkte aus den beiden Bereichen verglichen werden. Verwenden Sie die für Range-Objekte üblichen Konstanten (siehe unten stehende Tabelle). |
||||||||||
Wenn der erste der beiden miteinander verglichenen Begrenzungspunkte im Dokument vor dem zweiten Begrenzungspunkt liegt, wird der Wert -1 zurückgegeben, wenn der erste Begrenzungspunkt nach dem zweiten Begrenzungspunkt liegt, wird der Wert 1 zurückgegeben. Befinden sich beide Begrenzungspunkte an der gleichen Position, so lautet der Rückgabewert 0. Diese Methode ähnelt der compareEndPoints( )-Methode beim TextRange-Objekt von IE. |
||||||||||
Die Situation kann jedoch noch wesentlich komplizierter werden. Wenn sich die miteinander zu vergleichenden Begrenzungspunkte nämlich in unterschiedlichen Container-Nodes befinden, wird das Ergebnis des Vergleichs maßgeblich von den Offsetwerten der Begrenzungspunkte in Bezug auf ihre jeweilige Container-Node beeinflusst. Aufgrund der vielen verschiedenen Ergebnisse, die angesichts der zahlreichen Beziehungen zwischen den verglichenen Begrenzungspunkten ermittelt werden können, muss Ihr Skript die Bereichsgrenzen genauestens analysieren, um sicherzustellen, dass der Vergleich die gewünschte Abfolge wiedergibt. Andererseits ist es wesentlich leichter, einfach nach Übereinstimmungen von Begrenzungspunkten zu suchen. Es kann sinnvoll sein, Vergleiche auf die Suche nach Rückgabewerten von Null (oder anderer Werte) zu beschränken, um eine binäre Bestimmung von Bereichsverhältnissen zu ermöglichen. |
||||||||||
|
||||||||||
Parameter | ||||||||||
|
||||||||||
Zurückgegebener Wert | ||||||||||
Integerwerte -1, 0 oder 1. |
compareNode( ) | NN 6 IE nicht zutreffend DOM nicht zutreffend | ||||||||||||||
compareNode(nodeReference) | |||||||||||||||
Eine nur in Netscape verfügbare Methode, die die relative Position einer anderen Node in Bezug auf den aktuellen Bereich in Form eines ganzzahligen Codes zurückgibt. Die von der compareNode( )-Methode zurückgegebenen Werte können mithilfe der vier unverschlüsselten Konstanten, die zu jedem Netscape-Range-Objekt gehören, miteinander verglichen werden. Beachten Sie, dass sich die Rückgabewerte auf die mit dem Parameter übergebene Node und nicht auf die Node des aktuellen Bereichs beziehen. |
|||||||||||||||
Die Rückgabewerte und Konstanten lauten wie folgt. |
|||||||||||||||
Beispiel: |
|||||||||||||||
|
|||||||||||||||
Parameter | |||||||||||||||
|
|||||||||||||||
Zurückgegebener Wert | |||||||||||||||
Integerwerte 0, 1, 2 oder 3. |
comparePoint( ) | NN 6 IE nicht zutreffend DOM nicht zutreffend | |||||||
compareNode(nodeReference, offset) | ||||||||
Eine nur in Netscape verfügbare Methode, die die relative Position einer anderen Node und den Offset innerhalb dieser Node in Bezug auf den aktuellen Bereich in Form eines ganzzahligen Codes zurückgibt. Beachten Sie, dass sich die Rückgabewerte auf die mit den Parametern übergebene Node (genauer gesagt, auf den durch den Offsetwert bezeichneten Punkt innerhalb dieser Node) und nicht auf die Node des aktuellen Bereichs beziehen. |
||||||||
Folgende Rückgabewerte sind möglich. |
||||||||
Beispiel: |
||||||||
|
||||||||
Parameter | ||||||||
|
||||||||
Zurückgegebener Wert | ||||||||
Integerwerte -1, 0, 1. |
createContextualFragment( ) | NN 6 IE nicht zutreffend DOM nicht zutreffend |
createContextualFragment(contentString) | |
Die Methode createContextualFragment( ) wurde ursprünglich als Alternative zu der Hilfseigenschaft innerHTML entwickelt, da das W3C-DOM nur wenig Unterstützung für Inhaltszeichenfolgen bietet, die aus Tags bestehen. Diese Methode akzeptiert jede beliebige Zeichenfolge – einschließlich Inhalte mit Tags – als Parameter und gibt eine Node vom Typ DocumentFragment zurück, die direkt an den Dokumentbaum angehängt oder in ihn eingefügt werden kann. Da die innerHTML-Eigenschaft später im Mozilla-Browser implementiert wurde, ist diese Methode eigentlich überflüssig, sie passt jedoch insgesamt besser in das grundlegende Nodemodell des W3C-DOM. |
|
Parameter | |
|
|
Zurückgegebener Wert | |
Referenz auf eine Dokumentfragmentnode außerhalb des Dokumentbaums. Diese Node kann sodann dem Dokumentbaum hinzugefügt werden. |
deleteContents( ) | NN 6 IE nicht zutreffend DOM 2 |
Entfernt den Inhalt des aktuellen Textbereichs aus dem Dokumentbaum. Wenn es sich bei dem Bereich um eine Elementnode handelt, deren Begrenzungspunkte beispielsweise mithilfe der selectNode( )-Methode festgelegt wurden, bewirkt die Anwendung der deleteContents( )-Methode auf diesen Bereich, dass die Node aus dem Dokumentbaum entfernt und der Bereich verkürzt wird. Das Range-Objekt verbleibt im Arbeitsspeicher, jedoch ohne irgendwelchen Inhalt. Wenn Sie den Inhalt vor dem Löschen erfassen möchten, verwenden Sie eine der anderen Methoden des Range-Objekts, z. B. die cloneRange( )- oder, sofern sie ordnungsgemäß funktioniert, die cloneContents( )-Methode. |
|
Parameter | |
Keine. |
|
Zurückgegebener Wert | |
Keiner. |
detach( ) | NN 6 IE nicht zutreffend DOM 2 |
Zerstört das aktuelle Range-Objekt und bewirkt, dass der Aufruf der meisten Methoden oder der Zugriff auf die Eigenschaften dieses Objekts eine RangeException-Ausnahme vom Typ INVALID_STATE_ERR erzeugt. |
|
Parameter | |
Keine. |
|
Zurückgegebener Wert | |
Keiner. |
extractContents( ) | NN 6 IE nicht zutreffend DOM 2 |
Entfernt den Inhalt des aktuellen Bereichs aus dem Dokumentbaum und gibt ihn in Form einer DocumentFragment-Node zurück. Funktioniert in Netscape 6.2 bislang nur, wenn die Begrenzungspunkte des Bereichs mit der Methode selectNodeContents( ) eingestellt wurden. |
|
Parameter | |
Keine. |
|
Zurückgegebener Wert | |
Referenz auf eine Node eines Dokumentfragmenttyps. |
insertNode( ) | NN 6 IE nicht zutreffend DOM 2 |
insertNode(nodeReference) | |
Fügt eine Node am Anfang des aktuellen Textbereichs ein. Dies ist vor allem dann sinnvoll, wenn der Bereich bereits zu einer Texteinfügemarke verkürzt wurde. Die einzufügende Node kann entweder mit Hilfe der Methode document.createElement( ) eigens erstellt oder von einer anderen Stelle des Dokumentbaums übernommen werden. Im letzteren Fall wird die Node an ihrer ursprünglichen Position entfernt und in den aktuellen Bereich eingefügt. Wenn Sie eine Textnode unmittelbar neben einer vorhandenen Textnode einfügen, enthält das Dokument an dieser Stelle letztlich zwei benachbarte Textnodes. In diesem Fall können Sie die Textnodes konsolidieren, indem Sie auf ihren Parent-Container die Methode normalize( ) anwenden. |
|
Parameter | |
|
|
Zurückgegebener Wert | |
Keiner. |
intersectsNode( ) | NN 6 IE nicht zutreffend DOM nicht zutreffend |
intersectsNode(nodeReference) | |
Gibt den Booleschen Wert true zurück, wenn sich ein Teil des aktuellen Bereichs mit der im Parameter übergebenen Text- oder Elementnode überschneidet. Wenn Ihr Skript eine solche Überschneidung erkennt, kann es mit der Methode compareNode( ) weitere Informationen abrufen. |
|
Parameter | |
|
|
Zurückgegebener Wert | |
Boolescher Wert: true | false. |
isPointInRange( ) | NN 6 IE nicht zutreffend DOM nicht zutreffend |
isPointInRange(nodeReference, offset) | |
Gibt den Booleschen Wert true zurück, wenn der durch die Parameterwerte (eine Node im Dokumentbaum und eine Offset-Position innerhalb dieser Node) bezeichnete Punkt innerhalb des aktuellen Bereichs liegt. |
|
Parameter | |
|
|
Zurückgegebener Wert | |
Boolescher Wert: true | false. |
selectNode( ), selectNodeContents( ) | NN 6 IE nicht zutreffend DOM 2 | ||||||||||||||
selectNode(nodeReference) selectNodeContents(nodeReference) | |||||||||||||||
Stellt die Begrenzungspunkte des Bereichs so ein, dass sie entweder eine Node oder nur ihren Inhalt umfassen. Obwohl der Methodenname dies vermuten ließe, wird kein Bodytext im dargestellten Dokument markiert. |
|||||||||||||||
Die ausgewählte Methode bestimmt die Art und Weise, in der die Eigenschaften startContainer und endContainer des Bereichs gefüllt werden. Das folgende Verfahren zeigt, was mit dem Bereich und seinen Eigenschaften geschieht, wenn Sie eine Elementnode und eine Textnode als Parameter an diese Methoden übergeben. Das ursprüngliche HTML-Segment sieht folgendermaßen aus: <>One paragraph with a <span id="myspan">nested</span> element inside.</p>p |
|||||||||||||||
Wenn Sie mit der Methode rng.selectNode(document.getElementByID("myspan")) das Element span auswählen, wird der Bereich wie folgt eingestellt: <>One paragraph with a |<span id="myspan">pnested</spa>| element inside.</p>n |
|||||||||||||||
Die Eigenschaften des Range-Objekts melden die folgenden Werte. |
|||||||||||||||
Wenn Sie mit der Methode rng.selectNodeContents(document.getElementByID("myspan")) den Inhalt des span-Elements auswählen, wird der Bereich wie folgt eingestellt: <>One paragraph with a <span id="myspan">|pnested</span> element inside.</p>| |
|||||||||||||||
Die Eigenschaften des Range-Objekts melden die folgenden Werte. |
|||||||||||||||
Wenn Sie mit der Methode selectNode(document.getElementByID("myspan").firstChild) die Textnode innerhalb des span-Elements auswählen, wird der Bereich wie folgt eingestellt: <>One paragraph with a <span id="myspan">|pnested</span> element inside.</p>| |
|||||||||||||||
Obwohl als Parameter eine andere Node (mit einem anderen Nodetyp) übergeben wird, ist der ausgewählte Bereich mit dem aus dem vorigen Beispiel identisch. Tatsächlich melden die Eigenschaften des Range-Objekts aufgrund der Struktur des Nodebaums dieselben Werte. |
|||||||||||||||
Wenn Sie mit der Methode rng.selectNodeContents(document.getElementByID("myspan") den Inhalt der Textnode innerhalb des span-Elements auswählen, wird der Bereich wie folgt eingestellt: <>One paragraph with a <span id="myspan">||nested</span> element inside.</p>p |
|||||||||||||||
Der Bereich wird also, wie die folgende Eigenschaftsübersicht zeigt, zu einem Einfügepunkt am Anfang der Textnode verkürzt (möglicherweise ein Anwendungsfehler in Netscape 6), und die Textnode wird zum Container. |
|||||||||||||||
Im Allgemeinen ist es am praktischsten, die Elementnodes als Parameter an die verschiedenen Methoden zu übergeben. |
|||||||||||||||
|
|||||||||||||||
|
|||||||||||||||
|
|||||||||||||||
|
|||||||||||||||
Parameter | |||||||||||||||
|
|||||||||||||||
Zurückgegebener Wert | |||||||||||||||
Keiner. |
setEnd( ), setStart( ) | NN 6 IE nicht zutreffend DOM 2 |
setEnd(nodeReference, offset) setStart(nodeReference, offset) | |
Legen die Positionen der einzelnen Begrenzungspunkte eines vorhandenen Range-Objekts im Dokumentbaum fest. Ähnelt der Methode setEndPoint( ) des IE-TextRange-Objekts. Die Zuordnung einer Position basiert auf einer Nodereferenz und einem Offsetwert in Bezug auf den Startpunkt und Typ der betreffenden Node. Wenn es sich bei der nodeReference um eine Elementnode handelt, wird der Offsetwert als Anzahl von Child-Nodes angegeben, und wenn es sich bei nodeReference um eine Textnode handelt, als Anzahl von Textzeichen. Für das Festlegen eines Begrenzungspunkts am Rand einer Node sind die zugehörigen Methoden (setEndAfter( ) und drei weitere) besser geeignet. |
|
Parameter | |
|
|
Zurückgegebener Wert | |
Keiner. |
setEndAfter( ), setEndBefore( ), setStartAfter( ), setStartBefore( ) | NN 6 IE nicht zutreffend DOM 2 |
setEndAfter(nodeReference) setEndBefore(nodeReference) setStartAfter(nodeReference) setStartBefore(nodeReference) | |
Legen die Positionen der einzelnen Begrenzungspunkte eines vorhandenen Range-Objekts im Dokumentbaum in Bezug auf die Ränder einer Node fest. Bei diesen Methoden wird davon ausgegangen, dass Sie die Begrenzungspunkte eines Bereichs unmittelbar vor oder hinter einer vorhandenen Node platzieren und keinen Offset einstellen möchten. Die Bereichsgrenzen müssen nicht symmetrisch sein, d. h. Sie können den Startpunkt in Bezug auf eine Node und den Endpunkt in Bezug auf eine vollkommen andere Node weiter hinten im Dokument angeben. |
|
Parameter | |
|
|
Zurückgegebener Wert | |
Keiner. |
surroundContents( ) | NN 7 IE nicht zutreffend DOM 2 |
surroundContents(parentNodeReference) | |
Schließt den aktuellen Bereich in einen neuen Container, in der Regel in eine mit der Methode document.createElement( ) erstellte neue Elementnode, ein. Die Endpunkte des aktuellen Bereichs sollten innerhalb desselben Parent-Containers liegen, wenn Sie diese Methode anwenden möchten. |
|
Parameter | |
|
|
Zurückgegebener Wert | |
Keiner. |
toString( ) | NN 6 IE nicht zutreffend DOM 2 |
Gibt eine Zeichenfolge mit dem im Bereich enthaltenen Body-Inhalt zurück. Der Rückgabewert enthält keine Tags oder Attribute. |
|
Parameter | |
Keine. |
|
Zurückgegebener Wert | |
Zeichenfolge. |