TextRange - Web APIs 编辑

Non-standard

This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

IE Only

This property is IE specific. Although it is well supported by IE, most other browsers no longer support this property. This property should only be used as one of the solutions when you need to be compatible with lower versions of IE, rather than relying on it completely in cross browser scripts.

A TextRange object represents a fragment of text in a document, similar to the standard defined Range interface.

This object is used to represent a specific piece of text in the document. For example, when you hold down the mouse to select the content on the page, you create a typical TextRange. It is implemented in IE, then a TextRange object can be created by Element.createTextRange() or Document.selection.createRange().

Note that this interface is not supported in non IE browsers. Alternative Selection and Range interfaces can be used.

Properties

TextRange.boundingHeightRead only

Returns the height of the rectangle bound to the TextRange object.

TextRange.boundingLeftRead only

Returns the distance between the left edge of the rectangle that binds the TextRange object and the left edge that completely contains the TextRange object.

TextRange.boundingTopRead only

Returns the distance between the top edge of the rectangle that binds the TextRange object and the top edge that completely contains the TextRange object.

TextRange.boundingWidthRead only

Returns the width of the rectangle bound to the TextRange object.

TextRange.htmlText

Gets or sets the HTML content within the TextRange.

TextRange.text

Gets or sets the plaintext content within the TextRange.

Methods

TextRange.collapse()

Move the caret to the beginning or end of the current range.

TextRange.duplicate()

Returns a copy of TextRange.

TextRange.execCommand()

Executes a command on the current document, the current selection, or the given scope.

TextRange.expand()

Expand the range to include the full range of specified units. For example, expanding a "word" means that the words at both ends of the range will completely included in the range. xpand to wor may become expand to words, etc.

TextRange.findText()

Searches the specified text in the original range and adjusts the range to include the first match.

TextRange.inRange()

Returns whether the current range contains the specified range.

TextRange.isEqual()

Returns whether the current range is equal to the specified range.

TextRange.move()

Collapses the range and moves the blank range by a specified number of units. Such as, move("character",-1) means to move one character to the left.

TextRange.moveEnd()

Moves the end of the range by a specified number of units.

TextRange.moveStart()

Moves the start of the range by a specified number of units.

TextRange.moveToElementText()

Causes the range to contain the text of the specified element. Can only be used on Element objects.

TextRange.parentElement()

Returns the parent element of the range, which is the smallest element that contains the range completely. If the selection contains more than one element, when you modify the contents of the selection, the contents will be placed in the corresponding position of the parent element instead of the child element.

TextRange.pasteHTML()

Paste the HTML content into the given range and replace any previous text and HTML elements in the range.

TextRange.queryCommandEnabled()

Returns a Boolean indicating whether the specified command can be executed successfully with the execCommand method in the current state of the given document. You can also see Document.queryCommandEnabled().

TextRange.queryCommandState()

Returns the Boolean indicating the current state of the specified command. You can also see Document.queryCommandState().

TextRange.queryCommandValue()

Returns the DOMString indicating the current value of the specified command. You can also see Document.queryCommandValue().

TextRange.scrollIntoView()

Scroll the range to the visible range (top or bottom). It can be used as an alternative to Element.scrollIntoView in the lower version of IE.

TextRange.select()

Select the current range (i.e. the blue selection seen by the user).

TextRange.setEndPoint()

Sets the end point of the current range based on the bounds of other TextRange.

Example

The following example is valid under IE9. The example gets the TextRange through document.selection, and sets the specified element to be selected. IE9 supports the standard alternative Range.

var range = document.selection.createRange();
var element = document.getElementById("test");
range.moveToElementText(element);
range.select();
// Selected "SomeTextToBeSelected"

<!DOCTYPE html>
<html>
<head>
  <title>TextRange Example</title>
</head>
<body>
  <p id="test">SomeTextToBeSelected</p>
</body>
</html>

Notes

Use TextRange to Operate the Selection

Valid only under IE9. The selection interface should be used first, if the browser allows it.

document.selection property returns a non-standard selection object, and the selection.createRange() method creates a TextRange object consistent with the currently selection.

var sel = document.selection;
var range = sel.createRange();
alert(range.text);
// Output plaintext of the selection

Note that the createRange method does not create a reference. If you want to select the modified range after modifying the selection, you need to call the TextRange.select method.

selection Compatibility

The document.selection object is the primary purpose of TextRange. This object is used to process the selected ranges in the document, and is mainly implemented by using the TextRange interface. According to the standard, a window / document may have multiple non adjacent selection, but only Firefox can select multiple ranges through Ctrl; generally, only one selected TextRange is allowed in ie. 

However, in other browsers, document does not have a so-called selection attribute - they operate on the selection through the standard Selection API, that is, they get the Selection object through the window.getselection() method, and use the standard Range object to process the text fragment. IE9 and later also gave up the document.selection object and switched to the standard interface (although TextRange has been reserved, it has lost its function in most cases).

It's easy to get confused. Generally, if the script only needs to be compatible with the latest browser, the standard interface is the best choice; however, the current website still wants to be compatible with IE8 or below browsers. Therefore, the best way is to deal with both at the same time, that is, try to use TextRange mode when the standard interface is not supported, but do not regard it as the only choice.

Browser compatibility

	IE	Other Browsers
TextRange	≤8(Standard API after IE9)	No Support (See Selection API)

See also

• Selection and Range standard interface
• Selection API to replace this non-standard interface