mozilla

Revision 440233 of Range

  • Revision slug: Web/API/range
  • Revision title: Range
  • Revision id: 440233
  • Created:
  • Creator: teoli
  • Is current revision? No
  • Comment
Tags: 

Revision Content

{{ DomRef() }}

The Range interface represents a fragment of a document that can contain nodes and parts of text nodes in a given document.

A range can be created using the {{ domxref("Document.createRange", "createRange") }} method of the {{ domxref("Document") }} object. Range objects can also be retrieved by using the {{ domxref("Selection/getRangeAt", "getRangeAt") }} method of the {{ domxref("Selection") }} object.

Properties

{{domxref("Range.collapsed")}}
Returns a boolean indicating whether the range's start and end points are at the same position.
{{domxref("Range.commonAncestorContainer")}}
Returns the deepest {{ domxref("Node") }} that contains the startContainer and endContainer Nodes.
{{domxref("Range.endContainer")}}
Returns the {{ domxref("Node") }} within which the Range ends.
{{domxref("Range.endOffset")}}
Returns a number representing where in the endContainer the Range ends.
{{domxref("Range.startContainer")}}
Returns the {{ domxref("Node") }} within which the Range starts.
{{domxref("Range.startOffset")}}
Returns a number representing where in the startContainer the Range starts.

Methods

{{ domxref("Range.setStart()")}}
Sets the start position of a Range.
{{ domxref("Range.setEnd()")}}
Sets the end position of a Range.
{{ domxref("Range.setStartBefore()")}}
Sets the start position of a Range relative to another {{ domxref("Node") }}.
{{ domxref("Range.setStartAfter()")}}
Sets the start position of a Range relative to another {{ domxref("Node") }}.
{{ domxref("Range.setEndBefore()")}}
Sets the end position of a Range relative to another {{ domxref("Node") }}.
{{ domxref("Range.setEndAfter()")}}
Sets the end position of a Range relative to another {{ domxref("Node") }}.
{{ domxref("Range.selectNode()")}}
Sets the Range to contain the {{ domxref("Node") }} and its contents.
{{ domxref("Range.selectNodeContents()")}}
Sets the Range to contain the contents of a {{ domxref("Node") }}.
{{ domxref("Range.collapse()")}}
Collapses the Range to one of its boundary points.
{{ domxref("Range.cloneContents()")}}
Returns a {{ domxref("DocumentFragment") }} copying the nodes of a Range.
{{ domxref("Range.deleteContents()")}}
Removes the contents of a Range from the {{ domxref("Document") }}.
{{ domxref("Range.extractContents()")}}
Moves contents of a Range from the document tree into a {{ domxref("DocumentFragment") }}.
{{ domxref("Range.insertNode()")}}
Insert a {{ domxref("Node") }} at the start of a Range.
{{ domxref("Range.surroundContents()")}}
Moves content of a Range into a new {{ domxref("Node") }}.
{{ domxref("Range.compareBoundaryPoints()")}}
Compares the boundary points of two Ranges.
{{ domxref("Range.cloneRange()")}}
Returns a Range object with boundary points identical to the cloned Range.
{{ domxref("Range.detach()")}}
Releases the Range from use to improve performance.
{{ domxref("Range.toString()")}}
Returns the text of the Range.
{{ domxref("Range.compareNode()")}} {{ Obsolete_inline }}{{non-standard_inline}}
Returns a constant representing whether the Node is before, after, inside, or surrounding the range.
{{ domxref("Range.comparePoint()")}}
Returns -1, 0, or 1 indicating whether the point occurs before, inside, or after the range.
{{ domxref("Range.createContextualFragment()")}}{{experimental_inline()}}
Returns a {{ domxref("DocumentFragment") }} created from a given string of code.
{{ domxref("Range.getBoundingClientRect()") }} {{experimental}}{{ gecko_minversion_inline("2.0") }}
Returns a {{ domxref("ClientRect") }} object which bounds the entire contents of the range; this would be the union of all the rectangles returned by {{ domxref("range.getClientRects()") }}.
{{ domxref("Range.getClientRects()") }} {{experimental}}{{ gecko_minversion_inline("2.0") }}
Returns a list of {{ domxref("ClientRect") }} objects that aggregates the results of {{ domxref("Element.getClientRects()") }} for all the elements in the range.
{{ domxref("Range.intersectsNode()")}} {{ Obsolete_inline() }}{{non-standard_inline}}
Returns a boolean indicating whether the given node intersects the range.
{{ domxref("Range.isPointInRange()")}}
Returns a boolean indicating whether the given point is in the range.

Exceptions

Starting with Gecko 13.0 {{ geckoRelease("13.0") }} the Range object throws {{ domxref("DOMException", "DOMExceptions") }} as defined in DOM 4, instead of a RangeException defined in prior specifications.

Revision Source

<p>{{ DomRef() }}</p>
<p>The <strong><code>Range</code></strong> interface represents a fragment of a document that can contain nodes and parts of text nodes in a given document.</p>
<p>A range can be created using the {{ domxref("Document.createRange", "createRange") }}&nbsp;method of the&nbsp;{{ domxref("Document") }}&nbsp;object. Range objects can also be retrieved by using the {{ domxref("Selection/getRangeAt", "getRangeAt") }}&nbsp;method of the&nbsp;{{ domxref("Selection") }}&nbsp;object.</p>
<h2 id="Properties" name="Properties">Properties</h2>
<dl>
  <dt>
    {{domxref("Range.collapsed")}}</dt>
  <dd>
    Returns a&nbsp;<code>boolean</code>&nbsp;indicating whether the range's start and end points are at the same position.</dd>
  <dt>
    {{domxref("Range.commonAncestorContainer")}}</dt>
  <dd>
    Returns the deepest&nbsp;{{ domxref("Node") }}&nbsp;that contains the startContainer and endContainer Nodes.</dd>
  <dt>
    {{domxref("Range.endContainer")}}</dt>
  <dd>
    Returns the&nbsp;{{ domxref("Node") }}&nbsp;within which the Range ends.</dd>
  <dt>
    {{domxref("Range.endOffset")}}</dt>
  <dd>
    Returns a number representing where in the endContainer the Range ends.</dd>
  <dt>
    {{domxref("Range.startContainer")}}</dt>
  <dd>
    Returns the&nbsp;{{ domxref("Node") }}&nbsp;within which the Range starts.</dd>
  <dt>
    {{domxref("Range.startOffset")}}</dt>
  <dd>
    Returns a number representing where in the startContainer the Range starts.</dd>
</dl>
<h2 id="Methods" name="Methods">Methods</h2>
<dl>
  <dt>
    {{ domxref("Range.setStart()")}}</dt>
  <dd>
    Sets the start position of a Range.</dd>
  <dt>
    {{ domxref("Range.setEnd()")}}</dt>
  <dd>
    Sets the end position of a Range.</dd>
  <dt>
    {{ domxref("Range.setStartBefore()")}}</dt>
  <dd>
    Sets the start position of a Range relative to another&nbsp;{{ domxref("Node") }}.</dd>
  <dt>
    {{ domxref("Range.setStartAfter()")}}</dt>
  <dd>
    Sets the start position of a Range relative to another&nbsp;{{ domxref("Node") }}.</dd>
  <dt>
    {{ domxref("Range.setEndBefore()")}}</dt>
  <dd>
    Sets the end position of a Range relative to another&nbsp;{{ domxref("Node") }}.</dd>
  <dt>
    {{ domxref("Range.setEndAfter()")}}</dt>
  <dd>
    Sets the end position of a Range relative to another&nbsp;{{ domxref("Node") }}.</dd>
  <dt>
    {{ domxref("Range.selectNode()")}}</dt>
  <dd>
    Sets the Range to contain the&nbsp;{{ domxref("Node") }}&nbsp;and its contents.</dd>
  <dt>
    {{ domxref("Range.selectNodeContents()")}}</dt>
  <dd>
    Sets the Range to contain the contents of a&nbsp;{{ domxref("Node") }}.</dd>
  <dt>
    {{ domxref("Range.collapse()")}}</dt>
  <dd>
    Collapses the Range to one of its boundary points.</dd>
  <dt>
    {{ domxref("Range.cloneContents()")}}</dt>
  <dd>
    Returns a&nbsp;{{ domxref("DocumentFragment") }}&nbsp;copying the nodes of a Range.</dd>
  <dt>
    {{ domxref("Range.deleteContents()")}}</dt>
  <dd>
    Removes the contents of a Range from the {{ domxref("Document") }}.</dd>
  <dt>
    {{ domxref("Range.extractContents()")}}</dt>
  <dd>
    Moves contents of a Range from the document tree into a&nbsp;{{ domxref("DocumentFragment") }}.</dd>
  <dt>
    {{ domxref("Range.insertNode()")}}</dt>
  <dd>
    Insert a&nbsp;{{ domxref("Node") }}&nbsp;at the start of a Range.</dd>
  <dt>
    {{ domxref("Range.surroundContents()")}}</dt>
  <dd>
    Moves content of a Range into a new&nbsp;{{ domxref("Node") }}.</dd>
  <dt>
    {{ domxref("Range.compareBoundaryPoints()")}}</dt>
  <dd>
    Compares the boundary points of two <code>Range</code>s.</dd>
  <dt>
    {{ domxref("Range.cloneRange()")}}</dt>
  <dd>
    Returns a <code>Range</code> object with boundary points identical to the cloned <code>Range</code>.</dd>
  <dt>
    {{ domxref("Range.detach()")}}</dt>
  <dd>
    Releases the <code>Range</code> from use to improve performance.</dd>
  <dt>
    {{ domxref("Range.toString()")}}</dt>
  <dd>
    Returns the text of the <code>Range</code>.</dd>
  <dt>
    {{ domxref("Range.compareNode()")}} {{ Obsolete_inline }}{{non-standard_inline}}</dt>
  <dd>
    Returns a constant representing whether the&nbsp;<a href="/en/DOM/Node" title="en/DOM/Node">Node</a>&nbsp;is before, after, inside, or surrounding the range.</dd>
  <dt>
    {{ domxref("Range.comparePoint()")}}</dt>
  <dd>
    Returns -1, 0, or 1 indicating whether the point occurs before, inside, or after the range.</dd>
  <dt>
    {{ domxref("Range.createContextualFragment()")}}{{experimental_inline()}}</dt>
  <dd>
    Returns a&nbsp;{{ domxref("DocumentFragment") }}&nbsp;created from a given string of code.</dd>
  <dt>
    {{ domxref("Range.getBoundingClientRect()") }} {{experimental}}{{ gecko_minversion_inline("2.0") }}</dt>
  <dd>
    Returns a {{ domxref("ClientRect") }} object which bounds the entire contents of the range; this would be the union of all the rectangles returned by {{ domxref("range.getClientRects()") }}.</dd>
  <dt>
    {{ domxref("Range.getClientRects()") }} {{experimental}}{{ gecko_minversion_inline("2.0") }}</dt>
  <dd>
    Returns a list of {{ domxref("ClientRect") }} objects that aggregates the results of {{ domxref("Element.getClientRects()") }} for all the elements in the range.</dd>
  <dt>
    {{ domxref("Range.intersectsNode()")}} {{ Obsolete_inline() }}{{non-standard_inline}}</dt>
  <dd>
    Returns a <code>boolean</code> indicating whether the given node intersects the range.</dd>
  <dt>
    {{ domxref("Range.isPointInRange()")}}</dt>
  <dd>
    Returns a <code>boolean</code> indicating whether the given point is in the range.</dd>
</dl>
<h3 id="Exceptions">Exceptions</h3>
<p>Starting with Gecko 13.0 {{ geckoRelease("13.0") }} the <code>Range</code> object throws {{ domxref("DOMException", "DOMExceptions") }} as defined in DOM 4, instead of a <code>RangeException</code> defined in prior specifications.</p>
Revert to this revision