TextRange

非标准

该特性是非标准的,请尽量不要在生产环境中使用它!

IE Only

该属性是IE专有的。尽管IE很好地支持它,但大部分其它浏览器已经不支持该属性。该属性仅应在需兼容低版本IE时作为其中一种方案,而不是在跨浏览器的脚本中完全依赖它。

TextRange 对象表示文档中的文本片段,类似于标准定义的 Range 接口。

此对象用于表示文档中特定的一段文本,例如在按住鼠标选中页面上的内容时,创建出的就是一个较为典型的 TextRange。它在IE中被实现,可通过 Element.createTextRange() 方法或是 MSSelection.createRange() 方法创建一个 TextRange 对象。

注意,在非IE浏览器不支持该接口,可使用替代的 Selection 及 Range 接口。

属性

TextRange.boundingHeight只读

返回绑定 TextRange 对象的矩形的高度。

TextRange.boundingLeft只读
返回绑定 TextRange 对象的矩形左边缘和完全包含 TextRange 对象的左侧之间的距离。
TextRange.boundingTop只读
返回绑定 TextRange 对象的矩形上边缘和完全包含 TextRange 对象的顶边之间的距离。
TextRange.boundingWidth只读
返回绑定 TextRange 对象的矩形的宽度。
TextRange.htmlText
获取或设置 TextRange 内的HTML内容。
TextRange.text
获取或设置 TextRange 内的纯文本内容。

方法

TextRange.collapse()
将插入光标(Caret)移动到当前范围的开始或结尾。
TextRange.duplicate()
返回 TextRange 的副本。
TextRange.execCommand()
在当前文档、当前选中区或给定范围上执行命令
TextRange.expand()
扩展区域,以便完全包含指定单位的范围。例如,扩展一个 "word" 表示把区域两端的单词完全包含在区域内,如 xpand to wor 可能变成 expand to words
TextRange.findText()
搜索原先区域内的指定文本,并调整区域使其包含第一次匹配的内容。
TextRange.inRange()
返回当前区域是否包含指定区域。
TextRange.isEqual()
返回当前区域是否与指定区域相等。
TextRange.move()
将区域折叠(collapse),并将空白区域移动指定单位数。如 move("character",-1) 表示向左移动一个字符。
TextRange.moveEnd()
将区域的结束位置移动指定单位数。
TextRange.moveStart()
将区域的开始位置移动指定单位数。
TextRange.moveToElementText()
使区域包含指定元素的文本。只能用于 Element 对象。
TextRange.parentElement()
返回区域的父元素,也就是完全包含区域的最小元素。如果选区包含多个元素,则当修改选区的内容时,内容将放置在该父元素的对应位置中,而不是放在子元素中。
TextRange.pasteHTML()
将HTML内容粘贴入给定范围,并替换范围内任何先前的文本和 HTML 元素。
TextRange.queryCommandEnabled()
返回表明指定命令是否可于给定文档当前状态下使用 execCommand 命令成功执行的 Boolean 值。参见 Document.queryCommandEnabled()
TextRange.queryCommandState()
返回表明指定命令当前状态的 Boolean 值。参见 Document.queryCommandState()
TextRange.queryCommandValue()
返回表明指定命令当前值的 DOMString。参见 Document.queryCommandValue()
TextRange.scrollIntoView()
将区域滚动到可视范围内(顶部或底部)。可作为 Element.scrollIntoView 在低版本IE下的一种替代方法。
TextRange.select()
将当前区域选中(即用户看到的蓝色选区)。
TextRange.setEndPoint()
根据其它 TextRange 的端点设置当前区域的结束点。

示例

以下示例在IE10以下有效。该示例通过 document.selection 获取 TextRange,并设置选中指定的元素。IE9以上支持标准的替代方案 Range

var range = document.selection.createRange();
var element = document.getElementById("test");
range.moveToElementText(element);
range.select();
// 选中"一些将被选中的文本"
<!DOCTYPE html>
<html>
<head>
  <title>TextRange示例</title>
</head>
<body>
  <p id="test">一些将被选中的文本</p>
</body>
</html>

开发者笔记

使用 TextRange 操作选中区域

仅在IE10以下有效。在浏览器允许的情况下,应优先使用 Selection 接口。

document.selection 属性返回一个非标准的 MSSelection 对象,selection.createRange() 方法创建一个和当前选中区域一致的 TextRange 对象。

var sel = document.selection;
var range = sel.createRange();
alert(range.text);
// 输出被选区域的纯文本

注意,createRange 方法并不创建引用,如果在对选区修改后希望修改后区域被选中,则需要调用 TextRange.select 方法。

selection 兼容性

document.selection 对象是 TextRange 的主要用途。该对象用于处理文档中被选中的区域,并且主要依靠使用 TextRange 接口实现。标准规定一个窗口/文档可能有多个不相邻选区,但只有Firefox实现通过 Ctrl 选中多个区域;IE中一般也只允许文档只存在一个被选中的 TextRange

然而,在其它浏览器中,document 并不存在一个所谓 selection 属性——它们通过标准 Selection API (en-US) 实现对选区的操作,也就是通过 window.getSelection() 方法获取 Selection 对象,并使用标准的 Range 对象对文本片段作出处理。IE11及之后的版本也放弃了 document.selection 对象而转为使用标准接口(尽管 TextRange 一直保留,但大多数情况下它已失去作用)。

这很容易引起迷惑。通常,如果脚本只要求兼容最新的浏览器,那么标准的接口是最佳的选择;但通常目前的网站仍希望兼容IE8或其以下的浏览器,因此,最好的做法是同时处理两者,也就是在不支持标准接口时尝试使用 TextRange 方式,但不要把该方式作为唯一的选择。

浏览器兼容性

IE 其它浏览器
TextRange 支持(IE9后应使用标准API) 不支持(详见Selection API (en-US)

扩展