富文本编辑器开发系列——Range对象

Range对象简介

Range, 直译为“范围”，俗称“拖蓝”，顾名思义，就是浏览器中使用鼠标拖拽选中的部分，通常会显示为蓝色背景，故称“拖蓝”。

但“拖蓝”表示的并不是选中的文字内容，而是选中文字部分的HTML源代码，它的开始节点和结束节点都是HTML元素对象。

还有一种特殊的拖蓝，即闭合的拖蓝，即它的开始节点和结束节点闭合到了一起（就是说它们是同一个HTML元素），最终表现为光标所在位置的一个点。

Range属于一个Selection（选区），通常，一个选区内只有且只能选中一个拖蓝，但在firefox 中，一个选区会包含多个选区，所以，通常获取拖蓝都是使用selection.getRangeAt(0)这样的方式，表示获取选区中的第一个拖蓝。

原生 API说明

Ragne对象原生 API ——IE9以上及其它内核浏览器

属性或方法 说明
collapsed 只读属性，拖蓝是否闭合
commonAncestorContainer 只读属性，返回包含开始节点与结束节点的最深一级的节点（根节点）
endContainer 只读属性，拖蓝的结束节点
endOffSet 只读属性，拖蓝终点相对于结束节点开始位置的偏移量
startContainer 只读属性， 拖蓝的开始节点
startOffset 只读属性，拖蓝起点相对于开始节点开始位置的偏移量
new Range() 构造一个以全局Document为起点与终点的拖蓝对象，即选中整篇文档
setStart(startNode, startOffset) 设置拖蓝的起点,startNode：开始节点，startOffset: 起点相对于开始节点开始位置的偏移量。
setEnd(endNode, endOffset) 设置拖蓝的终点，endNode:结束节点， endOffset: 终点相对于结束节点开始位置的偏移量。
setStartBefore(referenceNode) 相对于另一个节点来设置拖蓝的开始位置，该拖蓝的开始节点与另一个节点的父节点是同一个，开始节点在另一个节点之前
setStartAfter(referenceNode) 相对于另一个节点来设置拖蓝的开始位置，该拖蓝的开始节点与另一个节点的父节点是同一个，开始节点在另一个节点之后
setEndBefore(referenceNode) 相对于另一个节点来设置拖蓝的结束位置，该拖蓝的结束节点与另一个节点的父节点是同一个，结束节点在另一个节点之前
setEndAfter(referenceNode) 相对于另一个节点来设置拖蓝的结束位置，该拖蓝的结束节点与另一个节点的父节点是同一个，结束节点在另一个节点之后
seelctNode(referenceNode) 将拖蓝设置为包含整个节点及其内容， 拖蓝的起始和结束节点的父节点与传入节点（referenceNode）的父节点相同。
selectNodeContents(referenceNode) 设置拖蓝，使其包含传入节点的内容，拖蓝的起始和结束节点的父节点即为传入的节点。
collapse(toStart) 闭合拖蓝。toStart: 闭合方向，true向起点闭合，false向终点闭合。
cloneContents() 返回包含拖蓝中所有节点的文档片段
deleteContents() 从文档中移除拖蓝包含的内容
extractContents() 把拖蓝的内容从文档树移动到一个文档片段中，返回该文档片段
insertNode(newNode) 在拖蓝的起始位置插入一个新的节点，如果将新节点添加到一个文本节点，则该文本节点在插入点处被拆分，插入发生在两个文本节点之间；如果新节点是一个文档片段，则插入文档片段的子节点。
surroundContents(newParent) 将拖蓝的内容移动到一个新的节点，并将新节点放到这个范围的起始处。
compareBoundaryPoints(how, sourceRange) 比较两个拖蓝的端点。 how：指定如何比较，参见本表下方how部分。sourceRange : 要与之比较的拖蓝，返回一个数字，-1/0/1中的一个，表示本拖蓝的指定端点在源拖蓝的指定端点前面，相同位置还是后面。
cloneRange() 返回一个拖蓝，并且该拖蓝的范围边界点与被克隆的拖蓝对象相同。两个拖蓝的操作不会相互影响。
detach() 将拖蓝从使用状态中释放，用于改善性能
toString() 将拖蓝的内容作为字符串返回

how

指定如何比较，有四个可选值：

  • Range.END_TO_END: 比较源拖蓝的终点与本拖蓝的终点
  • Range.END_TO_START: 比较源拖蓝的终点与本拖蓝的起点
  • Range.START_TO_END: 比较源拖蓝的起点与本拖蓝的终点
  • Range.START_TO_START: 比较源拖蓝的起点与本拖蓝的起点

详见 [[富文本编辑器开发系列6——浏览器拖蓝RangeAPI探究]]

TextRange 原生 API——IE9以下浏览器

属性或方法 说明
boundingHeight 只读，返回绑定拖蓝对象的矩形的高度
boundingLeft 只读，返回绑定拖蓝对象矩形左边缘和完全包含拖蓝对象的左侧之间的距离
boundingTop 只读，返回绑定拖蓝对象的矩形上边缘和完全包含拖蓝对象的顶边之间的距离
boundingWidth 只读，返回绑定拖蓝对象的矩形的宽度
htmlText 只读，获取绑定拖蓝对象的HTML内容
text 只读，获取或设置拖蓝对象的纯文本内容
collapse(toStart) 闭合拖蓝，toStart：闭合方向，向起点闭合还是向终点闭合
duplicate() 复制一份拖蓝
execCommand() 在当前拖蓝上执行命令
expand() 扩展拖蓝，以便完全包含指定单位的范围
findText() 搜索原先拖蓝内的指定文本，并调整拖蓝使其包含第一次匹配的内容
inRange() 返回当前拖蓝是否包含指定拖蓝
isEqual() 返回当前拖蓝是否与指定拖蓝相等
move() 将拖蓝折叠，并将空白区域移动指定单位数。
moveEnd() 将拖蓝结束位置移动指定单位数
moveStart() 将拖蓝的开始位置移动指定单位数
moveToElementText() 使拖蓝包含指定元素的文本
parentElement() 返回拖蓝的父元素，也就是完全包含拖蓝的最小元素
pasteHTML() 将HTML内容粘贴入给定的拖蓝，并替换拖蓝内任何先前的文本和HTML元素
queryCommandEnabled() 返回表明指定命令是否可于给定文档当前状态下使用execCommand命令成功事项的布尔值。
queryCommandState() 返回表明指定命令当前状态的布尔值
queryCommandValue() 返回表明指定命令当前值的DOMString
scrollIntoView() 将拖蓝滚动到可视范围内（顶部或底部）
select() 将当前拖蓝选中
setEndPoint() 根据其它拖蓝的端点设置当前拖蓝的结束点

详见 [[富文本编辑器开发系列7——textRange对象详解]]