Node (engine/model)
@ckeditor/ckeditor5-engine/src/model/node
Model node. Most basic structure of model tree.
This is an abstract class that is a base for other classes representing different nodes in model.
Note: If a node is detached from the model tree, you can manipulate it using it's API. However, it is very important that nodes already attached to model tree should be only changed through Writer API.
Changes done by Node
methods, like _insertChild or
_setAttribute
do not generate operations
which are essential for correct editor work if you modify nodes in document root.
The flow of working on Node
(and classes that inherits from it) is as such:
- You can create a
Node
instance, modify it using it's API. - Add
Node
to the model usingBatch
API. - Change
Node
that was already added to the model usingBatch
API.
Similarly, you cannot use Batch
API on a node that has not been added to the model tree, with the exception
of inserting that node to the model tree.
Be aware that using remove from Batch API does not allow to use Node
API because
the information about Node
is still kept in model document.
In case of element node, adding and removing children also counts as changing a node and follows same rules.
Filtering
Properties
-
Document that owns this root element.
-
Offset at which this node ends in it's parent. It is equal to the sum of this node's start offset and offset size. Equals to
null
if the node has no parent. -
Index of this node in its parent or
null
if the node has no parent.Accessing this property throws an error if this node's parent element does not contain it. This means that model tree got broken.
-
Node's next sibling or
null
if 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 it's parent. It is important for position. When node has
offsetSize
greater than1
, position can be placed between that node start and end.offsetSize
greater than1
is for nodes that represents more than one entity, i.e. text node. -
Parent of this node. It could be
Element
orDocumentFragment
. Equals tonull
if the node has no parent. -
Node's previous sibling or
null
if 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'sroot
is 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
null
if node has no parent.Accessing this property throws an error if this node's parent element does not contain it. This means that model tree got broken.
-
Attributes set on this node.
Methods
-
constructor( [ attrs ] )
module:engine/model/node~Node#constructor
Creates a model node.
This is an abstract class, so this constructor should not be used directly.
Parameters
[ attrs ] : NodeAttributes
Node's attributes. See
toMap
for a list of accepted values.
-
getAncestors( options = { [options.includeSelf], [options.parentFirst] } ) → Array<Node | DocumentFragment>
module:engine/model/node~Node#getAncestors
Returns ancestors array of this node.
Parameters
options : object
Options object.
Properties[ options.includeSelf ] : boolean
When set to
true
this node will be also included in parent's array.[ options.parentFirst ] : boolean
When 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.
-
getAttribute( key ) → unknown
module:engine/model/node~Node#getAttribute
Gets an attribute value for given key or
undefined
if that attribute is not set on node.Parameters
key : string
Key of attribute to look for.
Returns
unknown
Attribute value or
undefined
.
-
getAttributeKeys() → IterableIterator<string>
module:engine/model/node~Node#getAttributeKeys
Returns iterator that iterates over this node's attribute keys.
Returns
IterableIterator<string>
-
getAttributes() → IterableIterator<tuple>
module:engine/model/node~Node#getAttributes
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 inNode
constructor.Returns
IterableIterator<tuple>
-
getCommonAncestor( node, options = { [options.includeSelf] } ) → null | Element | DocumentFragment
module:engine/model/node~Node#getCommonAncestor
Returns a
Element
orDocumentFragment
which is a common ancestor of both nodes.Parameters
node : Node
The second node.
options : object
Options object.
Properties[ options.includeSelf ] : boolean
When set to
true
both 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
-
getPath() → Array<number>
module:engine/model/node~Node#getPath
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>
-
hasAttribute( key ) → boolean
module:engine/model/node~Node#hasAttribute
Checks if the node has an attribute with given key.
Parameters
key : string
Key of attribute to check.
Returns
boolean
true
if attribute with given key is set on node,false
otherwise.
-
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
-
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
-
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
-
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
-
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
-
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
-
Checks whether the object is of type
Element
or its subclass and has the specifiedname
.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
-
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 Selection | DocumentSelection
module:engine/model/node~Node#is:SELECTION
Checks whether the object is of type
Selection
orDocumentSelection
.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
-
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
-
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
-
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
-
Checks whether the object is of type
RootElement
and 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 | RootElement
module:engine/model/node~Node#is:NODE
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 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 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' ); // -> 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
-
isAfter( node ) → boolean
module:engine/model/node~Node#isAfter
Returns whether this node is after given node.
false
is returned if nodes are in different trees (for example, in differentDocumentFragment
s).Parameters
node : Node
Node to compare with.
Returns
boolean
-
isAttached() → boolean
module:engine/model/node~Node#isAttached
Returns
true
if the node is inside a document root that is attached to the document.Returns
boolean
-
isBefore( node ) → boolean
module:engine/model/node~Node#isBefore
Returns whether this node is before given node.
false
is returned if nodes are in different trees (for example, in differentDocumentFragment
s).Parameters
node : Node
Node to compare with.
Returns
boolean
-
toJSON() → unknown
module:engine/model/node~Node#toJSON
Converts
Node
to plain object and returns it.Returns
unknown
Node
converted to plain object.
-
-
Creates a copy of this node, that is a node with exactly same attributes, and returns it.
Parameters
[ _deep ] : boolean
Returns
Node
Node with same attributes as this node.
-
-
Removes an attribute with given key from the node.
Parameters
key : string
Key of attribute to remove.
Returns
boolean
true
if the attribute was set on the element,false
otherwise.
Related:
-
Sets attribute on the node. If attribute with the same key already is set, it's value is overwritten.
Parameters
key : string
Key of attribute to set.
value : unknown
Attribute value.
Returns
void
Related:
-
Removes all attributes from the node and sets given attributes.
Parameters
attrs : NodeAttributes
Attributes to set. See
toMap
for a list of accepted values.
Returns
void
Related:
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.