CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

Range (engine/view)

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

class
See source

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

Methods

  • constructor( start, [ end ] )

    Creates a range spanning from start position to end position.

    See source

    Note: Constructor creates it's own Position instances basing on passed values.

    Parameters

    start : Position

    Start position.

    [ end ] : Position

    End position. If not set, range will be collapsed at the start position.

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

    Iterable interface.

    See source

    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 and ignoreElementEnd option set to true.

    Returns

    Iterable.<TreeWalkerValue>

  • clone() → Range

    Clones this range.

    See source

    Returns

    Range

  • 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() → Node | DocumentFragment | null

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

    See source

    Returns

    Node | 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 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

    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).

    See source

    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:

    Returns

    Range

    Enlarged range.

  • 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 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

    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 view 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 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>

  • 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>

  • 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).

    See source

    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:

    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.

    See source

    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 type.

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

range.is( 'model:range' ); // -> false
range.is( 'element' ); // -> false
range.is( 'selection' ); // -> false

    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.

    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 the given range.

    See source

    Parameters

    otherRange : Range

    Range to compare with.

    Returns

    Boolean

    True if ranges intersect.

Static methods

  • _createFromParentsAndOffsets( startElement, startOffset, endElement, endOffset ) → Range

    protected static

    Creates a range from the given parents and offsets.

    See source

    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. 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 view item and ends after it.

    See source

    Parameters

    item : Item

    Returns

    Range