Range (engine/view)
@ckeditor/ckeditor5-engine/src/view/range
Range in the view tree. A range is represented by its start and end positions.
In order to create a new position instance use the createPosition*()
factory methods available in:
Filtering
Properties
-
End position.
-
Returns whether the range is collapsed, that is it start and end positions are equal.
-
Range root element.
-
Start position.
Methods
-
constructor( start, end )
module:engine/view/range~Range#constructor
Creates a range spanning from
start
position toend
position.Note: Constructor creates it's own
Position
instances basing on passed values.Parameters
-
Symbol.iterator() → IterableIterator<TreeWalkerValue>
module:engine/view/range~Range#Symbol.iterator
Iterable interface.
Iterates over all view items that are in this range and returns them together with additional information like length or positions, grouped as
TreeWalkerValue
.This iterator uses TreeWalker with
boundaries
set to this range andignoreElementEnd
option set totrue
.Returns
IterableIterator<TreeWalkerValue>
-
-
containsPosition( position ) → boolean
module:engine/view/range~Range#containsPosition
-
containsRange( otherRange, loose ) → boolean
module:engine/view/range~Range#containsRange
Checks whether this range contains given range.
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() → null | Node | DocumentFragment
module:engine/view/range~Range#getCommonAncestor
Returns a
Node
orDocumentFragment
which is a common ancestor of range's both ends (in which the entire range is contained).Returns
null | Node | DocumentFragment
-
getContainedElement() → null | Element
module:engine/view/range~Range#getContainedElement
-
getDifference( otherRange ) → Array<Range>
module:engine/view/range~Range#getDifference
Computes which part(s) of this range is not a part of given range. Returned array contains zero, one or two ranges.
Examples:
let foo = downcastWriter.createText( 'foo' ); let img = downcastWriter.createContainerElement( 'img' ); let bar = downcastWriter.createText( 'bar' ); let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] ); let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range. let otherRange = view.createRange( // "oo", img, "ba" are in range. view.createPositionAt( foo, 1 ), view.createPositionAt( bar, 2 ) ); let transformed = range.getDifference( otherRange ); // transformed array has no ranges because `otherRange` contains `range` otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range. transformed = range.getDifference( otherRange ); // transformed array has one range: from ( p, 2 ) to ( bar, 1 ) otherRange = view.createRange( view.createPositionAt( p, 1 ), view.createPositionAt( p, 2 ) ); // img is in range. transformed = range.getDifference( otherRange ); // transformed array has two ranges: from ( foo, 1 ) to ( p, 1 ) and from ( p, 2 ) to ( bar, 1 )
Parameters
otherRange : Range
Range to differentiate against.
Returns
Array<Range>
The difference between ranges.
-
getEnlarged() → Range
module:engine/view/range~Range#getEnlarged
Creates a maximal range that has the same content as this range but is expanded in both ways (at the beginning and at the end).
For example:
<p>Foo</p><p><b>{Bar}</b></p> -> <p>Foo</p>[<p><b>Bar</b>]</p> <p><b>foo</b>{bar}<span></span></p> -> <p><b>foo[</b>bar<span></span>]</p>
Note that in the sample above:
<p>
have type ofContainerElement
,<b>
have type ofAttributeElement
,<span>
have type ofUIElement
.
Returns
Range
Enlarged range.
-
getIntersection( otherRange ) → null | Range
module:engine/view/range~Range#getIntersection
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
.Examples:
let foo = downcastWriter.createText( 'foo' ); let img = downcastWriter.createContainerElement( 'img' ); let bar = downcastWriter.createText( 'bar' ); let p = downcastWriter.createContainerElement( 'p', null, [ foo, img, bar ] ); let range = view.createRange( view.createPositionAt( foo, 2 ), view.createPositionAt( bar, 1 ); // "o", img, "b" are in range. let otherRange = view.createRange( view.createPositionAt( foo, 1 ), view.createPositionAt( p, 2 ); // "oo", img are in range. let transformed = range.getIntersection( otherRange ); // range from ( foo, 1 ) to ( p, 2 ). otherRange = view.createRange( view.createPositionAt( bar, 1 ), view.createPositionAt( bar, 3 ); "ar" is in range. transformed = range.getIntersection( otherRange ); // null - no common part.
Parameters
otherRange : Range
Range to check for intersection.
Returns
null | Range
A common part of given ranges or
null
if ranges have no common part.
-
Returns an iterator that iterates over all view items that are in this range and returns them.
This method uses
TreeWalker
withboundaries
set to this range andignoreElementEnd
option set totrue
. However it returns only items, notTreeWalkerValue
.You may specify additional options for the tree walker. See
TreeWalker
for a full list of available options.Parameters
options : TreeWalkerOptions
Object with configuration options. See
TreeWalker
.Defaults to
{}
Returns
IterableIterator<Item>
-
getPositions( options ) → IterableIterator<Position>
module:engine/view/range~Range#getPositions
Returns an iterator that iterates over all positions that are boundaries or contained in this range.
This method uses
TreeWalker
withboundaries
set to this range. However it returns only positions, notTreeWalkerValue
.You may specify additional options for the tree walker. See
TreeWalker
for a full list of available options.Parameters
options : TreeWalkerOptions
Object with configuration options. See
TreeWalker
.Defaults to
{}
Returns
IterableIterator<Position>
-
getTrimmed() → Range
module:engine/view/range~Range#getTrimmed
Creates a minimum range that has the same content as this range but is trimmed in both ways (at the beginning and at the end).
For example:
<p>Foo</p>[<p><b>Bar</b>]</p> -> <p>Foo</p><p><b>{Bar}</b></p> <p><b>foo[</b>bar<span></span>]</p> -> <p><b>foo</b>{bar}<span></span></p>
Note that in the sample above:
<p>
have type ofContainerElement
,<b>
have type ofAttributeElement
,<span>
have type ofUIElement
.
Returns
Range
Shrunk range.
-
getWalker( options ) → TreeWalker
module:engine/view/range~Range#getWalker
Creates a TreeWalker instance with this range as a boundary.
Parameters
options : TreeWalkerOptions
Object with configuration options. See
TreeWalker
.Defaults to
{}
Returns
-
inherited
is( type ) → this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
module:engine/view/range~Range#is:ELEMENT
Checks whether this object is of type
Element
or its subclass.element.is( 'element' ); // -> true element.is( 'node' ); // -> true element.is( 'view:element' ); // -> true element.is( 'view:node' ); // -> true element.is( 'model:element' ); // -> false element.is( 'documentSelection' ); // -> false
Assuming that the object being checked is an element, you can also check its name:
element.is( 'element', 'img' ); // -> true if this is an <img> element text.is( 'element', 'img' ); -> false
Parameters
type : 'element' | 'view:element'
Returns
this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
-
Checks whether this object is of type
AttributeElement
.attributeElement.is( 'attributeElement' ); // -> true attributeElement.is( 'element' ); // -> true attributeElement.is( 'node' ); // -> true attributeElement.is( 'view:attributeElement' ); // -> true attributeElement.is( 'view:element' ); // -> true attributeElement.is( 'view:node' ); // -> true attributeElement.is( 'model:element' ); // -> false attributeElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is an attribute element, you can also check its name:
attributeElement.is( 'element', 'b' ); // -> true if this is a bold element attributeElement.is( 'attributeElement', 'b' ); // -> same as above text.is( 'element', 'b' ); -> false
Parameters
type : 'attributeElement' | 'view:attributeElement'
Returns
this is AttributeElement
-
inherited
is( type ) → this is EditableElement | RootEditableElement
module:engine/view/range~Range#is:EDITABLE_ELEMENT
Checks whether this object is of type
EditableElement
or its subclass.editableElement.is( 'editableElement' ); // -> true editableElement.is( 'element' ); // -> true editableElement.is( 'node' ); // -> true editableElement.is( 'view:editableElement' ); // -> true editableElement.is( 'view:element' ); // -> true editableElement.is( 'view:node' ); // -> true editableElement.is( 'model:element' ); // -> false editableElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is an editbale element, you can also check its name:
editableElement.is( 'element', 'div' ); // -> true if this is a div element editableElement.is( 'editableElement', 'div' ); // -> same as above text.is( 'element', 'div' ); -> false
Parameters
type : 'editableElement' | 'view:editableElement'
Returns
this is EditableElement | RootEditableElement
-
inherited
is( type ) → this is ContainerElement | EditableElement | RootEditableElement
module:engine/view/range~Range#is:CONTAINER_ELEMENT
Checks whether this object is of type
ContainerElement
or its subclass.containerElement.is( 'containerElement' ); // -> true containerElement.is( 'element' ); // -> true containerElement.is( 'node' ); // -> true containerElement.is( 'view:containerElement' ); // -> true containerElement.is( 'view:element' ); // -> true containerElement.is( 'view:node' ); // -> true containerElement.is( 'model:element' ); // -> false containerElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is a container element, you can also check its name:
containerElement.is( 'element', 'div' ); // -> true if this is a div container element containerElement.is( 'contaienrElement', 'div' ); // -> same as above text.is( 'element', 'div' ); -> false
Parameters
type : 'containerElement' | 'view:containerElement'
Returns
this is ContainerElement | EditableElement | RootEditableElement
-
Checks whether this object is of type
RawElement
.rawElement.is( 'rawElement' ); // -> true rawElement.is( 'element' ); // -> true rawElement.is( 'node' ); // -> true rawElement.is( 'view:rawElement' ); // -> true rawElement.is( 'view:element' ); // -> true rawElement.is( 'view:node' ); // -> true rawElement.is( 'model:element' ); // -> false rawElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is a raw element, you can also check its name:
rawElement.is( 'img' ); // -> true if this is an img element rawElement.is( 'rawElement', 'img' ); // -> same as above text.is( 'img' ); -> false
Parameters
type : 'rawElement' | 'view:rawElement'
Returns
this is RawElement
-
hecks whether this object is of type
DocumentFragment
.docFrag.is( 'documentFragment' ); // -> true docFrag.is( 'view:documentFragment' ); // -> true docFrag.is( 'model:documentFragment' ); // -> false docFrag.is( 'element' ); // -> false docFrag.is( 'node' ); // -> false
Parameters
type : 'documentFragment' | 'view:documentFragment'
Returns
this is DocumentFragment
-
Checks whether this object is of type
Position
.position.is( 'position' ); // -> true position.is( 'view:position' ); // -> true position.is( 'model:position' ); // -> false position.is( 'element' ); // -> false position.is( 'range' ); // -> false
Parameters
type : 'position' | 'view:position'
Returns
this is Position
-
Checks whether this object is of type
TextProxy
.textProxy.is( '$textProxy' ); // -> true textProxy.is( 'view:$textProxy' ); // -> true textProxy.is( 'model:$textProxy' ); // -> false textProxy.is( 'element' ); // -> false textProxy.is( 'range' ); // -> false
Note: Until version 20.0.0 this method wasn't accepting
'$textProxy'
type. The legacy'textProxy'
type is still accepted for backward compatibility.Parameters
type : '$textProxy' | 'view:$textProxy'
Returns
this is TextProxy
-
Checks whether this object is of type
Text
.text.is( '$text' ); // -> true text.is( 'node' ); // -> true text.is( 'view:$text' ); // -> true text.is( 'view:node' ); // -> true text.is( 'model:$text' ); // -> false text.is( 'element' ); // -> false text.is( 'range' ); // -> false
Parameters
type : '$text' | 'view:$text'
Returns
this is Text
-
Checks whether this object is of type
UIElement
.uiElement.is( 'uiElement' ); // -> true uiElement.is( 'element' ); // -> true uiElement.is( 'node' ); // -> true uiElement.is( 'view:uiElement' ); // -> true uiElement.is( 'view:element' ); // -> true uiElement.is( 'view:node' ); // -> true uiElement.is( 'model:element' ); // -> false uiElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is an ui element, you can also check its name:
uiElement.is( 'element', 'span' ); // -> true if this is a span ui element uiElement.is( 'uiElement', 'span' ); // -> same as above text.is( 'element', 'span' ); -> false
Parameters
type : 'uiElement' | 'view:uiElement'
Returns
this is UIElement
-
Checks whether this object is of type
RootEditableElement
.rootEditableElement.is( 'rootElement' ); // -> true rootEditableElement.is( 'editableElement' ); // -> true rootEditableElement.is( 'element' ); // -> true rootEditableElement.is( 'node' ); // -> true rootEditableElement.is( 'view:editableElement' ); // -> true rootEditableElement.is( 'view:element' ); // -> true rootEditableElement.is( 'view:node' ); // -> true rootEditableElement.is( 'model:element' ); // -> false rootEditableElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is a root editable element, you can also check its name:
rootEditableElement.is( 'element', 'div' ); // -> true if this is a div root editable element rootEditableElement.is( 'rootElement', 'div' ); // -> same as above text.is( 'element', 'div' ); -> false
Parameters
type : 'rootElement' | 'view:rootElement'
Returns
this is RootEditableElement
-
Checks whether this object is of type
EmptyElement
.emptyElement.is( 'emptyElement' ); // -> true emptyElement.is( 'element' ); // -> true emptyElement.is( 'node' ); // -> true emptyElement.is( 'view:emptyElement' ); // -> true emptyElement.is( 'view:element' ); // -> true emptyElement.is( 'view:node' ); // -> true emptyElement.is( 'model:element' ); // -> false emptyElement.is( 'documentFragment' ); // -> false
Assuming that the object being checked is an empty element, you can also check its name:
emptyElement.is( 'element', 'img' ); // -> true if this is a img element emptyElement.is( 'emptyElement', 'img' ); // -> same as above text.is( 'element', 'img' ); -> false
Parameters
type : 'emptyElement' | 'view:emptyElement'
Returns
this is EmptyElement
-
inherited
is( type ) → this is Selection | DocumentSelection
module:engine/view/range~Range#is:SELECTION
Checks whether this object is of type
Selection
orDocumentSelection
.selection.is( 'selection' ); // -> true selection.is( 'view:selection' ); // -> true selection.is( 'model:selection' ); // -> false selection.is( 'element' ); // -> false selection.is( 'range' ); // -> false
Parameters
type : 'selection' | 'view:selection'
Returns
this is Selection | DocumentSelection
-
Checks whether the object is of type
Element
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'element' | 'view:element'
name : N
Returns
boolean
-
Checks whether the object is of type
ContainerElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'containerElement' | 'view:containerElement'
name : N
Returns
boolean
-
Checks whether the object is of type
EmptyElement
has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'emptyElement' | 'view:emptyElement'
name : N
Returns
boolean
-
Checks whether the object is of type
RootEditableElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'rootElement' | 'view:rootElement'
name : N
Returns
boolean
-
Checks whether the object is of type
UIElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'uiElement' | 'view:uiElement'
name : N
Returns
boolean
-
Checks whether the object is of type
RawElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'rawElement' | 'view:rawElement'
name : N
Returns
boolean
-
Checks whether the object is of type
EditableElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'editableElement' | 'view:editableElement'
name : N
Returns
boolean
-
Checks whether the object is of type
AttributeElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'attributeElement' | 'view:attributeElement'
name : N
Returns
boolean
-
inherited
is( type ) → this is DocumentSelection
module:engine/view/range~Range#is:DOCUMENT_SELECTION
Checks whether this object is of type
DocumentSelection
.`docSelection.is( 'selection' ); // -> true docSelection.is( 'documentSelection' ); // -> true docSelection.is( 'view:selection' ); // -> true docSelection.is( 'view:documentSelection' ); // -> true docSelection.is( 'model:documentSelection' ); // -> false docSelection.is( 'element' ); // -> false docSelection.is( 'node' ); // -> false
Parameters
type : 'documentSelection' | 'view:documentSelection'
Returns
this is DocumentSelection
-
inherited
is( type ) → this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
module:engine/view/range~Range#is:NODE
Checks whether this object is of type
Node
or its subclass.This method is useful when processing view objects that are of unknown type. For example, a function may return a
DocumentFragment
or aNode
that can be either a text node or an element. This method can be used to check what kind of object is returned.someObject.is( 'element' ); // -> true if this is an element someObject.is( 'node' ); // -> true if this is a node (a text node or an element) someObject.is( 'documentFragment' ); // -> true if this is a document fragment
Since this method is also available on a range of model objects, you can prefix the type of the object with
model:
orview:
to check, for example, if this is the model's or view's element:viewElement.is( 'view:element' ); // -> true viewElement.is( 'model:element' ); // -> false
By using this method it is also possible to check a name of an element:
imgElement.is( 'element', 'img' ); // -> true imgElement.is( 'view:element', 'img' ); // -> same as above, but more precise
Parameters
type : 'node' | 'view:node'
Returns
this is Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
-
isEqual( otherRange ) → boolean
module:engine/view/range~Range#isEqual
Two ranges are equal if their start and end positions are equal.
Parameters
otherRange : Range
Range to compare with.
Returns
boolean
true
if ranges are equal,false
otherwise
-
isIntersecting( otherRange ) → boolean
module:engine/view/range~Range#isIntersecting
Checks and returns whether this range intersects with the given range.
Parameters
otherRange : Range
Range to compare with.
Returns
boolean
True if ranges intersect.
Static methods
-
internal static
_createFromParentsAndOffsets( startElement, startOffset, endElement, endOffset ) → Range
module:engine/view/range~Range._createFromParentsAndOffsets
Creates a range from the given parents and offsets.
Parameters
startElement : Element | DocumentFragment
Start position parent element.
startOffset : number
Start position offset.
endElement : Element | DocumentFragment
End position parent element.
endOffset : number
End position offset.
Returns
Range
Created range.
-
internal static
_createFromPositionAndShift( position, shift ) → Range
module:engine/view/range~Range._createFromPositionAndShift
-
Creates a range inside an element which starts before the first child of that element and ends after the last child of that element.
Parameters
element : Element | DocumentFragment
Element which is a parent for the range.
Returns
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.