Text (engine/model)
@ckeditor/ckeditor5-engine/src/model/text
Model text node. Type of node that contains text data.
Important: see Node to read about restrictions using Text and Node API.
Note: keep in mind that Text instances might indirectly got removed from model tree when model is changed.
This happens when model writer is used to change model and the text node is merged with
another text node. Then, both text nodes are removed and a new text node is inserted into the model. Because of
this behavior, keeping references to Text is not recommended. Instead, consider creating
live position placed before the text node.
Filtering
Properties
-
Returns a text data contained in the node.
-
Document that owns this root element.
-
Offset at which this node ends in its parent. It is equal to the sum of this node's start offset and offset size. Equals to
nullif the node has no parent. -
Index of this node in its parent or
nullif the node has no parent. -
Node's next sibling or
nullif the node is a last child of it's parent or if the node has no parent. -
Offset size of this node.
Represents how much "offset space" is occupied by the node in its parent. It is important for position. When node has
offsetSizegreater than1, position can be placed between that node start and end.offsetSizegreater than1is for nodes that represents more than one entity, i.e. a text node. -
Parent of this node. It could be
ElementorDocumentFragment. Equals tonullif the node has no parent. -
Node's previous sibling or
nullif the node is a first child of it's parent or if the node has no parent. -
The top-most ancestor of the node. If node has no parent it is the root itself. If the node is a part of
DocumentFragment, it'srootis equal to thatDocumentFragment. -
Unique root name used to identify this root element by
Document. -
Offset at which this node starts in its parent. It is equal to the sum of offsetSize of all its previous siblings. Equals to
nullif node has no parent. -
Text data contained in this text node.
-
Index of this node in its parent or
nullif the node has no parent. -
Offset at which this node starts in its parent or
nullif the node has no parent.
Methods
-
Creates a text node.
Note: Constructor of this class shouldn't be used directly in the code. Use the
createTextmethod instead.Parameters
[ data ] : stringNode's text.
[ attrs ] : NodeAttributesNode's attributes. See
toMapfor a list of accepted values.
-
inherited
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<Node | DocumentFragment>module:engine/model/text~Text#getAncestorsReturns ancestors array of this node.
Parameters
options : objectOptions object.
Properties[ options.includeSelf ] : booleanWhen set to
truethis node will be also included in parent's array.[ options.parentFirst ] : booleanWhen set to
true, array will be sorted from node's parent to root element, otherwise root element will be the first item in the array.
Defaults to
{}
Returns
Array<Node | DocumentFragment>Array with ancestors.
-
Gets an attribute value for given key or
undefinedif that attribute is not set on node.Parameters
key : stringKey of attribute to look for.
Returns
unknownAttribute value or
undefined.
-
inherited
getAttributeKeys() → IterableIterator<string>module:engine/model/text~Text#getAttributeKeysReturns iterator that iterates over this node's attribute keys.
Returns
IterableIterator<string>
-
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
Mapobject and also can be passed inNodeconstructor.Returns
IterableIterator<tuple>
-
inherited
getCommonAncestor( node, options = { [options.includeSelf] } ) → null | Element | DocumentFragmentmodule:engine/model/text~Text#getCommonAncestorReturns a
ElementorDocumentFragmentwhich is a common ancestor of both nodes.Parameters
node : NodeThe second node.
options : objectOptions object.
Properties[ options.includeSelf ] : booleanWhen set to
trueboth nodes will be considered "ancestors" too. Which means that if e.g. node A is inside B, then their common ancestor will be B.
Defaults to
{}
Returns
null | Element | DocumentFragment
-
Gets path to the node. The path is an array containing starting offsets of consecutive ancestors of this node, beginning from root, down to this node's starting offset. The path can be used to create Position instance.
const abc = new Text( 'abc' ); const foo = new Text( 'foo' ); const h1 = new Element( 'h1', null, new Text( 'header' ) ); const p = new Element( 'p', null, [ abc, foo ] ); const div = new Element( 'div', null, [ h1, p ] ); foo.getPath(); // Returns [ 1, 3 ]. `foo` is in `p` which is in `div`. `p` starts at offset 1, while `foo` at 3. h1.getPath(); // Returns [ 0 ]. div.getPath(); // Returns [].Returns
Array<number>
-
Checks if the node has an attribute with given key.
Parameters
key : stringKey of attribute to check.
Returns
booleantrueif attribute with given key is set on node,falseotherwise.
-
Checks whether the object is of type
Elementor 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' ); // -> falseAssuming 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' ); -> falseParameters
type : 'element' | 'model:element'
Returns
this is Element | 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' ); // -> falseAssuming that the object being checked is an element, you can also check its name:
rootElement.is( 'rootElement', '$root' ); // -> same as aboveParameters
type : 'rootElement' | 'model:rootElement'
Returns
this is RootElement
-
Checks whether the object is of type
Positionor its subclass.position.is( 'position' ); // -> true position.is( 'model:position' ); // -> true position.is( 'view:position' ); // -> false position.is( 'documentSelection' ); // -> falseParameters
type : 'position' | 'model:position'
Returns
this is Position | LivePosition
-
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' ); // -> falseNote: 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
-
Checks whether the object is of type
Rangeor its subclass.range.is( 'range' ); // -> true range.is( 'model:range' ); // -> true range.is( 'view:range' ); // -> false range.is( 'documentSelection' ); // -> falseParameters
type : 'range' | 'model:range'
Returns
-
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' ); // -> falseParameters
type : 'documentSelection' | 'model:documentSelection'
Returns
this is DocumentSelection
-
Checks whether the object is of type
Elementor its subclass and has the specifiedname.element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element text.is( 'element', 'imageBlock' ); -> falseType parameters
N : extends string
Parameters
type : 'element' | 'model:element'name : N
Returns
boolean
-
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' ); // -> falseNote: 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 Selection | DocumentSelectionmodule:engine/model/text~Text#is:SELECTIONChecks whether the object is of type
SelectionorDocumentSelection.selection.is( 'selection' ); // -> true selection.is( 'model:selection' ); // -> true selection.is( 'view:selection' ); // -> false selection.is( 'range' ); // -> falseParameters
type : 'selection' | 'model:selection'
Returns
this is Selection | DocumentSelection
-
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' ); // -> falseParameters
type : 'documentFragment' | 'model:documentFragment'
Returns
this is DocumentFragment
-
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' ); // -> falseParameters
type : 'liveRange' | 'model:liveRange'
Returns
this is LiveRange
-
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' ); // -> falseParameters
type : 'livePosition' | 'model:livePosition'
Returns
this is LivePosition
-
Checks whether the object is of type
RootElementand has the specifiedname.rootElement.is( 'rootElement', '$root' );Type parameters
N : extends string
Parameters
type : 'rootElement' | 'model:rootElement'name : N
Returns
boolean
-
inherited
is( type ) → this is Node | Text | Element | RootElementmodule:engine/model/text~Text#is:NODEChecks whether the object is of type
Nodeor its subclass.This method is useful when processing model objects that are of unknown type. For example, a function may return a
DocumentFragmentor aNodethat 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 fragmentSince this method is also available on a range of view 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:modelElement.is( 'model:element' ); // -> true modelElement.is( 'view:element' ); // -> falseBy 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 preciseParameters
type : 'node' | 'model:node'
Returns
this is Node | Text | Element | RootElement
-
Returns whether this node is after given node.
falseis returned if nodes are in different trees (for example, in differentDocumentFragments).Parameters
node : NodeNode to compare with.
Returns
boolean
-
Returns
trueif the node is inside a document root that is attached to the document.Returns
boolean
-
Returns whether this node is before given node.
falseis returned if nodes are in different trees (for example, in differentDocumentFragments).Parameters
node : NodeNode to compare with.
Returns
boolean
-
toJSON() → unknownmodule:engine/model/text~Text#toJSONConverts
Textinstance to plain object and returns it.@returns
Textinstance converted to plain object.Returns
unknown
-
-
Creates a copy of this text node and returns it. Created text node has same text data and attributes as original text node.
Returns
TextTextinstance created using given plain object.
-
-
Removes an attribute with given key from the node.
Parameters
key : stringKey of attribute to remove.
Returns
booleantrueif the attribute was set on the element,falseotherwise.
Related:
-
Sets attribute on the node. If attribute with the same key already is set, it's value is overwritten.
Parameters
key : stringKey of attribute to set.
value : unknownAttribute value.
Returns
void
Related:
-
Removes all attributes from the node and sets given attributes.
Parameters
attrs : NodeAttributesAttributes to set. See
toMapfor a list of accepted values.
Returns
void
Related:
Static methods
-
Creates a
Textinstance from given plain object (i.e. parsed JSON string).Parameters
json : anyPlain object to be converted to
Text.
Returns
TextTextinstance created using given plain object.
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.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.