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 | |||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||
Objektspezifische Methoden | |||||||||||||||||||||||||||
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
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 | |
|
|
Zurückgegebener Wert | |
Keiner. |