CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

Position (engine/view)

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

class
See source

Position in the view tree. Position is represented by its parent node and an offset in this parent.

In order to create a new position instance use the createPosition*() factory methods available in:

Filtering

Properties

  • editableElement : EditableElement | null

    See source

    EditableElement instance that contains this position, or null if position is not inside an editable element.

  • readonly

    isAtEnd : Boolean

    See source

    Is true if position is at the end of its parent, false otherwise.

  • readonly

    isAtStart : Boolean

    See source

    Is true if position is at the beginning of its parent, false otherwise.

  • readonly

    nodeAfter : Node | null

    See source

    Node directly after the position. Equals null when there is no node after position or position is located inside text node.

  • readonly

    nodeBefore : Node | null

    See source

    Node directly before the position. Equals null when there is no node before position or position is located inside text node.

  • readonly

    offset : Number

    See source

    Position offset.

  • readonly

    parent : Node | DocumentFragment

    See source

    Position parent.

  • readonly

    root : Node | DocumentFragment

    See source

    Position's root, that is the root of the position's parent element.

Methods

  • constructor( parent, offset )

    See source

    Creates a position.

    Parameters

    parent : Node | DocumentFragment

    Position parent.

    offset : Number

    Position offset.

  • compareWith( otherPosition ) → PositionRelation

    See source

    Checks whether this position is before, after or in same position that other position. Two positions may be also different when they are located in separate roots.

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    PositionRelation

  • getAncestors() → Array

    See source

    Returns ancestors array of this position, that is this position's parent and it's ancestors.

    Returns

    Array

    Array with ancestors.

  • getCommonAncestor( position ) → Node | DocumentFragment | null

    See source

    Returns a Node or DocumentFragment which is a common ancestor of both positions.

    Parameters

    position : Position

    Returns

    Node | DocumentFragment | null

  • getLastMatchingPosition( skip, options ) → Position

    See source

    Gets the farthest position which matches the callback using TreeWalker.

    For example:

    getLastMatchingPosition( value => value.type == 'text' ); // <p>{}foo</p> -> <p>foo[]</p>
getLastMatchingPosition( value => value.type == 'text', { direction: 'backward' } ); // <p>foo[]</p> -> <p>{}foo</p>
getLastMatchingPosition( value => false ); // Do not move the position.

    Parameters

    skip : function

    Callback function. Gets TreeWalkerValue and should return true if the value should be skipped or false if not.

    options : Object

    Object with configuration options. See TreeWalker.

    Returns

    Position

    The position after the last item which matches the skip callback test.

  • getShiftedBy( shift ) → Position

    See source

    Returns a new instance of Position with offset incremented by shift value.

    Parameters

    shift : Number

    How position offset should get changed. Accepts negative values.

    Returns

    Position

    Shifted position.

  • getWalker( options = { [options.boundaries], [options.singleCharacters], [options.shallow], [options.ignoreElementEnd] } )

    See source

    Creates a TreeWalker instance with this positions as a start position.

    Parameters

    options : Object

    Object with configuration options. See TreeWalker

    Properties
    [ options.boundaries ] : Range

    Range to define boundaries of the iterator.

    [ options.singleCharacters ] : Boolean

    Defaults to false

    [ options.shallow ] : Boolean

    Defaults to false

    [ options.ignoreElementEnd ] : Boolean

    Defaults to false

  • is( type ) → Boolean

    See source

    Checks whether this object is of the given type.

    position.is( 'position' ); // -> true
position.is( 'view:position' ); // -> true

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

    Check the entire list of view objects which implement the is() method.

    Parameters

    type : String

    Returns

    Boolean

  • isAfter( otherPosition ) → Boolean

    See source

    Checks whether this position is located after given position. When method returns false it does not mean that this position is before give one. Two positions may be located inside separate roots and in that situation this method will still return false.

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    Boolean

    Returns true if this position is after given position.

    Related:

  • isBefore( otherPosition ) → Boolean

    See source

    Checks whether this position is located before given position. When method returns false it does not mean that this position is after give one. Two positions may be located inside separate roots and in that situation this method will still return false.

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    Boolean

    Returns true if this position is before given position.

    Related:

  • isEqual( otherPosition ) → Boolean

    See source

    Checks whether this position equals given position.

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    Boolean

    True if positions are same.

Static methods

  • protected static

    _createAfter( item ) → Position

    See source

    Creates a new position after given view item.

    Parameters

    item : Item

    View item after which the position should be located.

    Returns

    Position

  • protected static

    _createAt( itemOrPosition, [ offset ] )

    See source

    Creates position at the given location. The location can be specified as:

    • a position,
    • parent element and offset (offset defaults to 0),
    • parent element and 'end' (sets position at the end of that element),
    • view item and 'before' or 'after' (sets position before or after given view item).

    This method is a shortcut to other constructors such as:

    Parameters

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

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

  • protected static

    _createBefore( item ) → Position

    See source

    Creates a new position before given view item.

    Parameters

    item : Item

    View item before which the position should be located.

    Returns

    Position