path: root/files/zh-cn/web/api/textrange/index.html

---
title: TextRange
slug: Web/API/TextRange
tags:
  - API
  - DHTML
  - DOM
  - TextRange
---
<div>{{ ApiRef("DOM") }}{{Non-standard_Header}}</div>

<div class="blockIndicator warning">
<p><strong>IE Only</strong></p>
该属性是IE专有的。尽管IE很好地支持它，但大部分其它浏览器已经不支持该属性。该属性仅应在需兼容低版本IE时作为其中一种方案，而不是在跨浏览器的脚本中完全依赖它。</div>

<p><code>TextRange</code> 对象表示文档中的文本片段，类似于标准定义的 {{domxref("Range")}} 接口。</p>

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

<p>注意，在非IE浏览器不支持该接口，可使用替代的 {{domxref("Selection")}} 及 {{domxref("Range")}} 接口。</p>

<h2 id="Properties" name="Properties">属性</h2>

<dl>
 <dt>{{domxref("TextRange.boundingHeight")}}{{ReadOnlyInline}}</dt>
 <dd>
 <p>返回绑定 <code>TextRange</code> 对象的矩形的高度。</p>
 </dd>
 <dt>{{domxref("TextRange.boundingLeft")}}{{ReadOnlyInline}}</dt>
 <dd>返回绑定 <code>TextRange</code> 对象的矩形左边缘和完全包含 <code>TextRange</code> 对象的左侧之间的距离。</dd>
 <dt>{{domxref("TextRange.boundingTop")}}{{ReadOnlyInline}}</dt>
 <dd>返回绑定 <code>TextRange</code> 对象的矩形上边缘和完全包含 <code>TextRange</code> 对象的顶边之间的距离。</dd>
 <dt>{{domxref("TextRange.boundingWidth")}}{{ReadOnlyInline}}</dt>
 <dd>返回绑定 <code>TextRange</code> 对象的矩形的宽度。</dd>
 <dt>{{domxref("TextRange.htmlText")}}</dt>
 <dd>获取或设置 <code>TextRange</code> 内的HTML内容。</dd>
 <dt>{{domxref("TextRange.text")}}</dt>
 <dd>获取或设置 <code>TextRange</code> 内的纯文本内容。</dd>
</dl>

<h2 id="Methods" name="Methods">方法</h2>

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

<h2 id="示例">示例</h2>

<p>以下示例在IE10以下有效。该示例通过 <code>document.selection</code> 获取 <code>TextRange</code>，并设置选中指定的元素。IE9以上支持标准的替代方案 {{domxref("Range")}}。</p>

<pre class="brush:js">var range = document.selection.createRange();
var element = document.getElementById("test");
range.moveToElementText(element);
range.select();
// 选中"一些将被选中的文本"</pre>

<pre class="brush:html"><code>&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
  &lt;title&gt;TextRange示例&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;p id="test"&gt;一些将被选中的文本&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;</code></pre>

<h2 id="开发者笔记">开发者笔记</h2>

<h3 id="使用_TextRange_操作选中区域">使用 TextRange 操作选中区域</h3>

<div class="blockIndicator warning">
<p>仅在<strong>IE10以下</strong>有效。在浏览器允许的情况下，应优先使用 {{domxref("Selection")}} 接口。</p>
</div>

<p>{{domxref("document.selection")}} 属性返回一个非标准的 {{domxref("MSSelection")}} 对象，<code>selection.createRange()</code> 方法创建一个和当前选中区域一致的 <code>TextRange</code> 对象。</p>

<pre class="brush:js">var sel = document.selection;
var range = sel.createRange();
alert(range.text);
// 输出被选区域的纯文本</pre>

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

<h3 id="selection_兼容性"><code>selection</code> 兼容性</h3>

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

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

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

<h2 id="浏览器兼容性">浏览器兼容性</h2>

<table class="standard-table">
 <thead>
  <tr>
   <th scope="row" style="width: 15px;"></th>
   <th scope="col">IE</th>
   <th scope="col">其它浏览器</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <th scope="row" style="width: 15%;">{{domxref("TextRange")}} {{non-standard_inline()}}</th>
   <td>支持(IE9后应使用标准API)</td>
   <td style="width: 60%;">不支持（详见<a href="/zh-CN/docs/Web/API/Selection_API">Selection API</a>）</td>
  </tr>
 </tbody>
</table>

<h2 id="See_also" name="See_also">扩展</h2>

<ul>
 <li>{{domxref("Selection")}} 及 {{domxref("Range")}} 标准接口</li>
 <li><a href="/zh-CN/docs/Web/API/Selection_API">Selection API</a> 用于取代该非标准接口</li>
</ul>