DocumentFragment (engine/model)
@ckeditor/ckeditor5-engine/src/model/documentfragment
DocumentFragment represents a part of model which does not have a common root but its top-level nodes can be seen as siblings. In other words, it is a detached part of model tree, without a root.
DocumentFragment has own MarkerCollection
. Markers from this collection
will be set to the model markers by a
insert
function.
Filtering
Properties
-
Number of this document fragment's children.
-
Artificial owner of
DocumentFragment
. Returnsnull
. Added for compatibility reasons. -
Is
true
if there are no nodes inside this document fragment,false
otherwise. -
DocumentFragment static markers map. This is a list of names and ranges which will be set as Markers to model markers collection when DocumentFragment will be inserted to the document.
-
Sum of offset sizes of all of this document fragment's children.
-
name : undefined
module:engine/model/documentfragment~DocumentFragment#name
Artificial element name. Returns
undefined
. Added for compatibility reasons. -
Artificial next sibling. Returns
null
. Added for compatibility reasons. -
Artificial parent of
DocumentFragment
. Returnsnull
. Added for compatibility reasons. -
readonly
previousSibling : null
module:engine/model/documentfragment~DocumentFragment#previousSibling
Artificial previous sibling. Returns
null
. Added for compatibility reasons. -
Artificial root of
DocumentFragment
. Returns itself. Added for compatibility reasons. -
rootName : undefined
module:engine/model/documentfragment~DocumentFragment#rootName
Artificial root name. Returns
undefined
. Added for compatibility reasons. -
private readonly
_children : NodeList
module:engine/model/documentfragment~DocumentFragment#_children
List of nodes contained inside the document fragment.
Methods
-
internal
constructor( [ children ] )
module:engine/model/documentfragment~DocumentFragment#constructor
Creates an empty
DocumentFragment
.Note: Constructor of this class shouldn't be used directly in the code. Use the
createDocumentFragment
method instead.Parameters
-
Symbol.iterator() → IterableIterator<Node>
module:engine/model/documentfragment~DocumentFragment#Symbol.iterator
Returns an iterator that iterates over all nodes contained inside this document fragment.
Returns
IterableIterator<Node>
-
getAncestors() → Array<never>
module:engine/model/documentfragment~DocumentFragment#getAncestors
-
Gets the child at the given index. Returns
null
if incorrect index was passed.Parameters
index : number
Index in this document fragment.
Returns
null | Node
Child node.
-
getChildAtOffset( offset ) → null | Node
module:engine/model/documentfragment~DocumentFragment#getChildAtOffset
Gets the child at the given offset. Returns
null
if incorrect index was passed.Parameters
offset : number
Offset in this document fragment.
Returns
null | Node
Child node.
-
getChildIndex( node ) → null | number
module:engine/model/documentfragment~DocumentFragment#getChildIndex
Returns an index of the given child node. Returns
null
if given node is not a child of this document fragment.Parameters
node : Node
Child node to look for.
Returns
null | number
Child node's index.
-
getChildStartOffset( node ) → null | number
module:engine/model/documentfragment~DocumentFragment#getChildStartOffset
Returns the starting offset of given child. Starting offset is equal to the sum of offset sizes of all node's siblings that are before it. Returns
null
if given node is not a child of this document fragment.Parameters
node : Node
Child node to look for.
Returns
null | number
Child node's starting offset.
-
getChildren() → IterableIterator<Node>
module:engine/model/documentfragment~DocumentFragment#getChildren
Returns an iterator that iterates over all of this document fragment's children.
Returns
IterableIterator<Node>
-
getNodeByPath( relativePath ) → Node | DocumentFragment
module:engine/model/documentfragment~DocumentFragment#getNodeByPath
Returns a descendant node by its path relative to this element.
// <this>a<b>c</b></this> this.getNodeByPath( [ 0 ] ); // -> "a" this.getNodeByPath( [ 1 ] ); // -> <b> this.getNodeByPath( [ 1, 0 ] ); // -> "c"
Parameters
relativePath : Array<number>
Path of the node to find, relative to this element.
Returns
-
getPath() → Array<number>
module:engine/model/documentfragment~DocumentFragment#getPath
Returns path to a
DocumentFragment
, which is an empty array. Added for compatibility reasons.Returns
Array<number>
-
inherited
is( type ) → this is Element | RootElement
module:engine/model/documentfragment~DocumentFragment#is:ELEMENT
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
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 Position | LivePosition
module:engine/model/documentfragment~DocumentFragment#is:POSITION
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 RootElement
module:engine/model/documentfragment~DocumentFragment#is:ROOT_ELEMENT
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 LiveRange
module:engine/model/documentfragment~DocumentFragment#is:LIVE_RANGE
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 Marker
module:engine/model/documentfragment~DocumentFragment#is:MARKER
-
inherited
is( type ) → this is TextProxy
module:engine/model/documentfragment~DocumentFragment#is:TEXT_PROXY
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
module:engine/model/documentfragment~DocumentFragment#is:DOCUMENT_SELECTION
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 Selection | DocumentSelection
module:engine/model/documentfragment~DocumentFragment#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
-
inherited
is( type ) → this is DocumentFragment
module:engine/model/documentfragment~DocumentFragment#is:DOCUMENT_FRAGMENT
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 Range | LiveRange
module:engine/model/documentfragment~DocumentFragment#is:RANGE
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
-
inherited
is( type ) → this is LivePosition
module:engine/model/documentfragment~DocumentFragment#is:LIVE_POSITION
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, name ) → boolean
module:engine/model/documentfragment~DocumentFragment#is:ELEMENT_NAME
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
-
inherited
is( type, name ) → boolean
module:engine/model/documentfragment~DocumentFragment#is:ROOT_ELEMENT_NAME
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/documentfragment~DocumentFragment#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
-
isAttached() → false
module:engine/model/documentfragment~DocumentFragment#isAttached
Returns
false
asDocumentFragment
by definition is not attached to a document. Added for compatibility reasons.Returns
false
-
offsetToIndex( offset ) → number
module:engine/model/documentfragment~DocumentFragment#offsetToIndex
Converts offset "position" to index "position".
Returns index of a node that occupies given offset. If given offset is too low, returns
0
. If given offset is too high, returns index after last child.const textNode = new Text( 'foo' ); const pElement = new Element( 'p' ); const docFrag = new DocumentFragment( [ textNode, pElement ] ); docFrag.offsetToIndex( -1 ); // Returns 0, because offset is too low. docFrag.offsetToIndex( 0 ); // Returns 0, because offset 0 is taken by `textNode` which is at index 0. docFrag.offsetToIndex( 1 ); // Returns 0, because `textNode` has `offsetSize` equal to 3, so it occupies offset 1 too. docFrag.offsetToIndex( 2 ); // Returns 0. docFrag.offsetToIndex( 3 ); // Returns 1. docFrag.offsetToIndex( 4 ); // Returns 2. There are no nodes at offset 4, so last available index is returned.
Parameters
offset : number
Offset to look for.
Returns
number
Index of a node that occupies given offset.
-
toJSON() → unknown
module:engine/model/documentfragment~DocumentFragment#toJSON
Converts
DocumentFragment
instance to plain object and returns it. Takes care of converting all of this document fragment's children.Returns
unknown
DocumentFragment
instance converted to plain object.
-
internal
_appendChild( items ) → void
module:engine/model/documentfragment~DocumentFragment#_appendChild
-
internal
_insertChild( index, items ) → void
module:engine/model/documentfragment~DocumentFragment#_insertChild
-
internal
_removeChildren( index, howMany ) → Array<Node>
module:engine/model/documentfragment~DocumentFragment#_removeChildren
Static methods
-
static
fromJSON( json ) → DocumentFragment
module:engine/model/documentfragment~DocumentFragment.fromJSON
Creates a
DocumentFragment
instance from given plain object (i.e. parsed JSON string). ConvertsDocumentFragment
children to proper nodes.Parameters
json : any
Plain object to be converted to
DocumentFragment
.
Returns
DocumentFragment
DocumentFragment
instance 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.