TextRange對象參考

原文來自TextRange object。
textRange對象表明document中一個連續的部分。

TextRange對象爲實現一些實用功能提供了幾個屬性和方法。利用TextRange對象，你能夠取得並修改文檔的任意部分；你能夠獲得文檔中的一個連續部分的定位以及一些其它的幾何屬性；你能夠取得並修改文檔中已選中的內容。

Internet Explorer以及部分Opera瀏覽器支持TextRange對象。

在火狐、Opera、Google Chrome以及Safari中，Range對象提供了簡單的功能。Internet Explorer 9.0之後的版本一樣支持Range對象。

由於全部的現代瀏覽器都支持Range對象，只有在Range對象不被支持的狀況下才使用TextRange對象。本文後面的內容將一塊兒介紹這兩個對象。

建立一個TextRange對象有三個方法：

• 經過createTextRange方法建立一個TextRange對象。body對象以及一些其它的HTML元素支持createTextRange方法。新建立的TextRange對象的邊界點（開始點和結束點）與這些HTML元素的內容對齊。
  
  
  • 你可使用document.createRange方法建立一個空的Range對象。後面的章節描述了修改一個Range對象的邊界點的方法。

• 在Internet Explorer中，有三種不一樣類型的選區（selection）：

  • 控件選區 - 選區包含了控件。
  • 文本選區 - 選區只包含文本。
  • 空選區 - 即沒有選區（或者說選中的內容是不可用的）。

  利用selection對象的type屬性能夠獲得選區的類型。當選區包含文本或者沒有選中的內容時，用selection對象的createRange方法能夠取得一個TextRange對象。返回的TextRange對象的邊界點與選區的內容對齊。

  爲了獲得選區的內容，selection對象還支持其它的方法，好比說createRangeCollection方法，它返回一個TextRanges集合，包含了若干個TextRange對象。每一個TextRange對象表明這個選區的一個連續部分。該createRangeCollection方法對多重選區來講頗有用。可是Internet Explorer不支持它。因此使用createRange方法就足夠了。

  使用selectionRange對象的getRangeAt方法能夠取得一個表明當前選區的Range對象。selectRange對象能夠包含超過一個Range對象。每一個Range對象表明選區的一個連續部分。

  在Internet Explorer、Opera、Google Chrome、Safari以及低於3.0版本的火狐瀏覽器中，至少有一個Range對象屬於selectionRange對象，由於文本選區永遠是一個DOM層次結構的連續部分。

  在3.0版之後的火狐瀏覽器中，鼠標選網頁內容時按住Ctrl鍵，能夠選中多個文本域。若是你想選中離散的文本塊，請使用addRange方法。

• 使用duplicate方法能夠複製出一個已有的TextRange對象的副本。返回的對象與原始對象徹底相同。

若是已存在一個TextRange對象的實例，你能夠用下面的方法修改它的邊界：

• 若是你想把一個TextRange對象的邊界點與一個元素的內容對齊，並且這個元素支持createTextRange方法，請在這個元素上使用createTextRange方法。對其它元素，請使用body.createTextRange方法來建立一個TExtRange對象，並對這個必要的元素使用moveToElementText方法。

  若是你想把一個Range對象的邊界點與一個元素或元素的內容對齊，請使用selectNode或selectNodeContents方法。

• 使用moveStart方法和moveEnd方法能夠移動一個TextRange對象的開始點的結束點。若是你想把一個TextRange對象的開始點和結束點與另外一個TextRange對象的開始點和結束點對齊，請使用setEndPoint方法。

  若是你想分別地修改一個Range的開始點和結束點，請使用setStart方法、setStartBefore方法、setStartAfter方法，以及setEnd方法、setEndBefore方法、setEndAfter方法。

• 利用collapse方法，你能夠移動開始點或者結束點，反之亦然。TextRange對象和Range對象均可以用這個方法。

• 擴展TextRange對象的內容，請使用expand方法以實現它。

若是你一個TextRange對象的定位，你能夠：

• 利用offsetLeftc以及offsetTop屬性，能夠獲得該TextRange對象的座標。不能取得該元素以及一個TextRamge對象用開始點和結束點定義的偏移。

  • 若是你要取得一個TextRange對象的矩形邊界，請使用boundingLeft、boundingTop、boundWidth以及boundingHeight屬性。

  • 若是你要取得一個TextRange對象的準確形狀，請使用getClientRects方法。它將取得一個TextRectangles集合，包含了幾個TextRectangle對象。每一個TextRectangle對象表明屬於這個TextRange對象的一行文本。

  上面的提到全部的座標都是相對於瀏覽器窗口的左上角的。

  • document.elementFromPoint方法能夠幫助你取得位於指定座標上的元素。

  • 這個包含了整個TextRange對象的元素，若是你想要取得它在DOM層次結構中元素的深度，請使用parentElement方法。

  一個Range對象是用開始點和結束點定義的。一個元素以及一個位置定義了一個點。若是這個元素只有文本內容（TextNode、CDATASection或者CommentNode），這個位置指定了元素中的一個字符位置；若是這個元素並不是只有文本內容，這個位置指定了元素中一個子元素的序號索引。

  和(endContainer,endOffset)屬性指定了一個Range對象的開始點和結束點。startOffset屬性指定在這個startContainer元素中Range開始的位置。endOffset屬性指定了在這個endContainer元素中Range結束的位置。

  若是你想取得包含了整個Range對象的元素在DOM層次結構中節點的深度，請使用commonAncestorContainer屬性。

• 當一個TextRange的開始點和結束點是同一個位置的時候，這個TextRange對象就是收縮的。你能夠用多種方法來檢測它是否處於收縮狀態。好比說，用TextRange對象的文本內容來檢測。用text屬性可取得一個TextRange對象的文本內容，並做爲字符串來對待。若是這個text屬性表明的字符串的長度返回0，則TextRange對象是收縮的。

  使用collapsed方法能夠檢測Range對象是否處於收縮狀態。

• 比較兩個TextRange對象的定位，可使用compareEndPoints方法。它比較了這些對象的邊界點。

  要想檢測一個TextRange對象是否包含另外一個TextRange對象，能夠用inRange方法。isEqual方法檢測兩個TextRange對象是不是徹底相同的。

  兩個Range對象的定位能夠經過compareboundaryPoint方法來比較。它比較了這些對象的邊界，相似於TextRange對象中的compareEndPoints方法。

  請注意，雖然compareboundaryPoints方法和compareEndPoints方法的語法是類似的，可是一樣的案例，在不一樣的瀏覽器中，它們的行爲是不一樣的。請閱讀這兩個方法的頁面以瞭解詳細區別。

  若是你想檢測一個點（一個(element,position)對，其中position指定了element內部的一個索引或者說一個字符位置）是否位於一個Range內部，請使用comparePoint或者isPointInRange方法。

操做一個TextRange對象的內容：

• text屬性可以設置或取得一個TextRange對象的文本內容，做爲一個字符串。

  若是你須要HTML格式的內容，請使用htmlText屬性。

  若是要替換一個帶有HTML格式文本的TextRange對象的內容，請使用pasteHTML方法。你還能夠用這個方法來刪除這些內容（只須要在調用pasteHTML時用空字符串做爲參數。）

  toString方法取得一個Range對象的文本內容，做爲一個字符串。

  • 若是你須要以層次結構DOM的形式取得一個Range對象的內容，請使用cloneContents方法和extractContents方法。這兩個方法會從Range內容中創建一個DocumentFragment對象。
  • 要想從document中移除一個Range對象的內容，請使用deleteContents方法。
  • 要想向Range對象中插入一個新元素，請使用insertNode方法。

選擇一個TextRange對象的內容：

• 直接調用TextRange對象的select方法（多文本選區中這個方法不可用）。
  > 首先調用window.getSelection方法來接收一個從屬於當前選區的selectionRange對象。若是你想給當前選區 添加一個Range的內容，直接調用addRange方法就能夠把這個Range對象添加到selectionRange對象中。若是你只想要一個被選中的Range的內容，在調用addRange方法加入這個Range對象以前，先調用selectionRange對象的removeAllRanges方法。

TextRange對象的一些額外的功能：

• 能夠用execCommand方法編輯一個TextRange對象的內容，就像在富文本編輯器中那樣。你能夠修改背景色或者前景色，你可使字體變成粗體、斜體，你能夠用剪貼板剪切、複製以及粘貼內容，它提供了一些其它的功能。

• 用getBookmark方法，能夠把一個TextRange對象保存爲bookmark。以後能夠用moveToBookmark方法建立一個TextRange對象。該bookmark，以及這個用moveToBookmark方法建立的TextRange對象與被保存的那個TextRange對象是徹底相同的。

語法：

用下面的方法能夠訪問textRange對象：

• selection.createRange()
• object.createTextRange()
• TextRanges.item(index)

可能的成員：

屬性：

屬性名	說明
boundingHeight	返回一個整型值，指定了當前的TextRange對象的邊界矩形的高度，以像素爲單位。
boundingLeft	返回一個整型數，指定了當前的TextRange對象的邊界矩形的左邊緣座標，以像素爲單位。
boundingTop	返回一個整型數，指定了當前的TextRange對象的邊界矩形的上邊緣座標，以像素爲單位。
boundingWidth	返回一個整型數，指定了當前TextRange對象的邊界矩形的寬度，以像素爲單位。
htmlText	返回屬於一個TextRange對象的HTML源碼，做爲一個字符串。
offsetLeft	返回一個對象相對於它的定位父元素[1]的左邊緣的左座標位置，以像素爲單位。
offsetTop	返回一個對象相對於它的定位父元素[1]的頂邊緣的頂座標位置，以像素爲單位。
text	用一個字符串設置一個TextRange對象內部的文本，或者返回一個TextRange對象內部的文本，做爲一個字符串。

方法

方法名	說明
collapse	把一個range對象的開始點移動到它的結束點，或者相反。
compareEndPoints	比較兩個textRange對象的開始點和結束點的位置。
duplicate	返回當前TextRange對象的一個精確的複製副本。
execCommand	在某個對象上運行commands
expand	用一個字符、句子或者詞語，在插入點擴展TextRange對象的內容。
findText	在document中查找指定的文本，並關聯到一個TextRange對象。
getBookmark	把當前的TextRange對象保存到一個字符串中，以後能夠用moveToBookmark方法返回原始的TextRange對象。
getBoundingClientRect	返回一個TextRectangle對象，指定當前元素或者TextRange對象的邊界矩形，以像素爲單位，相對於瀏覽器窗口的左上角。
getClientRects	返回一個TextRectangles集合，指定當前元素或者TextRange對象的精確形狀。
inRange	返回當前TextRange對象是否包含了指定的TextRange對象。
isEqual	返回當前的TextRange對象是否與指定的TextRange對象徹底相同。
move	把當前的TextRange對象的結束點移到它的開始點，並把這個收縮的TextRange對象移動指定的字距。
moveEnd	把當前的TextRange對象的結束點移動指定字距。
moveStart	把當前的TextRange對象的開始點移動指定字距。
moveToBookmark	把當前的TextRange對象的開始點和結束點移到指定bookmark表明的位置。
moveToElementText	把當前的TextRange對象的開始點和結束點對齊到指定的元素的文本內容。
moveToPoint	把當前的TextRange對象的開始點和結束點移動到指定的位置。
parentElement	返回在DOM層次結構中包含了整個TextRange對象的最深的節點的引用。
pasteHTML	把當前TextRange對象的內容替換爲指定的HTML格式的文本。
queryCommandEnabled	用execCommand方法，返回這個指定的command是否能被執行成功。
queryCommandIndeterm	返回指定的command是否在一個不肯定的狀態中。
queryCommandState	返回指定的command當前的狀態
queryCommandSupported	返回當前的對象是否支持指定的command。
queryCommandText	返回指定的command的說明描述。
queryCommandValue	返回指定的command的實際的值。
scrollIntoView	把指定的元素滾致到文檔的可見區域。
select	選擇包含在當前TextRange或者controlRange對象中的全部的文本或控件。
setEndPoint	把當前TextRange對象的開始點和結束點對齊到指定的TextRange對象的開始點和結束點。

[1]定位父元素（offsetParent）：定位父元素並不是是DOM層次結構中的parentElement，而是離該元素最近的一個position屬性爲relative、absolute、static的上層級元素。若是上層級元素中沒有這樣的元素，則定位父元素就是document.body。

HTML代碼示例1：

這個示例演示了一個在document中取得選中內容的跨瀏覽器解決方案。

HTML<head>
    <script type="text/javascript">
        function TestSelection () {
            if (window.getSelection) {  // all browsers, except IE before version 9
                var selectionRange = window.getSelection ();                                        
                alert ("The text content of the selection:\n" + selectionRange.toString ());
            } 
            else {
                if (document.selection.type == 'None') {
                    alert ("No content is selected, or the selected content is not available!");
                }
                else {
                    var textRange = document.selection.createRange ();
                    alert ("The text content of the selection:\n" + textRange.text);
                }
            }
        }
    </script>
</head>
<body>
    Select some text or <button>element</button>, or do not select anything, before you click on the button below.
    <br /><br />
    <button onclick="TestSelection ();">Test the selection!</button>
</body>

HTML代碼示例2：

這個跨瀏覽器解示例演示瞭如何用range對象刪除一個元素中的內容：

HTML<head>
    <script type="text/javascript">
        function RemoveContent () {
            var srcObj = document.getElementById ("src");

            if (document.createRange) {     // all browsers, except IE before version 9
                var rangeObj = document.createRange ();
                rangeObj.selectNodeContents (srcObj);
                rangeObj.deleteContents ();
            }
            else {      // Internet Explorer before version 9
                var rangeObj = document.body.createTextRange ();
                rangeObj.moveToElementText (srcObj);
                rangeObj.select ();
                rangeObj.execCommand ('cut');
            }
        }
    </script>
</head>
<body>
    <div id="src" style="background-color:#e0a0b0; width:300px; height:50px;">The <b>contents</b> of the <i>source</i> element.</div>
    <br /><br />
    <button onclick="RemoveContent ();">Remove the contents of the source element!</button>
</body>