Class

Range (engine/view)

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

class

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.

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

    Parameters

    start : Position

    Start position.

    end : null | Position

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

    Defaults to null

  • Symbol.iterator() → IterableIterator<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

    IterableIterator<TreeWalkerValue>
  • clone() → Range

    Clones this range.

    Returns

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

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

    Returns

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

    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.

    Returns

    null | Element
  • 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 = 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).

    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 ) → null | Range

    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.

  • getItems( options ) → IterableIterator<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 : TreeWalkerOptions

    Object with configuration options. See TreeWalker.

    Defaults to {}

    Returns

    IterableIterator<Item>
  • getPositions( options ) → IterableIterator<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 : TreeWalkerOptions

    Object with configuration options. See TreeWalker.

    Defaults to {}

    Returns

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

    Shrunk range.

  • getWalker( options ) → TreeWalker

    Creates a TreeWalker instance with this range as a boundary.

    Parameters

    options : TreeWalkerOptions

    Object with configuration options. See TreeWalker.

    Defaults to {}

    Returns

    TreeWalker
  • inherited

    is( type ) → this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

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

    is( type ) → this is AttributeElement

    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

    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

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

    is( type ) → this is RawElement

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

    is( type ) → this is DocumentFragment

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

    is( type ) → this is Range

    Checks whether this object is of type Range.

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

    Parameters

    type : 'range' | 'view:range'

    Returns

    this is Range
  • inherited

    is( type ) → this is Position

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

    is( type ) → this is TextProxy

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

    is( type ) → this is Text

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

    is( type ) → this is UIElement

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

    is( type ) → this is RootEditableElement

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

    is( type ) → this is EmptyElement

    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

    Checks whether this object is of type Selection or DocumentSelection.

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

    is( type, name ) → boolean

    Checks whether the object is of type Element or its subclass and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'element' | 'view:element'
    name : N

    Returns

    boolean
  • inherited

    is( type, name ) → boolean

    Checks whether the object is of type ContainerElement or its subclass and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'containerElement' | 'view:containerElement'
    name : N

    Returns

    boolean
  • inherited

    is( type, name ) → boolean

    Checks whether the object is of type EmptyElement has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'emptyElement' | 'view:emptyElement'
    name : N

    Returns

    boolean
  • inherited

    is( type, name ) → boolean

    Checks whether the object is of type RootEditableElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'rootElement' | 'view:rootElement'
    name : N

    Returns

    boolean
  • inherited

    is( type, name ) → boolean

    Checks whether the object is of type UIElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'uiElement' | 'view:uiElement'
    name : N

    Returns

    boolean
  • inherited

    is( type, name ) → boolean

    Checks whether the object is of type RawElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'rawElement' | 'view:rawElement'
    name : N

    Returns

    boolean
  • inherited

    is( type, name ) → boolean

    Checks whether the object is of type EditableElement or its subclass and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'editableElement' | 'view:editableElement'
    name : N

    Returns

    boolean
  • inherited

    is( type, name ) → boolean

    Checks whether the object is of type AttributeElement and has the specified name.

    Type parameters

    N : extends string

    Parameters

    type : 'attributeElement' | 'view:attributeElement'
    name : N

    Returns

    boolean
  • inherited

    is( type ) → this is DocumentSelection

    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

    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 a Node 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: or view: 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

    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.

    Parameters

    otherRange : Range

    Range to compare with.

    Returns

    boolean

    True if ranges intersect.

Static methods

  • internal static

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

    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

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

    _createIn( element ) → 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.

    Parameters

    element : Element | DocumentFragment

    Element which is a parent for the range.

    Returns

    Range
  • internal static

    _createOn( item ) → Range

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

    Parameters

    item : Item

    Returns

    Range