XML DOM - Range 对象

Range 对象表示文档中的连续范围。

Range 对象

Range 对象表示文档的连续范围区域,如用户在浏览器窗口中用鼠标拖动选中的区域。

如果一个实现支持 Range 模块,那么 Document 对象就定义了 createRange() 方法,调用它可创建新的 Range 对象。

注意:IE 定义了不兼容的 Document.createRange() 方法,它返回的对象与 Rang 接口相似,但不兼容。

Range 接口为指定文档“选中”的区域定义了大量的方法,此外还有几个方法可以用于在选中的区域中进行剪切和粘贴类型的操作。

Range 接口的属性提供了获取范围的边界节点和偏移量的方法。它的方法提供了设置范围边界的方法。注意,范围的边界可以设置为 DocumentDocumentFragment 对象中的节点。一旦定义了范围的边界点,就可以使用 deleteContents()、extractContents()、cloneContents() 和 insertNode() 方法实现剪切、复制和粘贴的操作。

当通过插入或删除操作改变了文档时,表示文档一部分的所有 Range 对象都将改变(如果必要的话),以便使它们的边界点保持有效,并且让它们(尽可能接近地)表示同样的文档内容。

术语:范围、边界点和偏移量

一个范围具有两个边界点,即一个开始点和一个结束点。每个边界点由一个节点和那个节点的偏移量指定。该节点通常是 Element 节点Document 节点Text 节点。对于 Element 节点和 Document 节点,偏移量指该节点的子节点。偏移量为 0,说明边界点位于该节点的第一个子节点之前。偏移量为 1,说明边界点位于该节点的第一个子节点之后,第二个子节点之前。但如果边界节点是 Text 节点,偏移量则指的是文本中两个字符之间的位置。

Range 对象的常量

这些常量指定了如何比较 Range 对象的边界点。

它们是 compareBoundaryPoints() 方法的 how 参数的合法值:

常量 描述
START_TO_START 用指定范围的开始点与当前范围的开始点进行比较。
START_TO_END 用指定范围的开始点与当前范围的结束点进行比较。
END_TO_END 用指定范围的结束点与当前范围的结束点进行比较。
END_TO_START 用指定范围的结束点与当前范围的开始点进行比较。

Range 对象的属性

注意:所有属性都是只读的,不能通过设置这些属性改变范围的开始点和结束点,必须调用 setEnd() 方法和 setStart() 方法实现这一点。

注意:调用 detach() 方法后,对这些属性的任何读操作都会抛出代码为 INVALID_STATE_ERR 的 DOMException 异常

属性 描述
collapsed 如果范围的开始点和结束点在文档的同一位置,则为 true,即范围是空的,或折叠的。
commonAncestorContainer 范围的开始点和结束点的(即它们的祖先节点)、嵌套最深的 Document 节点。
endContainer 包含范围的结束点的 Document 节点。
endOffset endContainer 中的结束点位置。
startContainer 包含范围的开始点的 Document 节点。
endOffset startContainer 中的开始点位置。

Range 对象的方法

注意:如果调用了范围的 detach() 方法,那么接下来调用 Range 对象的任何方法都会抛出代码为 INVALID_STATE_ERR 的 DOMException 异常

方法 描述
cloneContents() 返回新的 DocumentFragment 对象,它包含该范围表示的文档区域的副本。
cloneRange() 创建一个新的 Range 对象,表示与当前的 Range 对象相同的文档区域。
collapse() 折叠该范围,使它的边界点重合。
compareBoundaryPoints() 比较指定范围的边界点和当前范围的边界点,根据它们的顺序返回 -1、0 和 1。比较哪个边界点由它的第一个参数指定,它的值必须是前面定义的常量之一。
deleteContents() 删除当前 Range 对象表示的文档区域。
detach() 通知实现不再使用当前的范围,可以停止跟踪。如果调用了范围的这个方法,那么接下来调用的该范围任何方法都会抛出代码为 INVALID_STATE_ERR 的 DOMException 异常
extractContents() 删除当前范围表示的文档区域,并且以 DocumentFragment 对象的形式返回那个区域的内容。该方法和 cloneContents() 方法与 deleteContents() 方法的组合很相似。
insertNode() 把指定的节点插入文档范围的开始点。
selectNode() 设置该范围的边界点,使它包含指定的节点和它的所有子孙节点。
selectNodeContents() 设置该范围的边界点,使它包含指定节点的子孙节点,但不包含指定的节点本身。
setEnd() 把该范围的结束点设置为指定的节点和偏移量。
setEndAfter() 把该范围的结束点设置为紧邻指定节点的节点之后。
setEndBefore() 把该范围的结束点设置为紧邻指定节点之前。
setStart() 把该范围的开始点设置为指定的节点中的指定偏移量。
setStartAfter() 把该范围的开始点设置为紧邻指定节点的节点之后。
setStartBefore() 把该范围的开始点设置为紧邻指定节点之前。
surroundContents() 把指定的节点插入文档范围的开始点,然后重定范围中的所有节点的父节点,使它们成为新插入的节点的子孙节点。
toString() 返回该范围表示的文档区域的纯文本内容。