TextProxy (engine/view)
@ckeditor/ckeditor5-engine/src/view/textproxy
TextProxy is a wrapper for substring of Text
. Instance of this class is created by
TreeWalker
when only a part of Text
needs to be returned.
TextProxy
has an API similar to Text and allows to do most of the common tasks performed
on view nodes.
Note: Some TextProxy
instances may represent whole text node, not just a part of it.
See isPartial
.
Note: TextProxy
is a readonly interface.
Note: TextProxy
instances are created on the fly basing on the current state of parent Text
.
Because of this it is highly unrecommended to store references to `TextProxy instances because they might get
invalidated due to operations on Document. Also TextProxy is not a Node
so it can not be
inserted as a child of Element
.
TextProxy
instances are created by view tree walker. You should not need to create
an instance of this class by your own.
Filtering
Properties
-
Text data represented by this text proxy.
-
View document that owns this text proxy, or
null
if the text proxy is inside document fragment. -
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 equals0
) and text proxy sizes is equal to text node size. -
Offset in the
textNode
where thisTextProxy
instance starts. -
Offset size of this node.
-
Parent of this text proxy, which is same as parent of text node represented by this text proxy.
-
Root of this text proxy, which is same as root of text node represented by this text proxy.
-
Reference to the
Text
element which TextProxy is a substring.
Methods
-
internal
constructor( textNode, offsetInText, length )
module:engine/view/textproxy~TextProxy#constructor
Creates a text proxy.
Parameters
-
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<Text | Element | DocumentFragment>
module:engine/view/textproxy~TextProxy#getAncestors
Returns ancestors array of this text proxy.
Parameters
options : object
Options object.
Properties[ options.includeSelf ] : boolean
When set to
true
, textNode 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<Text | Element | DocumentFragment>
Array with ancestors.
-
inherited
is( type ) → this is Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
module:engine/view/textproxy~TextProxy#is:ELEMENT
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
module:engine/view/textproxy~TextProxy#is:ATTRIBUTE_ELEMENT
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
module:engine/view/textproxy~TextProxy#is:EDITABLE_ELEMENT
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
-
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
-
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
module:engine/view/textproxy~TextProxy#is:DOCUMENT_FRAGMENT
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
-
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
module:engine/view/textproxy~TextProxy#is:SELECTION
Checks whether this object is of type
Selection
orDocumentSelection
.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
-
Checks whether the object is of type
Element
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'element' | 'view:element'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/textproxy~TextProxy#is:CONTAINER_ELEMENT_NAME
Checks whether the object is of type
ContainerElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'containerElement' | 'view:containerElement'
name : N
Returns
boolean
-
Checks whether the object is of type
EmptyElement
has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'emptyElement' | 'view:emptyElement'
name : N
Returns
boolean
-
Checks whether the object is of type
RootEditableElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'rootElement' | 'view:rootElement'
name : N
Returns
boolean
-
Checks whether the object is of type
UIElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'uiElement' | 'view:uiElement'
name : N
Returns
boolean
-
Checks whether the object is of type
RawElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'rawElement' | 'view:rawElement'
name : N
Returns
boolean
-
Checks whether the object is of type
EditableElement
or its subclass and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'editableElement' | 'view:editableElement'
name : N
Returns
boolean
-
inherited
is( type, name ) → boolean
module:engine/view/textproxy~TextProxy#is:ATTRIBUTE_ELEMENT_NAME
Checks whether the object is of type
AttributeElement
and has the specifiedname
.Type parameters
N : extends string
Parameters
type : 'attributeElement' | 'view:attributeElement'
name : N
Returns
boolean
-
inherited
is( type ) → this is DocumentSelection
module:engine/view/textproxy~TextProxy#is:DOCUMENT_SELECTION
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
-
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
-
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 RootEditableElement
module:engine/view/textproxy~TextProxy#is:ROOT_ELEMENT
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
-
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
module:engine/view/textproxy~TextProxy#is:CONTAINER_ELEMENT
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 Text | Node | Element | AttributeElement | ContainerElement | EditableElement | EmptyElement | RawElement | RootEditableElement | UIElement
module:engine/view/textproxy~TextProxy#is:NODE
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 aNode
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:
orview:
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
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.