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

  • readonly

    editableElement : null | EditableElement

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

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

    See source

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

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

  • clone() → Position

    See source

    Clones this position.

    Returns

    Position

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

    See source

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

    Returns

    Array<Node | DocumentFragment>

    Array with ancestors.

  • getCommonAncestor( position ) → null | Node | DocumentFragment

    See source

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

    Parameters

    position : Position

    Returns

    null | Node | DocumentFragment

  • 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 : ( value: TreeWalkerValue ) => boolean

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

    options : TreeWalkerOptions

    Object with configuration options. See TreeWalker.

    Defaults to {}

    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 ) → TreeWalker

    See source

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

    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

    See source

    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

    See source

    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

    See source

    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 RootEditableElement

    See source

    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 RawElement

    See source

    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 EmptyElement

    See source

    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 ContainerElement | EditableElement | RootEditableElement

    See source

    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 UIElement

    See source

    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 DocumentFragment

    See source

    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 Position

    See source

    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 Selection | DocumentSelection

    See source

    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

    See source

    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

    See source

    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

    See source

    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

    See source

    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

    See source

    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

    See source

    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

    See source

    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

    See source

    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

    See source

    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 Range

    See source

    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 TextProxy

    See source

    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

    See source

    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 Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement

    See source

    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

  • 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

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

  • internal static

    _createAt( itemOrPosition, [ offset ] ) → Position

    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 : Position | Item
    [ offset ] : PositionOffset

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

    Returns

    Position

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