TextRange | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
Das TextRange-Objekt ähnelt vom Konzept her dem Range-Objekt von Netscape 6 und W3C-DOM und repräsentiert einen Text aus null oder mehr Zeichen in einem Dokument. Besteht ein Textbereich aus null Zeichen, stellt er einen Einfügepunkt zwischen zwei Zeichen (oder vor dem ersten oder hinter dem letzen Zeichen) dar.
Ein TextRange-Objekt wird über die createTextRange( )-Methode erstellt, die mit einem body-, button-, text- oder textarea-Objekt verknüpft ist. Mithilfe der Methode createRange( ) des selection-Objekts (beachten Sie den kleinen Unterschied im Methodennamen) können Sie auch einen vom Benutzer ausgewählten Text in einen Bereich umwandeln. Nachdem Sie einen Textbereich erstellt haben, verwenden Sie seine Methoden, um den Start- und Endpunkt zu definieren und so das gewünschte Textsegment einzurichten (z. B. Text, der einer Suchzeichenfolge entspricht). Haben Sie den Bereich auf den Zieltext eingeschränkt, weisen Sie den Eigenschaften htmlText und text Werte zu, um Text zu ändern, zu entfernen oder einzufügen. Sie können auch eine Bibliothek mit direkten Befehlen für den Textbereich aufrufen, mit denen bestimmte Änderungen am Text vornehmen werden können. Ausführliche Informationen und Beispiele zur Verwendung des TextRange-Objekts finden Sie in Kapitel 5.
Die gemeinsamen Eigenschaften und Methoden aus der Liste am Anfang dieses Kapitels sind: offsetLeft, offsetTop, getBoundingClientRect( ), getClientRects( ) und scrollIntoView( ). Beachten Sie, dass das TextRange-Objekt und mit ihm verknüpften Funktionen nur in der Win32-Version von Internet Explorer zur Verfügung stehen.
Objektmodellreferenz
    objectRef.createTextRange( )
    selectionObjectRef.createRange( )
Objektspezifische Eigenschaften
boundingHeight | boundingLeft | boundingTop | boundingWidth
htmlText | text |  |
Objektspezifische Methoden
collapse( ) | compareEndPoints( ) | duplicate( )
execCommand( ) | expand( ) | findText( )
getBookmark( ) | inRange( ) | isEqual( )
move( ) | moveEnd( ) | moveStart( )
moveToBookmark( ) | moveToElementText( ) | moveToPoint( )
parentElement( ) | pasteHTML( ) | queryCommandEnabled( )
queryCommandIndeterm( ) | queryCommandState( ) | queryCommandSupported( )
queryCommandText( ) | queryCommandValue( ) | select( )
setEndPoint( ) |  |

boundingHeight, boundingWidth | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
| Schreibgeschützt
Gibt die Pixelmaße des imaginären Raums zurück, der vom TextRange-Objekt belegt wird. Obwohl Sie kein TextRange-Objekt im Dokument sehen (es sei denn, ein Skript wählt es aus), ist der Bereich eines TextRange-Objekts identisch mit dem Bereich, den eine Auswahlmarkierung belegen würde. Diese Werte ziehen sich so zusammen, dass nur der breiteste und höchste Teil des Bereichs angenommen wird. Dieselben Werte könnten Sie auch anhand der von der Methode getBoundingClientRect( ) zurückgegebenen Werte errechnen.
Beispiel
    var rangeWidth = document.forms[0].myTextArea.createTextRange( ).boundingWidth;
Wert
Eine ganze Zahl.
Standardwert
Keiner.

boundingLeft, boundingTop | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
| Schreibgeschützt
Geben den Pixelabstand zwischen dem oberen oder linken Rand des Browserfensters bzw. Frames und der oberen bzw. linken Begrenzung des imaginären Raums zurück, der vom TextRange-Objekt belegt wird. Obwohl Sie kein TextRange-Objekt im Dokument sehen (es sei denn, ein Skript wählt es aus), ist der Bereich eines TextRange-Objekts identisch mit dem Bereich, den eine Auswahlmarkierung belegen würde. Die Werte für diese Eigenschaften werden von den feststehenden Fenster- bzw. Frameseiten und nicht vom oberen und linken Rand des Dokuments gemessen, der aus dem Anzeigebereich gerollt sein könnte. Daher ändern sich diese Werte, wenn das Dokument gerollt wird.
Beispiel
    var rangeOffH = document.forms[0].myTextArea.createTextRange( ).boundingLeft;
Wert
Eine ganze Zahl.
Standardwert
Keiner.

htmlText | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
| Schreibgeschützt
Legt den gesamten HTML-Code des Dokuments für ein bestimmtes Element fest, wenn dieses als Grundlage für ein TextRange-Objekt verwendet wird. Wenn Sie z. B. mit der Methode document.body.createTextRange( ) einen TextRange für das body-Element erstellen, enthält die Eigenschaft htmlText den gesamten HTML-Inhalt zwischen den body-Element-Tags (ohne die Tags selbst).
Beispiel
    var rangeHTML = document.body.createTextRange( ).htmlText;
Wert
Zeichenfolge.
Standardwert
Keiner.

text | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
| Lesen/Schreiben
Gibt den im Textbereich enthaltenen Text an. Im Falle des TextRange-Objekts eines body-Elements besteht dieser nur aus dem dargestellten Text ohne den HTML-Tags im Hintergrund.
Beispiel
    var rangeText = document.body.createTextRange( ).text;
Wert
Zeichenfolge.
Standardwert
Keiner.

collapse( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
collapse([start]) |
Reduziert das TextRange-Objekt auf eine Länge von Null (es wird ein Einfügepunkt erstellt) am Anfang oder am Ende des Textbereichs, bevor es zusammengezogen wird.
Parameter
Optionaler Boolescher Wert, der steuert, ob der Einfügepunkt An den Anfang (true) oder an das Ende (false) des ursprünglichen Bereichs gesetzt wird. Der Standardwert ist true.
Zurückgegebener Wert
Keiner.

compareEndPoints( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
compareEndPoints("type", comparisonRange) |
Vergleicht die relative Position der Begrenzungspunkte (Anfang und Ende) zweier Bereiche (der aktuelle Bereich und ein Bereich, der zuvor in einer Variablen gespeichert wurde). Der erste Parameter definiert, welche Begrenzungspunkte in den Bereichen verglichen werden sollen. Wenn der Vergleich ergibt, dass der erste Punkt im Bereich vor dem zweiten Punkt liegt, wird der Wert -1 zurückgegeben. Liegen beide Punkte an derselben Position, lautet der Rückgabewert 0. Wenn der Vergleich ergibt, dass der erste Punkt im Bereich hinter dem zweiten Punkt liegt, wird der Wert 1 zurückgegeben. Haben Sie z. B. den ersten Bereich in einer Variablen r1 gespeichert und einen neuen Bereich als r2 erstellt, erhalten Sie die physische Beziehung zwischen dem Ende von r2 und dem Anfang von r1:
    r1.compareEndPoints("EndToStart", r2)
Wenn r1 an dem Punkt endet, an dem r2 beginnt (dem Einfügepunkt zwischen zwei Zeichen), lautet der zurückgegebene Wert 0.
Parameter
Einer der folgenden Konstanten (als Zeichenfolge): StartToEnd | StartToStart | EndToStart | EndToEnd. Ein TextRange-Objekt, das zuvor erstellt und in einer Variablen gespeichert wurde.
Zurückgegebener Wert
-1, 0 oder 1.

duplicate( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
Erstellt ein neues TextRange-Objekt mit den gleichen Werten wie der aktuelle Bereich. Das neue Objekt ist ein unabhängiges Objekt (das alte und neue Objekt sind nicht gleich), aber deren Werte sind anfänglich identisch (bis Sie eine Änderung an dem einen oder anderen Bereich vornehmen).
Parameter
Keine.
Zurückgegebener Wert
TextRange-Objekt.

execCommand( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
execCommand("commandName"[, UIFlag[, value]]) |
Führt den benannten Befehl am aktuellen TextRange-Objekt aus. Viele Befehle funktionieren am besten, wenn das TextRange-Objekt ein Einfügepunkt ist. Eine Liste der Befehle finden Sie in Anhang D.
Parameter
Eine von der Groß-/Kleinschreibung unabhängige Zeichenfolge mit dem Befehlsnamen. Siehe Anhang D. Optionaler Boolescher Wert: true, um eine Benutzeroberfläche anzuzeigen, die durch den Befehl ausgelöst wird (falls vorhanden); false, um eine solche Anzeige zu verhindern. Ein Parameterwert für diesen Befehl.
Zurückgegebener Wert
Boolescher Wert: true, wenn der Befehl erfolgreich war; false, wenn der Befehl nicht erfolgreich war.

expand( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
expand("unit") |
Erweitert den aktuellen Textbereich (auch wenn es sich um einen zusammengezogenen Bereich handelt) so, dass er die als Parameter übergebene Texteinheit umfasst. Wenn beispielsweise ein Benutzer einige Zeichen im Dokument markiert, können Sie einen Bereich erstellen, und diesen so erweitern, dass er den gesamten Satz umfasst, in dem Zeichen markiert wurden:
    var rng = document.selection.createRange( );
    rng.expand("sentence");
Umfasst der Anfangsbereich bereits mehrere Einheiten, wird die Methode expand( ) nach außen bis zur nächstgelegenen Einheit erweitert.
Parameter
Eine von der Groß-/Kleinschreibung unabhängige Zeichenfolge, die die gewünschte Einheit angibt: character | word | sentence | textedit. Der Wert textedit erweitert den Bereich auf den gesamten Originalbereich.
Zurückgegebener Wert
Boolescher Wert: true, wenn die Methode erfolgreich war; false, wenn nicht.

findText( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
findText("string"[, searchScope][, flags]) |
Durchsucht das aktuelle TextRange-Objekt nach einer Übereinstimmung mit einer Zeichenfolge, die im erforderlichen ersten Parameter übergeben wurde. Standardmäßig ist die Übereinstimmung von der Groß-/Kleinschreibung unabhängig. Bei einer Übereinstimmung werden die Anfangs- und Endpunkte des TextRange-Objekts so positioniert, dass sie den gefundenen Text umgeben. Um die Suche im Dokument fortzusetzen, müssen Sie den Anfangspunkt des Textbereichs auf das Ende der gefundenen Zeichenfolge setzen (mit collapse( )).
Mithilfe optionaler Parameter können Sie die Suche im Bereich auf eine bestimmte Anzahl von Zeichen ab dem Startpunkt des Bereichs begrenzen oder zusätzliche Suchkriterien festlegen (z. B. Wortteile oder ganze Wörter).
Parameter
Eine zu suchende Zeichenfolge, unabhängig von der Groß-/Kleinschreibung. Ganze Zahl, die die Anzahl der zu suchenden Zeichen ab dem Startpunkt des Bereichs angibt. Ein positiver Wert bewirkt, dass der Text vorwärts, ein negativer Wert, dass der Text vor dem Startpunkt des Textbereichs aus in Rückwärtsrichtung durchsucht wird. Ganze Zahl, die die genaue Art der Suche angibt: 0 (Wortteile); 1 (Rückwärtssuche); 2 (nur ganze Wörter); 4 (Groß-/Kleinschreibung beachten).
Zurückgegebener Wert
Boolescher Wert: true, wenn eine Übereinstimmung gefunden wurde; false, wenn nicht.

getBookmark( ), moveToBookmark( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
getBookmark( ) moveToBookmark(bookmarkString) |
Diese zwei Methoden arbeiten zusammen und bieten die Möglichkeit, einen Textbereich temporär zwischenzuspeichern und ggf. wiederherzustellen. Die Methode getBookmark( ) gibt eine undurchsichtige Zeichenfolge zurück (mit Binärdaten, die für Benutzer keinen Sinn ergeben). Nachdem dieser Wert in einer Variablen gespeichert wurde, kann der Bereich für das Skript geändert werden. Später kann dieser mit einem Lesezeichen versehene Text mit der moveToBookmark( )-Methode wiederhergestellt werden:
    var rangeMark = myRange.getBookmark( );
    ...
    myRange.moveToBookmark(rangeMark);
Parameter
Die undurchsichtige Zeichenfolge, die von der getBookmark( )-Methode zurückgegeben wird.
Zurückgegebener Wert
Boolescher Wert: true, wenn der Vorgang erfolgreich war; false, wenn nicht.

inRange( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
inRange(comparisonRange) |
Legt fest, ob der Vergleichsbereich physisch im aktuellen Textbereich liegt oder ihm entspricht.
Parameter
TextRange-Objekt, das zuvor erstellt und in einer Variablen gespeichert wurde.
Zurückgegebener Wert
Boolescher Wert: true, wenn der Vergleichsbereich im aktuellen Bereich liegt oder ihm entspricht; false, wenn nicht.

isEqual( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
isEqual(comparisonRange) |
Legt fest, ob der Vergleichsbereich identisch mit dem aktuellen Textbereich ist.
Parameter
Ein TextRange-Objekt, das zuvor erstellt und in einer Variablen gespeichert wurde.
Zurückgegebener Wert
Boolescher Wert: true, wenn der Vergleichsbereich mit dem aktuellen Bereich identisch ist; false, wenn nicht.

move( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
move("unit"[, count]) |
Zieht den aktuellen Textbereich auf einen Einfügepunkt am Ende des aktuellen Bereichs zusammen und verschiebt ihn um eine oder mehrere Einheiten rückwärts von der aktuellen Position.
Parameter
Eine von der Groß-/Kleinschreibung unabhängige Zeichenfolge, die die gewünschte Einheit angibt: character | word | sentence | textedit. Der Wert textedit verschiebt den Einfügepunkt an den Anfang oder das Ende des gesamten Ursprungsbereichs. Eine optionale ganze Zahl der Einheiten, um die der Einfügepunkt verschoben werden soll. Positive Werte verschieben den Punkt vorwärts, negative Werte rückwärts. Der Standardwert ist 1.
Zurückgegebener Wert
Ganzzahliger Wert, der angibt, wie viele Einheiten verschoben werden sollen.

moveEnd( ), moveStart( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
moveEnd("unit"[, count]) moveStart("unit"[, count]) |
Verschiebt nur den Anfangs- oder Endpunkt des aktuellen Textbereichs um eine oder mehrere Einheiten. Mit einem optionalen Parameter können Sie die Anzahl der Einheiten und die Richtung definieren. Um den Anfangspunkt eines Textbereichs zum Anfang des Ursprungsbereichs hin zu verschieben, müssen Sie einen negativen Wert eingeben. Denken Sie beim Verschieben des Endpunktes um Worteinheiten nach rechts daran, dass ein Wort mit einem Leerzeichen (und gegebenenfalls einem Punkt) endet. Wenn also eine findText( )-Methode den Bereich auf eine gefundene Zeichenfolge setzt, die nicht mit einem Leerzeichen endet, verschiebt die erste moveEnd("word")-Methode den Endpunkt an eine Stelle hinter dem Leerzeichen, das der gefundenen Zeichenfolge folgt, und nicht zum folgenden Wort.
Parameter
Eine von der Groß-/Kleinschreibung unabhängige Zeichenfolge, die die gewünschte Einheit angibt: character | word | sentence | textedit. Der Wert textedit verschiebt den Einfügepunkt an den Anfang oder das Ende des gesamten Ursprungsbereichs. Eine optionale ganze Zahl der Einheiten, um die der Einfügepunkt verschoben werden soll. Positive Werte verschieben den Punkt vorwärts, negative Werte rückwärts. Der Standardwert ist 1.
Zurückgegebener Wert
Ganzzahliger Wert, der angibt, wie viele Einheiten verschoben werden sollen.

moveToBookmark( ) |
Siehe getBookmark( ).

moveToElementText( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
moveToElementText(elementObject) |
Verschiebt die aktuellen Anfangs- und Endpunkte des TextRange-Objekts so, dass sie das angegebene HTML-Elementobjekt umschließen. Der resultierende Textbereich enthält auch den HTML-Code für das Element.
Parameter
Eine Skriptreferenz zum Objekt. Diese kann in Form einer direkten Referenz (document.getElementByID("elementID") oder in Form einer Variable vorliegen, die einen gleichartigen Wert enthält.
Zurückgegebener Wert
Keiner.

moveToPoint( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
moveToPoint(x, y) |
Zieht den Textbereich zu einem Einfügepunkt zusammen und setzt dessen Position an die Stelle, die durch die horizontalen und vertikalen Koordinaten im Browserfenster bzw. Frame angegeben ist. Dies verhält sich genau so, als hätte ein Benutzer an einer Stelle im Fenster geklickt, um einen Einfügepunkt zu definieren. Verwenden Sie Methoden wie expand( ) zum Vergrößern des Textbereichs, damit er ein Zeichen, Wort, Satz oder einen gesamten Textbereich umfasst.
Parameter
Horizontale Koordinate des Einfügepunkts relativ zum linken Rand des Fensters bzw. Frames (in Pixel). Vertikale Koordinate des Einfügepunkts relativ zum oberen Rand des Fensters bzw. Frames (in Pixel).
Zurückgegebener Wert
Keiner.

parentElement( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
Gibt eine Objektreferenz zum nächstäußersten Element zurück, in dem das TextRange-Objekt vollständig enthalten ist.
Parameter
Keine.
Zurückgegebener Wert
Elementobjektreferenz.

pasteHTML( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
pasteHTML("HTMLText") |
Ersetzt den aktuellen Textbereich durch den HTML-Inhalt, der als Zeichenfolge im Parameter übergeben wird. In der Regel wird diese Methode für einen Textbereich mit der Länge Null verwendet, der als Einfügemarke fungiert. Alle Tags werden so dargestellt, als seien sie Teil des ursprünglichen Quellcodes.
Parameter
Dokumentquellcode, der in das Dokument eingefügt werden soll.
Zurückgegebener Wert
Keiner.

queryCommandEnabled( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
queryCommandEnabled("commandName") |
Gibt an, ob der Befehl angesichts des aktuellen Zustands des Dokuments bzw. der Auswahl aufgerufen werden kann.
Parameter
Eine von der Groß-/Kleinschreibung unabhängige Zeichenfolge mit dem Befehlsnamen. Siehe Anhang D.
Zurückgegebener Wert
Boolescher Wert: true, wenn aktiviert; false, wenn deaktiviert.

queryCommandIndeterm( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
queryCommandIndeterm("commandName") |
Gibt an, ob sich der Befehl in einem unbestimmten Zustand befindet.
Parameter
Eine von der Groß-/Kleinschreibung unabhängige Zeichenfolge mit dem Befehlsnamen. Siehe Anhang D.
Zurückgegebener Wert
Boolescher Wert: true | false.

queryCommandState( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
queryCommandState("commandName") |
Bestimmt den aktuellen Zustand des benannten Befehls.
Parameter
Eine von der Groß-/Kleinschreibung unabhängige Zeichenfolge mit dem Befehlsnamen. Siehe Anhang D.
Zurückgegebener Wert
true, wenn der Befehl abgeschlossen wurde; false, wenn der Befehl nicht abgeschlossen wurde; null, wenn der Zustand nicht genau bestimmt werden kann.

queryCommandSupported( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
queryCommandSupported("commandName") |
Bestimmt, ob der benannte Befehl vom Dokumentobjekt unterstützt wird.
Parameter
Eine von der Groß-/Kleinschreibung unabhängige Zeichenfolge mit dem Befehlsnamen. Siehe Anhang D.
Zurückgegebener Wert
Boolescher Wert: true | false.

queryCommandText( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
queryCommandText("commandName") |
Gibt den Text zurück, der dem Befehl zugewiesen ist.
Parameter
Eine von der Groß-/Kleinschreibung unabhängige Zeichenfolge mit dem Befehlsnamen. Siehe Anhang D.
Zurückgegebener Wert
Zeichenfolge.

queryCommandValue( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
queryCommandValue("commandName") |
Gibt den Wert zurück, der dem Befehl zugewiesen ist, z. B. den Schriftnamen der Auswahl.
Parameter
Eine von der Groß-/Kleinschreibung unabhängige Zeichenfolge mit dem Befehlsnamen. Siehe Anhang D.
Zurückgegebener Wert
Hängt vom Befehl ab.

select( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
Wählt den gesamten Text aus, der im aktuellen TextRange-Objekt enthalten ist. Diese Methode liefert den Benutzern eine sichtbare Bestätigung, dass ein Skript über einen bestimmten Textblock informiert ist. Wenn Sie beispielsweise ein Skript für eine Suchzeichenfolge mit der findText( )-Methode erstellen, würden Sie die Methoden scrollIntoView( ) und select( ) für diesen Bereich verwenden, um dem Benutzer zu zeigen, wo sich der übereinstimmende Text befindet.
Parameter
Keine.
Zurückgegebener Wert
Keiner.

setEndPoint( ) | NN nicht zutreffend IE 4(Win) DOM nicht zutreffend
setEndPoint("type", comparisonRange) |
Setzt den Endpunkt des aktuellen TextRange-Objekts auf den Endpunkt des anderen Bereichs, der zuvor in einer Variablen gespeichert wurde.
Parameter
Einer der folgenden Konstanten (als Zeichenfolge): StartToEnd | StartToStart | EndToStart | EndToEnd. Ein TextRange-Objekt, das zuvor erstellt und in einer Variablen gespeichert wurde.
Zurückgegebener Wert
Keiner.