JavaScript: TextRange (Objekt)
von Jan Winkler
Das clientseitige TextRange-Objekt definiert ein Textobjekt über den Text eines Elements oder einer Markierung (etc.). Es besitzt entsprechende Eigenschaften und Methoden zum Verarbeiten des Textes.
Die boundingHeight-Eigenschaft gibt die Höhe des Rechtecks in Pixel an, das sich um den Text befindet. Die boundingWidth-Eigenschaft gibt die entsprechende Breite an.
Notation: Objekt.boundingHeight
Notation: Objekt.boundingWidth
Kein Beispiel.
Die boundingLeft-Eigenschaft gibt den horizontalen Abstand des Textrechtecks in Pixel an, relativ zum linken Rand des Elternelements. Die boundingTop-Eigenschaft gibt den entsprechenden Abstand in vertikaler Richtung an.
Notation: Objekt.boundingLeft
Notation: Objekt.boundingTop
Kein Beispiel.
Die htmlText-Eigenschaft gibt den (HTML-) Quellcode des Textes an. Diese Eigenschaft ist schreibgeschützt.
Notation: Objekt.htmlText
a = document.body.createTextRange().htmlText;
Die offsetLeft-Eigenschaft gibt den berechneten Abstand horizontal des Textrechtecks in Pixel an, relativ zum linken Rand des Elternelements. Die offsetTop-Eigenschaft gibt den entsprechenden Abstand in vertikaler Richtung an.
Notation: Objekt.offsetLeft
Notation: Objekt.offsetTop
Kein Beispiel.
Die text-Eigenschaft gibt oder setzt den Inhalt (Text) des Objekts.
Notation: Objekt.text
document.body.createTextRange().text = 'Neuer Inhalt';
Die collapse-Methode bewegt den Textcursor (Stelle an dem der getippte Text eingefügt wird) an den Anfang (true / Standard) oder das Ende (false). Als Übergabewert muss ein entsprechender boolescher Ausdruck übergeben werden.
Notation: Objekt.collapse([Ort])
document.all.meinEingabefeld.createTextRange().collapse(true);
Die compareEndPoints-Methode vergleicht Start- und/oder Endpunkte von zwei TextRange-Objekten und gibt die Lage aus. Als Parameter wird dazu einer der folgenden Strings, sowie ein zu vergleichendes TextRange-Objekt erwartet (in dieser Reihenfolge). Mögliche Strings für Parameter 1:
-
StartToEnd - Vergleich Startpunkt der Quelle mit dem Endpunkt des übergeben Objekts.
-
StartToStart - Vergleich Startpunkt der Quelle mit dem Startpunkt des übergeben Objekts.
-
EndToStart - Vergleich Endpunkt der Quelle mit dem Startpunkt des übergeben Objekts.
-
EndToEnd - Vergleich Endpunkt der Quelle mit dem Endpunkt des übergeben Objekts.
Als Resultat gibt die Methode -1 aus wenn der Punkt der Quelle weiter links liegt als der des übergebenen Objekts. Es wird 0 zurückgegeben wenn beide Punkte am gleichen Platz legen und es wird 1 zurückgegeben, wenn der Punkt der Quelle weiter rechts liegt als der Punkt des übergebenen Objekts.
Notation: Objekt.compareEndPoints(Art,TextRange)
Kein Beispiel.
Die duplicate-Methode kopiert das Objekt und gibt die Kopie aus.
Notation: Objekt.duplicate()
a = document.body.createTextRange();
b = a.duplicate(); // a == b
Die execCommand-Methode führt eine bestimmte Funktion auf das Dokument, die Markierung oder einen Bereich aus. Als erster Parameter wird ein Command Identifier erwartet. Als zweiter und dritter Parameter folgen optional die entsprechenden Werte von vUserInterface und vValue (siehe Anhang).
Notation: Objekt.execCommand(ComInd[,vUserInterface,vValue])
document.body.createTextRange().execCommand('Bold');
Die expand-Methode erweitert den Bereich des Objekts, so dass bestimmte Dinge komplett eingeschlossen werden. Als Parameter kann einer der folgenden Strings übergeben werden:
-
character - Erweitert um ein Zeichen.
-
word - Erweitert um ein Wort oder vervollständigt ein angefangenes Wort.
-
sentence - Vervollständigt den Satz.
-
textedit - Vervollständigt den gesamten Text.
Die Methode gibt true aus, wenn der Text erweitert werden konnte - ansonsten false.
Notation: Objekt.expand(Art)
<input onMouseOut="machwas()" type="Text"
value="Markieren Sie einige Wörter dieses Satzes. Oder von diesem.">
<script language="JScript">
<!--
function machwas()
{
a = document.selection.createRange();
org = a.text;
dup = a; dup.expand("character"); ch = dup.text;
dup = a; dup.expand("word"); wo = dup.text;
dup = a; dup.expand("sentence"); sen = dup.text;
dup = a; dup.expand("textedit"); te = dup.text;
alert('Orginal: '+org+
'\nCharacter: '+ch+
'\nWord: '+wo+
'\nSentence: '+sen+
'\nTextedit: '+te);
}
//-->
</script>
Die findText-Methode sucht innerhalb des Objekttextes nach einem bestimmten String und setzt das Objekt auf den gefundenen String an (begrenzt den Inhalt auf den String). Die Methode erwartet als ersten Parameter den zu suchenden String. Als zweiter Parameter kann optional der Startindex der Suche übergeben werden, bei welchem Zeichen die Suche beginnen soll - negative Werte bedeuten hierbei, dass es sich um eine Suche von hinten nach vorn handeln soll. Als dritter und ebenfalls optionaler Parameter kann einer der folgenden Zahlen und deren durch Addition ergebenen Kombinationen angegeben werden:
- 0 - Standard.
- 1 - Standard mit Rückwärtssuche.
- 2 - Nur ganze Wörter werden gefunden.
- 4 - Groß- und Kleinschreibung beachten.
Notation: Objekt.findText(Text[,Anfang,Modus])
function ersetzen(von,nach)
{
a = document.selection.createRange();
a.findText(von);
a.text = nach;
}
Die getBookmark-Methode erzeugt einen eindeutigen zusammenhängenden String (Bookmark) und gibt diesen aus. Der String kann später dazu verwendet werden um wieder zu dieser Textstelle zurück kehren zu können.
Notation: Objekt.getBookmark()
a = meinRange.getBookmark();
andererRange.moveToBookmark(a);
Die getBoundingClientRect-Methode gibt ein TextRectangle-Objekt aus, dass die Koordinaten des TextRange's beschreibt.
Notation: Objekt.getBoundingClientRect()
a = meinRange.getBoundingClientRect();
Die getClientRects-Methode gibt eine Kollektion von TextRectangle-Objekten aus. Jedes Objekt der Kollektion beschreibt dabei eine Zeile des TextRange's.
Notation: Objekt.getClientRects()
a = meinRange.getClientRects();
for(i=0; i<a.length; i++)
{
b = a[i];
// mit b arbeiten
}
Die inRange-Methode prüft, ob sich ein übergebenes TextRange-Objekt innerhalb des Objektbereiches befindet (true) oder nicht (false). Die Methode gibt den entsprechenden booleschen Wert aus.
Notation: Objekt.inRange(TextRange)
r1 = document.body.createTextRange();
r2 = document.selection.createRange();
a = r1.inRange(r2); // sollte true sein
Die isEqual-Methode überprüft, ob ein übergebenes TextRange-Objekt dem Quellobjekt entspricht (true) oder nicht (false). Die Methode gibt den entsprechenden booleschen Wert aus.
Notation: Objekt.isEqual(TextRange)
r1 = document.body.createTextRange();
r2 = document.selection.createRange();
a = r1.isEqual(r2); // sollte false sein
Die move-Methode verringert den Bereich des Objekts (ohne den Text zu löschen) und bewegt den Anfang des leeren Objekts. Als erster Parameter muss die Maßeinheit der Verschiebung festgelegt werde. Hier sind die folgenden Strings möglich:
-
character - Springt zum nächsten Zeichen.
-
word - Springt zum nächsten Wort.
-
sentence - Springt zum nächsten Satz.
-
textedit - Springt zum nächsten Text.
Als zweiter Parameter kann optional eine Zahl angegeben werden um wieviele Maßeinheiten weiter (positive Zahl) bzw. zurück (negative Zahl) gesprungen werden soll. Standardwert ist 1.
Die Methode gibt eine Zahl aus um wieviele Einheiten gesprungen werden konnte.
Notation: Objekt.move(Art[,Anzahl])
<div onmouseout="machwas()">Markieren Sie diesen Satz. Satz 2. Satz 3.</div>
<script language="JScript">
<!--
function machwas()
{
a = document.selection.createRange();
a.move('character'); a.text = 'C';
a.move('word'); a.text = 'W';
a.move('sentence'); a.text = 'S';
a.move('textedit'); a.text = 'T';
}
//-->
</script>
Die moveStart-Methode setzt den Start des TextRange's um. Der Bereich des Objekts wird damit größer bzw. kleiner. Die moveEnd-Methode setzt das Ende des TextRange's um. Beide Methoden erwarteten einen der folgenden Strings und können optional die Anzahl der zu verschiebenden Einheiten als weiteren Parameter übergeben bekommen (siehe move-Methode).
-
character - Springt zum nächsten Zeichen.
-
word - Springt zum nächsten Wort.
-
sentence - Springt zum nächsten Satz.
-
textedit - Springt zum nächsten Text.
Die Methoden geben eine Zahl aus, die beschreibt um wieviele Einheiten der Bereich verkürzt bzw. verlängert wurde.
Notation: Objekt.moveStart(Art[,Anzahl])
Notation: Objekt.moveEnd(Art[,Anzahl])
a = document.selection.createRange();
a.moveEnd('word',1); a.text = a.text+'[Wortende]';
a.moveEnd('sentence',2); a.text = a.text+'[Satzende]';
a.moveStart('word',1); a.text = '[Wortanfang]'+a.text;
Die moveToBookmark-Methode setzt das Objekt auf den Text, der zuvor in einem Bookmark gespeichert wurde (getBookmark-Methode). Als Parameter wird der Bookmark erwartet.
Notation: Objekt.moveToBookmark(Bookmark)
Beispiel siehe getBookmark-Methode.
Die moveToElementText-Methode setzt das Objekt auf den Text eines Elements. Als Parameter wird eine Referenz zu einem bestehenden (HTML-)Element erwartet.
Notation: Objekt.moveToElementText(Element)
r = document.body.createTextRange();
r.moveToElementText(document.all.meinElement);
Die moveToPoint-Methode setzt den Start- und Endpunkt des Bereiches auf eine bestimmte Koordinate. Als Übergabewerte werden die entsprechenden x- und y-Koordinaten in Pixel erwartet (in dieser Reihenfolge).
Notation: Objekt.moveToPoint(x,y)
Kein Beispiel.
Die parentElement-Methode gibt das Elternelement aus, das dem Text des Objekts entspricht.
Notation: Objekt.parentElement()
Kein Beispiel.
Die pasteHTML-Methode ersetzt den Inhalt (Text inklusive HTML-Code) durch den zu übergebenden String. Im String kann wiederum HTML-Code verwendet werden - dieser wird in die Seite eingebunden.
Notation: Objekt.pasteHTML(Code)
a = document.selection.createRange();
a.pasteHTML('<b>'+a.text+'</b>');
Die queryCommandEnabled-Methode prüft, ob ein Command Identifier bereits eingeschaltet ist (true) oder nicht (false). Als Parameter wird der entsprechende String erwartet.
Notation: Objekt.queryCommandEnabled(ComInd)
a = document.selection.createRange();
if(a.queryCommandEnabled('Bold') == false)
{a.execCommand('Bold');}
Die queryCommandIndeterm-Methode prüft, ob ein Command Identifier in einem Übergangsstadium ist (true) oder nicht (false). Als Parameter wird der entsprechende String erwartet.
Notation: Objekt.queryCommandIndeterm(ComInd)
Kein Beispiel.
Die queryCommandState-Methode gibt an in welchem Status sich ein Command Identifier befindet. true bedeutet, dass der Command Identifier bereits auf das Objekt ausgeführt wurde - false bedeutet das Gegenteil ist der Fall. Als Parameter wird der entsprechende String erwartet.
Notation: Objekt.queryCommandState(ComInd)
Kein Beispiel.
Die queryCommandSupported-Methode prüft, ob der Command Identifier ausführbar ist (true) oder nicht (false). Als Parameter wird der entsprechende String erwartet.
Notation: Objekt.queryCommandSupported(ComInd)
Kein Beispiel.
Die queryCommandValue-Methode gibt den aktuellen vValue Wert eines Command Identifiers aus. Als Parameter wird der entsprechende String erwartet.
Notation: Objekt.queryCommandValue(ComInd)
Kein Beispiel.
Die scrollIntoView-Methode veranlaßt, dass das Dokument soweit gescrollt wird, bis das Objekt sichtbar ist. Optional kann ein boolescher Parameter angegeben werden, der beschreibt, ob der Bildschirm soweit gescrollt werden soll bis das Objekt am oberen (true / Standard) bzw. unterem (false) Bildschirmrand sichtbar ist.
Notation: Objekt.scrollIntoView([Ort])
function suche(s)
{
r = document.body.createTextRange();
r.findText(s);
r.select();
r.scrollIntoView(true);
}
Die select-Methode veranlaßt, dass der Bereich des Objekts markiert/ausgewählt wird.
Notation: Objekt.select()
Beispiel siehe scrollIntoView-Methode.
Die setEndPoint-Methode setzt den eigenen Start- oder Endpunkt auf den Start- oder Endpunkt eines anderen TextRange-Objekts. Als erster Parameter wird dazu einer der folgenden Strings erwartet:
-
EndToEnd - Setzt den Endpunkt auf den Endpunkt des übergebenen Objekts.
-
EndToStart - Setzt den Endpunkt auf den Startpunkt des übergebenen Objekts.
-
StartToEnd - Setzt den Startpunkt auf den Endpunkt des übergebenen Objekts.
-
StartToStart - Setzt den Startpunkt auf den Startpunkt des übergebenen Objekts.
Als zweiter Parameter wird das entsprechende TextRange-Objekt benötigt.
Notation: Objekt.setEndPoint(Art,TextRange)
Kein Beispiel.
