Class

TextProxy (engine/model)

@ckeditor/ckeditor5-engine/src/model/textproxy

class

TextProxy represents a part of text node.

Since positions can be placed between characters of a text node, ranges may contain only parts of text nodes. When getting items contained in such range, we need to represent a part of that text node, since returning the whole text node would be incorrect. TextProxy solves this issue.

TextProxy has an API similar to Text and allows to do most of the common tasks performed on model nodes.

Note: Some TextProxy instances may represent whole text node, not just a part of it. See isPartial.

Note: TextProxy is not an instance of node. Keep this in mind when using it as a parameter of methods.

Note: TextProxy is a readonly interface. If you want to perform changes on model data represented by a TextProxy use model writer API.

Note: TextProxy instances are created on the fly, basing on the current state of model. Because of this, it is highly unrecommended to store references to TextProxy instances. TextProxy instances are not refreshed when model changes, so they might get invalidated. Instead, consider creating live position.

TextProxy instances are created by model tree walker. You should not need to create an instance of this class by your own.

Filtering

Properties

  • readonly

    data : string

    Text data represented by this text proxy.

  • readonly

    endOffset : null | number

    Offset at which this text proxy ends in it's parent.

  • readonly

    isPartial : boolean

    Flag indicating whether TextProxy instance covers only part of the original text node (true) or the whole text node (false).

    This is false when text proxy starts at the very beginning of textNode (offsetInText equals 0) and text proxy sizes is equal to text node size.

  • readonly

    offsetInText : number

    Offset in text node from which the text proxy starts.

  • readonly

    offsetSize : number

    Offset size of this text proxy. Equal to the number of characters represented by the text proxy.

  • readonly

    parent : null | Element | DocumentFragment

    Parent of this text proxy, which is same as parent of text node represented by this text proxy.

  • readonly

    root : Node | DocumentFragment

    Root of this text proxy, which is same as root of text node represented by this text proxy.

  • readonly

    startOffset : null | number

    Offset at which this text proxy starts in it's parent.

  • readonly

    textNode : Text

    Text node which part is represented by this text proxy.

Methods

  • internal

    constructor( textNode, offsetInText, length )

    Creates a text proxy.

    Parameters

    textNode : Text

    Text node which part is represented by this text proxy.

    offsetInText : number

    Offset in text node from which the text proxy starts.

    length : number

    Text proxy length, that is how many text node's characters, starting from offsetInText it represents.

  • getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<Element | DocumentFragment | TextProxy>

    Returns ancestors array of this text proxy.

    Parameters

    options : object

    Options object.

    Properties
    [ options.includeSelf ] : boolean

    When set to true this text proxy will be also included in parent's array.

    [ options.parentFirst ] : boolean

    When set to true, array will be sorted from text proxy parent to root element, otherwise root element will be the first item in the array.

    Defaults to {}

    Returns

    Array<Element | DocumentFragment | TextProxy>

    Array with ancestors.

  • getAttribute( key ) → unknown

    Gets an attribute value for given key or undefined if that attribute is not set on text proxy.

    Parameters

    key : string

    Key of attribute to look for.

    Returns

    unknown

    Attribute value or undefined.

  • getAttributeKeys() → IterableIterator<string>

    Returns iterator that iterates over this node's attribute keys.

    Returns

    IterableIterator<string>
  • getAttributes() → IterableIterator<tuple>

    Returns iterator that iterates over this node's attributes. Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value.

    This format is accepted by native Map object and also can be passed in Node constructor.

    Returns

    IterableIterator<tuple>
  • getPath() → Array<number>

    Gets path to this text proxy.

    Returns

    Array<number>

    Related:

  • hasAttribute( key ) → boolean

    Checks if this text proxy has an attribute for given key.

    Parameters

    key : string

    Key of attribute to check.

    Returns

    boolean

    true if attribute with given key is set on text proxy, false otherwise.

  • inherited

    is( type ) → this is Element | RootElement

    Checks whether the object is of type Element or its subclass.

    element.is( 'element' ); // -> true
    element.is( 'node' ); // -> true
    element.is( 'model:element' ); // -> true
    element.is( 'model:node' ); // -> true
    
    element.is( 'view:element' ); // -> false
    element.is( 'documentSelection' ); // -> false
    

    Assuming that the object being checked is an element, you can also check its name:

    element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
    text.is( 'element', 'imageBlock' ); -> false
    

    Parameters

    type : 'element' | 'model:element'

    Returns

    this is Element | RootElement
  • inherited

    is( type ) → this is RootElement

    Checks whether the object is of type RootElement.

    rootElement.is( 'rootElement' ); // -> true
    rootElement.is( 'element' ); // -> true
    rootElement.is( 'node' ); // -> true
    rootElement.is( 'model:rootElement' ); // -> true
    rootElement.is( 'model:element' ); // -> true
    rootElement.is( 'model:node' ); // -> true
    
    rootElement.is( 'view:element' ); // -> false
    rootElement.is( 'documentFragment' ); // -> false
    

    Assuming that the object being checked is an element, you can also check its name:

    rootElement.is( 'rootElement', '$root' ); // -> same as above
    

    Parameters

    type : 'rootElement' | 'model:rootElement'

    Returns

    this is RootElement
  • inherited

    is( type ) → this is LivePosition

    Checks whether the object is of type LivePosition.

    livePosition.is( 'position' ); // -> true
    livePosition.is( 'model:position' ); // -> true
    livePosition.is( 'liveposition' ); // -> true
    livePosition.is( 'model:livePosition' ); // -> true
    
    livePosition.is( 'view:position' ); // -> false
    livePosition.is( 'documentSelection' ); // -> false
    

    Parameters

    type : 'livePosition' | 'model:livePosition'

    Returns

    this is LivePosition
  • inherited

    is( type ) → this is Range | LiveRange

    Checks whether the object is of type Range or its subclass.

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

    Parameters

    type : 'range' | 'model:range'

    Returns

    this is Range | LiveRange
  • inherited

    is( type ) → this is Position | LivePosition

    Checks whether the object is of type Position or its subclass.

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

    Parameters

    type : 'position' | 'model:position'

    Returns

    this is Position | LivePosition
  • inherited

    is( type ) → this is Text

    Checks whether the object is of type Text.

    text.is( '$text' ); // -> true
    text.is( 'node' ); // -> true
    text.is( 'model:$text' ); // -> true
    text.is( 'model:node' ); // -> true
    
    text.is( 'view:$text' ); // -> false
    text.is( 'documentSelection' ); // -> false
    

    Note: Until version 20.0.0 this method wasn't accepting '$text' type. The legacy 'text' type is still accepted for backward compatibility.

    Parameters

    type : '$text' | 'model:$text'

    Returns

    this is Text
  • inherited

    is( type ) → this is LiveRange

    Checks whether the object is of type LiveRange.

    liveRange.is( 'range' ); // -> true
    liveRange.is( 'model:range' ); // -> true
    liveRange.is( 'liveRange' ); // -> true
    liveRange.is( 'model:liveRange' ); // -> true
    
    liveRange.is( 'view:range' ); // -> false
    liveRange.is( 'documentSelection' ); // -> false
    

    Parameters

    type : 'liveRange' | 'model:liveRange'

    Returns

    this is LiveRange
  • inherited

    is( type ) → this is Selection | DocumentSelection

    Checks whether the object is of type Selection or DocumentSelection.

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

    Parameters

    type : 'selection' | 'model:selection'

    Returns

    this is Selection | DocumentSelection
  • inherited

    is( type ) → this is Marker

    Checks whether the object is of type Marker.

    marker.is( 'marker' ); // -> true
    marker.is( 'model:marker' ); // -> true
    
    marker.is( 'view:element' ); // -> false
    marker.is( 'documentSelection' ); // -> false
    

    Parameters

    type : 'marker' | 'model:marker'

    Returns

    this is Marker
  • inherited

    is( type, name ) → boolean

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

    element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
    text.is( 'element', 'imageBlock' ); -> false
    

    Type parameters

    N : extends string

    Parameters

    type : 'element' | 'model:element'
    name : N

    Returns

    boolean
  • inherited

    is( type, name ) → boolean

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

    rootElement.is( 'rootElement', '$root' );
    

    Type parameters

    N : extends string

    Parameters

    type : 'rootElement' | 'model:rootElement'
    name : N

    Returns

    boolean
  • inherited

    is( type ) → this is TextProxy

    Checks whether the object is of type TextProxy.

    textProxy.is( '$textProxy' ); // -> true
    textProxy.is( 'model:$textProxy' ); // -> true
    
    textProxy.is( 'view:$textProxy' ); // -> false
    textProxy.is( 'range' ); // -> false
    

    Note: Until version 20.0.0 this method wasn't accepting '$textProxy' type. The legacy 'textProxt' type is still accepted for backward compatibility.

    Parameters

    type : '$textProxy' | 'model:$textProxy'

    Returns

    this is TextProxy
  • inherited

    is( type ) → this is DocumentSelection

    Checks whether the object is of type DocumentSelection.

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

    Parameters

    type : 'documentSelection' | 'model:documentSelection'

    Returns

    this is DocumentSelection
  • inherited

    is( type ) → this is DocumentFragment

    Checks whether the object is of type DocumentFragment.

    docFrag.is( 'documentFragment' ); // -> true
    docFrag.is( 'model:documentFragment' ); // -> true
    
    docFrag.is( 'view:documentFragment' ); // -> false
    docFrag.is( 'element' ); // -> false
    docFrag.is( 'node' ); // -> false
    

    Parameters

    type : 'documentFragment' | 'model:documentFragment'

    Returns

    this is DocumentFragment
  • inherited

    is( type ) → this is Node | Text | Element | RootElement

    Checks whether the object is of type Node or its subclass.

    This method is useful when processing model 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 view 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:

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

    By using this method it is also possible to check a name of an element:

    imageElement.is( 'element', 'imageBlock' ); // -> true
    imageElement.is( 'element', 'imageBlock' ); // -> same as above
    imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise
    

    Parameters

    type : 'node' | 'model:node'

    Returns

    this is Node | Text | Element | RootElement