CKEditor Ecosystem Documentation
Search
⚠️ WarningNightly documentation ahead. Switch to the stable editor documentation.
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

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

    See source

  • isAtEnd : Boolean

    readonly

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

    See source

  • isAtStart : Boolean

    readonly

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

    See source

  • nodeAfter : Node | null

    readonly

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

    See source

  • nodeBefore : Node | null

    readonly

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

    See source

  • offset : Number

    readonly

    Position offset.

    See source

  • parent : Node | DocumentFragment

    readonly

    Position parent.

    See source

  • root : Node | DocumentFragment

    readonly

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

    See source

Methods

  • constructor( parent, offset )

    Creates a position.

    See source

    Parameters

    parent : Node | DocumentFragment

    Position parent.

    offset : Number

    Position offset.

  • compareWith( otherPosition ) → PositionRelation

    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.

    See source

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    PositionRelation

  • getAncestors() → Array

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

    See source

    Returns

    Array

    Array with ancestors.

  • getCommonAncestor( position ) → Node | DocumentFragment | null

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

    See source

    Parameters

    position : Position

    Returns

    Node | DocumentFragment | null

  • getLastMatchingPosition( skip, options ) → Position

    Gets the farthest position which matches the callback using TreeWalker.

    See source

    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

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

    See source

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

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

    See source

    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

    Checks whether this object is of the given type.

    See source
    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

    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.

    See source

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    Boolean

    Returns true if this position is after given position.

    Related:

  • isBefore( otherPosition ) → Boolean

    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.

    See source

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    Boolean

    Returns true if this position is before given position.

    Related:

  • isEqual( otherPosition ) → Boolean

    Checks whether this position equals given position.

    See source

    Parameters

    otherPosition : Position

    Position to compare with.

    Returns

    Boolean

    True if positions are same.

Static methods

  • _createAfter( item ) → Position

    protected static

    Creates a new position after given view item.

    See source

    Parameters

    item : Item

    View item after which the position should be located.

    Returns

    Position

  • _createAt( itemOrPosition, [ offset ] )

    protected static

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

    See source
    • 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.

  • _createBefore( item ) → Position

    protected static

    Creates a new position before given view item.

    See source

    Parameters

    item : Item

    View item before which the position should be located.

    Returns

    Position