CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 5/API
Class

Range (engine/view)

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

class

Tree view range.

Filtering

Properties

  • end : Position

    readonly

    End position.

  • isCollapsed : Boolean

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

  • isFlat : Boolean

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

  • root : Element | DocumentFragment

    Range root element.

  • start : Position

    readonly

    Start position.

Methods

  • constructor( start, [ end ] )

    Creates a range spanning from start position to end position.

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

    Returns

    Iterable.<TreeWalkerValue>

  • containsPosition( position ) → Boolean

    Checks whether this range contains given position.

    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.

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

    Returns

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

    Examples:

    let foo = new Text( 'foo' );
let img = new ContainerElement( 'img' );
let bar = new Text( 'bar' );
let p = new ContainerElement( 'p', null, [ foo, img, bar ] );

let range = new Range( new Position( foo, 2 ), new Position( bar, 1 ); // "o", img, "b" are in range.
let otherRange = new Range( new Position( foo, 1 ), new Position( bar, 2 ); "oo", img, "ba" are in range.
let transformed = range.getDifference( otherRange );
// transformed array has no ranges because `otherRange` contains `range`

otherRange = new Range( new Position( foo, 1 ), new Position( p, 2 ); // "oo", img are in range.
transformed = range.getDifference( otherRange );
// transformed array has one range: from ( p, 2 ) to ( bar, 1 )

otherRange = new Range( new Position( p, 1 ), new Position( 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).

    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.

    Examples:

    let foo = new Text( 'foo' );
let img = new ContainerElement( 'img' );
let bar = new Text( 'bar' );
let p = new ContainerElement( 'p', null, [ foo, img, bar ] );

let range = new Range( new Position( foo, 2 ), new Position( bar, 1 ); // "o", img, "b" are in range.
let otherRange = new Range( new Position( foo, 1 ), new Position( p, 2 ); // "oo", img are in range.
let transformed = range.getIntersection( otherRange ); // range from ( foo, 1 ) to ( p, 2 ).

otherRange = new Range( new Position( bar, 1 ), new Position( 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.

    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.

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

    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] } )

    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

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

    Parameters

    otherRange : Range

    Range to compare with.

    Returns

    Boolean

    True if ranges intersect.

Static methods

  • createCollapsedAt( itemOrPosition, [ offset ] )

    static

    Creates a collapsed range at given position or on the given item.

    Parameters

    itemOrPosition : Item | Position
    [ offset ] : Number | 'end' | 'before' | 'after'

    Offset or one of the flags. Used only when first parameter is a view item.

    Defaults to 0

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

    static

    Creates a range from 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

    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.

    Parameters

    position : Position

    Beginning of the range.

    shift : Number

    How long the range should be.

    Returns

    Range

  • createFromRange( range ) → Range

    static

    Creates and returns a new instance of Range which is equal to passed range.

    Parameters

    range : Range

    Range to clone.

    Returns

    Range

  • createIn( element ) → Range

    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.

    Parameters

    element : Element

    Element which is a parent for the range.

    Returns

    Range

  • createOn( item ) → Range

    static

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

    Parameters

    item : Item

    Returns

    Range