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.
-
isCollapsed : Boolean
Returns whether the range is collapsed, that is it start and end positions are equal.
-
isFlat : Boolean
-
Range root element.
-
Start position.
Methods
-
constructor( start, [ end ] )
Creates a range spanning from
start
position toend
position. -
Symbol.iterator() → Iterable.<TreeWalkerValue>
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
Iterable.<TreeWalkerValue>
-
Clones this range.
Returns
-
containsPosition( position ) → Boolean
Checks whether this range contains given position.
-
containsRange( otherRange, [ loose ] ) → Boolean
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() → Node | DocumentFragment | null
Returns a
Node
orDocumentFragment
which is a common ancestor of range's both ends (in which the entire range is contained).Returns
Node | DocumentFragment | null
-
getContainedElement() → Element | null
-
getDifference( otherRange ) → Array.<Range>
-
getEnlarged() → Range
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:
Note that in the sample above:
<p>
have type ofContainerElement
,<b>
have type ofAttributeElement
,<span>
have type ofUIElement
.
Returns
Range
Enlarged range.
-
getIntersection( otherRange ) → Range | null
-
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 : Object
Object with configuration options. See
TreeWalker
.
Returns
Iterable.<Item>
-
getPositions( options ) → Iterable.<Position>
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 : Object
Object with configuration options. See
TreeWalker
.
Returns
Iterable.<Position>
-
getTrimmed() → Range
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:
Note that in the sample above:
<p>
have type ofContainerElement
,<b>
have type ofAttributeElement
,<span>
have type ofUIElement
.
Returns
Range
Shrink range.
-
getWalker( options = { [options.startPosition], [options.singleCharacters], [options.shallow], [options.ignoreElementEnd] } ) → TreeWalker
Creates a TreeWalker instance with this range as a boundary.
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
-
is( type ) → Boolean
Checks whether this object is of the given type.
Check the entire list of view 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.
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 the given range.
Static methods
-
_createFromParentsAndOffsets( startElement, startOffset, endElement, endOffset ) → Range
protected static
Creates a range from the given parents and offsets.
Parameters
startElement : Node | DocumentFragment
Start position parent element.
startOffset : Number
Start position offset.
endElement : Node | DocumentFragment
End position parent element.
endOffset : Number
End position offset.
Returns
Range
Created range.
-
_createFromPositionAndShift( position, shift ) → Range
protected static
Creates a new range, spreading from specified position to a position moved by given
shift
. Ifshift
is a negative value, shifted position is treated as the beginning of the range. -
Creates a range inside an element which starts before the first child of that element and ends after the last child of that element.
-
Creates a range that starts before given view item and ends after it.
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.