Home/CKEditor 5/API

Range (engine/model)

@ckeditor/ckeditor5-engine/src/model/range

See source

Represents a range in the model tree.

A range is defined by its start and end positions.

You can create range instances via its constructor or the createRange*() factory methods of Model and Writer.

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

end : Position

readonly

End position.

See source
isCollapsed : Boolean

Returns whether the range is collapsed, that is if start and end positions are equal.

See source
isFlat : Boolean

Returns whether this range is flat, that is if start position and end position are in the same parent.

See source
root : Element | DocumentFragment

Range root element.

See source
start : Position

readonly

Start position.

See source

Methods

constructor( start, [ end ] )

Creates a range spanning from start position to end position.

See source

Parameters

start : Position

The start position.

[ end ] : Position

The end position. If not set, the range will be collapsed at the start position.
Symbol.iterator() → Iterable.<TreeWalkerValue>

Iterable interface.

See source

Iterates over all items that are in this range and returns them together with additional information like length or positions, grouped as TreeWalkerValue. It iterates over all text contents that are inside the range and all the Elements that are entered into when iterating over this range.

This iterator uses TreeWalker with boundaries set to this range and ignoreElementEnd option set to true.

Returns

Iterable.<TreeWalkerValue>
clone() → Range

Returns a new range that is equal to current range.

See source

Returns

Range
containsItem( item )

Checks whether given Item is inside this range.

See source

Parameters

item : Item

Model item to check.
containsPosition( position ) → Boolean

Checks whether this range contains given position.

See source

Parameters

position : Position

Position to check.

Returns

Boolean

true if given position is contained in this range,false otherwise.
containsRange( otherRange, [ loose ] ) → Boolean

Checks whether this range contains given range.

See source

Parameters

otherRange : Range

Range to check.

[ loose ] : Boolean

Whether the check is loose or strict. If the check is strict (false), compared range cannot start or end at the same position as this range boundaries. If the check is loose (true), compared range can start, end or even be equal to this range. Note that collapsed ranges are always compared in strict mode.

Defaults to false

Returns

Boolean

true if given range boundaries are contained by this range, false otherwise.
getCommonAncestor() → Element | DocumentFragment | null

Returns an Element or DocumentFragment which is a common ancestor of the range's both ends (in which the entire range is contained).

See source

Returns

Element | DocumentFragment | null
getContainedElement() → Element | null

Returns an Element contained by the range. The element will be returned when it is the only node within the range and fully–contained at the same time.

See source

Returns

Element | null

`getDifference( otherRange ) → Array.<Range>`

Computes which part(s) of this range is not a part of given range. Returned array contains zero, one or two ranges.

See source

Examples:

let range = model.createRange(
	model.createPositionFromPath( root, [ 2, 7 ] ),
	model.createPositionFromPath( root, [ 4, 0, 1 ] )
);
let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 5 ] ) );
let transformed = range.getDifference( otherRange );
// transformed array has no ranges because `otherRange` contains `range`

otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 3 ] ) );
transformed = range.getDifference( otherRange );
// transformed array has one range: from [ 3 ] to [ 4, 0, 1 ]

otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 4 ] ) );
transformed = range.getDifference( otherRange );
// transformed array has two ranges: from [ 2, 7 ] to [ 3 ] and from [ 4 ] to [ 4, 0, 1 ]

Parameters

otherRange : Range: Range to differentiate against.

Returns

Array.<Range>: The difference between ranges.

`getIntersection( otherRange ) → Range | null`

Returns an intersection of this range and given range. Intersection is a common part of both of those ranges. If ranges has no common part, returns null.

See source

Examples:

let range = model.createRange(
	model.createPositionFromPath( root, [ 2, 7 ] ),
	model.createPositionFromPath( root, [ 4, 0, 1 ] )
);
let otherRange = model.createRange( model.createPositionFromPath( root, [ 1 ] ), model.createPositionFromPath( root, [ 2 ] ) );
let transformed = range.getIntersection( otherRange ); // null - ranges have no common part

otherRange = model.createRange( model.createPositionFromPath( root, [ 3 ] ), model.createPositionFromPath( root, [ 5 ] ) );
transformed = range.getIntersection( otherRange ); // range from [ 3 ] to [ 4, 0, 1 ]

Parameters

otherRange : Range: Range to check for intersection.

Returns

Range | null: A common part of given ranges or null if ranges have no common part.

getItems( [ options ] ) → Iterable.<Item>

Returns an iterator that iterates over all items that are in this range and returns them.

See source

This method uses TreeWalker with boundaries set to this range and ignoreElementEnd option set to true. However it returns only model items, not TreeWalkerValue.

You may specify additional options for the tree walker. See TreeWalker for a full list of available options.

Parameters

[ options ] : Object

Object with configuration options. See TreeWalker.

Returns

Iterable.<Item>
getJoined( otherRange, [ loose ] ) → Range | null
Returns a range created by joining this range with the given range. If ranges have no common part, returns null.

See source
Examples:
```
let range = model.createRange(
	model.createPositionFromPath( root, [ 2, 7 ] ),
	model.createPositionFromPath( root, [ 4, 0, 1 ] )
);
let otherRange = model.createRange(
	model.createPositionFromPath( root, [ 1 ] ),
	model.createPositionFromPath( root, [ 2 ] )
);
let transformed = range.getJoined( otherRange ); // null - ranges have no common part

otherRange = model.createRange(
	model.createPositionFromPath( root, [ 3 ] ),
	model.createPositionFromPath( root, [ 5 ] )
);
transformed = range.getJoined( otherRange ); // range from [ 2, 7 ] to [ 5 ]
```
Parameters

otherRange : Range

Range to be joined.

[ loose ] : Boolean

Whether the intersection check is loose or strict. If the check is strict (false), ranges are tested for intersection or whether start/end positions are equal. If the check is loose (true), compared range is also checked if it's touching current range.

Defaults to false

Returns

Range | null

A sum of given ranges or null if ranges have no common part.

`getMinimalFlatRanges() → Array.<Range>`

Computes and returns the smallest set of flat ranges, that covers this range in whole.

See source

See an example of a model structure ([ and ] are range boundaries):

root                                                            root
 |- element DIV                         DIV             P2              P3             DIV
 |   |- element H                   H        P1        f o o           b a r       H         P4
 |   |   |- "fir[st"             fir[st     lorem                               se]cond     ipsum
 |   |- element P1
 |   |   |- "lorem"                                              ||
 |- element P2                                                   ||
 |   |- "foo"                                                    VV
 |- element P3
 |   |- "bar"                                                   root
 |- element DIV                         DIV             [P2             P3]             DIV
 |   |- element H                   H       [P1]       f o o           b a r        H         P4
 |   |   |- "se]cond"            fir[st]    lorem                               [se]cond     ipsum
 |   |- element P4
 |   |   |- "ipsum"

As it can be seen, letters contained in the range are: stloremfoobarse, spread across different parents. We are looking for minimal set of flat ranges that contains the same nodes.

Minimal flat ranges for above range ( [ 0, 0, 3 ], [ 3, 0, 2 ] ) will be:

( [ 0, 0, 3 ], [ 0, 0, 5 ] ) = "st"
( [ 0, 1 ], [ 0, 2 ] ) = element P1 ("lorem")
( [ 1 ], [ 3 ] ) = element P2, element P3 ("foobar")
( [ 3, 0, 0 ], [ 3, 0, 2 ] ) = "se"

Note: if an element is not wholly contained in this range, it won't be returned in any of the returned flat ranges. See in the example how H elements at the beginning and at the end of the range were omitted. Only their parts that were wholly in the range were returned.

Note: this method is not returning flat ranges that contain no nodes.

Returns

Array.<Range>: Array of flat ranges covering this range.

getPositions( options ) → Iterable.<Position>

Returns an iterator that iterates over all positions that are boundaries or contained in this range.

See source

This method uses TreeWalker with boundaries set to this range. However it returns only positions, not TreeWalkerValue.

You may specify additional options for the tree walker. See TreeWalker for a full list of available options.

Parameters

options : Object

Object with configuration options. See TreeWalker.

Returns

Iterable.<Position>
getTransformedByOperation( operation ) → Array.<Range>

Returns a range that is a result of transforming this range by given operation.

See source

Note: transformation may break one range into multiple ranges (for example, when a part of the range is moved to a different part of document tree). For this reason, an array is returned by this method and it may contain one or more Range instances.

Parameters

operation : Operation

Operation to transform range by.

Returns

Array.<Range>

Range which is the result of transformation.
getTransformedByOperations( operations ) → Array.<Range>
Returns a range that is a result of transforming this range by multiple operations.

See source
Parameters

operations : Iterable.<Operation>

Operations to transform the range by.

Returns

Array.<Range>

Range which is the result of transformation.

Related:
- Range#getTransformedByOperation
getWalker( options = { [options.startPosition], [options.singleCharacters], [options.shallow], [options.ignoreElementEnd] } ) → TreeWalker
Creates a TreeWalker instance with this range as a boundary.

See source
For example, to iterate over all items in the entire document root:
```
// Create a range spanning over the entire root content:
const range = editor.model.createRangeIn( editor.model.document.getRoot() );

// Iterate over all items in this range:
for ( const value of range.getWalker() ) {
	console.log( value.item );
}
```
Parameters

options : Object

Object with configuration options. See TreeWalker.

Properties

[ options.startPosition ] : Position

[ options.singleCharacters ] : Boolean

Defaults to false

[ options.shallow ] : Boolean

Defaults to false

[ options.ignoreElementEnd ] : Boolean

Defaults to false

Returns

TreeWalker
is( type ) → Boolean
Checks whether this object is of the given.

See source
```
range.is( 'range' ); // -> true
range.is( 'model:range' ); // -> true

range.is( 'view:range' ); // -> false
range.is( 'documentSelection' ); // -> false
```
Check the entire list of model objects which implement the is() method.

Parameters

type : String

Returns

Boolean
isEqual( otherRange ) → Boolean

Two ranges are equal if their start and end positions are equal.

See source

Parameters

otherRange : Range

Range to compare with.

Returns

Boolean

true if ranges are equal, false otherwise.
isIntersecting( otherRange ) → Boolean

Checks and returns whether this range intersects with given range.

See source

Parameters

otherRange : Range

Range to compare with.

Returns

Boolean

true if ranges intersect, false otherwise.
toJSON() → Object

Converts Range to plain object and returns it.

See source

Returns

Object

Node converted to plain object.
_getTransformedByDeletion( deletionPosition, howMany ) → Range | null

protected

Returns a copy of this range that is transformed by deletion of howMany nodes from deletePosition.

See source

If the deleted range is intersecting with the transformed range, the transformed range will be shrank.

If the deleted range contains transformed range, null will be returned.

Parameters

deletionPosition : Position

Position from which nodes are removed.

howMany : Number

How many nodes are removed.

Returns

Range | null

Result of the transformation.
_getTransformedByInsertOperation( operation ) → Array.<Range>

protected

Returns a result of transforming a copy of this range by insert operation.

See source

One or more ranges may be returned as a result of this transformation.

Parameters

operation : InsertOperation

Returns

Array.<Range>

`_getTransformedByInsertion( insertPosition, howMany, [ spread ] ) → Array.<Range>`

protected

Returns an array containing one or two ranges that are a result of transforming this range by inserting howMany nodes at insertPosition. Two ranges are returned if the insertion was inside this range and spread is set to true.

See source

Examples:

let range = model.createRange(
	model.createPositionFromPath( root, [ 2, 7 ] ),
	model.createPositionFromPath( root, [ 4, 0, 1 ] )
);
let transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 1 ] ), 2 );
// transformed array has one range from [ 4, 7 ] to [ 6, 0, 1 ]

transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 4, 0, 0 ] ), 4 );
// transformed array has one range from [ 2, 7 ] to [ 4, 0, 5 ]

transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 3, 2 ] ), 4 );
// transformed array has one range, which is equal to original range

transformed = range._getTransformedByInsertion( model.createPositionFromPath( root, [ 3, 2 ] ), 4, true );
// transformed array has two ranges: from [ 2, 7 ] to [ 3, 2 ] and from [ 3, 6 ] to [ 4, 0, 1 ]

Parameters

insertPosition : Position

Position where nodes are inserted.

howMany : Number

How many nodes are inserted.

[ spread ] : Boolean

Flag indicating whether this {~Range range} should be spread if insertion was inside the range. Defaults to false.

Defaults to false

Returns

Array.<Range>: Result of the transformation.

_getTransformedByMergeOperation( operation ) → Range

protected

Returns a result of transforming a copy of this range by merge operation.

See source

Always one range is returned. The transformation is done in a way to not break the range.

Parameters

operation : MergeOperation

Returns

Range
_getTransformedByMove( sourcePosition, targetPosition, howMany, [ spread ] ) → Array.<Range>

protected

Returns an array containing ranges that are a result of transforming this range by moving howMany nodes from sourcePosition to targetPosition.

See source

Parameters

sourcePosition : Position

Position from which nodes are moved.

targetPosition : Position

Position to where nodes are moved.

howMany : Number

How many nodes are moved.

[ spread ] : Boolean

Whether the range should be spread if the move points inside the range.

Defaults to false

Returns

Array.<Range>

Result of the transformation.
_getTransformedByMoveOperation( operation ) → Array.<Range>

protected

Returns a result of transforming a copy of this range by move operation.

See source

One or more ranges may be returned as a result of this transformation.

Parameters

operation : MoveOperation

Returns

Array.<Range>
_getTransformedBySplitOperation( operation ) → Range

protected

Returns a result of transforming a copy of this range by split operation.

See source

Always one range is returned. The transformation is done in a way to not break the range.

Parameters

operation : SplitOperation

Returns

Range

Static methods

`_createFromRanges( ranges ) → Range`

static

Combines all ranges from the passed array into a one range. At least one range has to be passed. Passed ranges must not have common parts.

See source

The first range from the array is a reference range. If other ranges start or end on the exactly same position where the reference range, they get combined into one range.

	[  ][]  [    ][ ][             ][ ][]  [  ]  // Passed ranges, shown sorted
	[    ]                                       // The result of the function if the first range was a reference range.
            [                           ]        // The result of the function if the third-to-seventh range was a reference range.
                                           [  ]  // The result of the function if the last range was a reference range.

Parameters

ranges : Array.<Range>: Ranges to combine.

Returns

Range: Combined range.

fromJSON( json, doc ) → Range

static

Creates a Range instance from given plain object (i.e. parsed JSON string).

See source

Parameters

json : Object

Plain object to be converted to Range.

doc : Document

Document object that will be range owner.

Returns

Range

Range instance created using given plain object.
_createFromPositionAndShift( position, shift ) → Range

protected static

Creates a new range, spreading from specified position to a position moved by given shift. If shift is a negative value, shifted position is treated as the beginning of the range.

See source

Parameters

position : Position

Beginning of the range.

shift : Number

How long the range should be.

Returns

Range
_createIn( element ) → Range

protected static

Creates a range inside an element which starts before the first child of that element and ends after the last child of that element.

See source

Parameters

element : Element

Element which is a parent for the range.

Returns

Range
_createOn( item ) → Range

protected static

Creates a range that starts before given model item and ends after it.

See source

Parameters

item : Item

Returns

Range

Every day, we work hard to keep our documentation complete. Have you spotted an outdated information? Is something missing? Please report it via our issue tracker.

Range (engine/model)

Filtering

Properties

end : Positionmodule:engine/model/range~Range#end

isCollapsed : Booleanmodule:engine/model/range~Range#isCollapsed

isFlat : Booleanmodule:engine/model/range~Range#isFlat

root : Element | DocumentFragmentmodule:engine/model/range~Range#root

start : Positionmodule:engine/model/range~Range#start

Methods

constructor( start, [ end ] )module:engine/model/range~Range#constructor

Parameters

Symbol.iterator() → Iterable.<TreeWalkerValue>module:engine/model/range~Range#Symbol.iterator

Returns

clone() → Rangemodule:engine/model/range~Range#clone

Returns

containsItem( item )module:engine/model/range~Range#containsItem

Parameters

containsPosition( position ) → Booleanmodule:engine/model/range~Range#containsPosition

Parameters

Returns

containsRange( otherRange, [ loose ] ) → Booleanmodule:engine/model/range~Range#containsRange

Parameters

Returns

getCommonAncestor() → Element | DocumentFragment | nullmodule:engine/model/range~Range#getCommonAncestor

Returns

getContainedElement() → Element | nullmodule:engine/model/range~Range#getContainedElement

Returns

getDifference( otherRange ) → Array.<Range>module:engine/model/range~Range#getDifference

Parameters

Returns

getIntersection( otherRange ) → Range | nullmodule:engine/model/range~Range#getIntersection

Parameters

Returns

getItems( [ options ] ) → Iterable.<Item>module:engine/model/range~Range#getItems

Parameters

Returns

getJoined( otherRange, [ loose ] ) → Range | nullmodule:engine/model/range~Range#getJoined

Parameters

Returns

getMinimalFlatRanges() → Array.<Range>module:engine/model/range~Range#getMinimalFlatRanges

Returns

getPositions( options ) → Iterable.<Position>module:engine/model/range~Range#getPositions

Parameters

Returns

getTransformedByOperation( operation ) → Array.<Range>module:engine/model/range~Range#getTransformedByOperation

Parameters

Returns

getTransformedByOperations( operations ) → Array.<Range>module:engine/model/range~Range#getTransformedByOperations

Parameters

Returns

Related:

getWalker( options = { [options.startPosition], [options.singleCharacters], [options.shallow], [options.ignoreElementEnd] } ) → TreeWalkermodule:engine/model/range~Range#getWalker

Parameters

Returns

is( type ) → Booleanmodule:engine/model/range~Range#is

Parameters

Returns

isEqual( otherRange ) → Booleanmodule:engine/model/range~Range#isEqual

Parameters

Returns

isIntersecting( otherRange ) → Booleanmodule:engine/model/range~Range#isIntersecting

Parameters

Returns

toJSON() → Objectmodule:engine/model/range~Range#toJSON

Returns

_getTransformedByDeletion( deletionPosition, howMany ) → Range | nullmodule:engine/model/range~Range#_getTransformedByDeletion

Parameters

Returns

_getTransformedByInsertOperation( operation ) → Array.<Range>module:engine/model/range~Range#_getTransformedByInsertOperation

Parameters

Returns

_getTransformedByInsertion( insertPosition, howMany, [ spread ] ) → Array.<Range>module:engine/model/range~Range#_getTransformedByInsertion

Parameters

Returns

_getTransformedByMergeOperation( operation ) → Rangemodule:engine/model/range~Range#_getTransformedByMergeOperation

Parameters

Returns

_getTransformedByMove( sourcePosition, targetPosition, howMany, [ spread ] ) → Array.<Range>module:engine/model/range~Range#_getTransformedByMove

Parameters

Returns

`end : Position`

`isCollapsed : Boolean`

`isFlat : Boolean`

`root : Element | DocumentFragment`

`start : Position`

`constructor( start, [ end ] )`

`Symbol.iterator() → Iterable.<TreeWalkerValue>`

`clone() → Range`

`containsItem( item )`

`containsPosition( position ) → Boolean`

`containsRange( otherRange, [ loose ] ) → Boolean`

`getCommonAncestor() → Element | DocumentFragment | null`

`getContainedElement() → Element | null`

`getDifference( otherRange ) → Array.<Range>`

`getIntersection( otherRange ) → Range | null`

`getItems( [ options ] ) → Iterable.<Item>`

`getJoined( otherRange, [ loose ] ) → Range | null`

`getMinimalFlatRanges() → Array.<Range>`

`getPositions( options ) → Iterable.<Position>`

`getTransformedByOperation( operation ) → Array.<Range>`

`getTransformedByOperations( operations ) → Array.<Range>`

`getWalker( options = { [options.startPosition], [options.singleCharacters], [options.shallow], [options.ignoreElementEnd] } ) → TreeWalker`

`is( type ) → Boolean`

`isEqual( otherRange ) → Boolean`

`isIntersecting( otherRange ) → Boolean`

`toJSON() → Object`

`_getTransformedByDeletion( deletionPosition, howMany ) → Range | null`

`_getTransformedByInsertOperation( operation ) → Array.<Range>`

`_getTransformedByInsertion( insertPosition, howMany, [ spread ] ) → Array.<Range>`

`_getTransformedByMergeOperation( operation ) → Range`

`_getTransformedByMove( sourcePosition, targetPosition, howMany, [ spread ] ) → Array.<Range>`

`_getTransformedByMoveOperation( operation ) → Array.<Range>`

`_getTransformedBySplitOperation( operation ) → Range`

`_createFromRanges( ranges ) → Range`

`fromJSON( json, doc ) → Range`

`_createFromPositionAndShift( position, shift ) → Range`

`_createIn( element ) → Range`

`_createOn( item ) → Range`