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>