documentfragment.js 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module engine/view/documentfragment
  7. */
  8. import Text from './text';
  9. import TextProxy from './textproxy';
  10. import mix from '@ckeditor/ckeditor5-utils/src/mix';
  11. import isIterable from '@ckeditor/ckeditor5-utils/src/isiterable';
  12. import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
  13. /**
  14. * Document fragment.
  15. *
  16. * To create a new document fragment instance use the
  17. * {@link module:engine/view/upcastwriter~UpcastWriter#createDocumentFragment `UpcastWriter#createDocumentFragment()`}
  18. * method.
  19. */
  20. export default class DocumentFragment {
  21. /**
  22. * Creates new DocumentFragment instance.
  23. *
  24. * @protected
  25. * @param {module:engine/view/document~Document} document The document to which this document fragment belongs.
  26. * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
  27. * A list of nodes to be inserted into the created document fragment.
  28. */
  29. constructor( document, children ) {
  30. /**
  31. * The document to which this document fragment belongs.
  32. *
  33. * @readonly
  34. * @member {module:engine/view/document~Document}
  35. */
  36. this.document = document;
  37. /**
  38. * Array of child nodes.
  39. *
  40. * @protected
  41. * @member {Array.<module:engine/view/element~Element>} module:engine/view/documentfragment~DocumentFragment#_children
  42. */
  43. this._children = [];
  44. if ( children ) {
  45. this._insertChild( 0, children );
  46. }
  47. }
  48. /**
  49. * Iterable interface.
  50. *
  51. * Iterates over nodes added to this document fragment.
  52. *
  53. * @returns {Iterable.<module:engine/view/node~Node>}
  54. */
  55. [ Symbol.iterator ]() {
  56. return this._children[ Symbol.iterator ]();
  57. }
  58. /**
  59. * Number of child nodes in this document fragment.
  60. *
  61. * @readonly
  62. * @type {Number}
  63. */
  64. get childCount() {
  65. return this._children.length;
  66. }
  67. /**
  68. * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
  69. *
  70. * @readonly
  71. * @type {Boolean}
  72. */
  73. get isEmpty() {
  74. return this.childCount === 0;
  75. }
  76. /**
  77. * Artificial root of `DocumentFragment`. Returns itself. Added for compatibility reasons.
  78. *
  79. * @readonly
  80. * @type {module:engine/model/documentfragment~DocumentFragment}
  81. */
  82. get root() {
  83. return this;
  84. }
  85. /**
  86. * Artificial parent of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
  87. *
  88. * @readonly
  89. * @type {null}
  90. */
  91. get parent() {
  92. return null;
  93. }
  94. /**
  95. * Checks whether this object is of the given type.
  96. *
  97. * docFrag.is( 'documentFragment' ); // -> true
  98. * docFrag.is( 'view:documentFragment' ); // -> true
  99. *
  100. * docFrag.is( 'model:documentFragment' ); // -> false
  101. * docFrag.is( 'element' ); // -> false
  102. * docFrag.is( 'node' ); // -> false
  103. *
  104. * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
  105. *
  106. * @param {String} type
  107. * @returns {Boolean}
  108. */
  109. is( type ) {
  110. return type === 'documentFragment' || type === 'view:documentFragment';
  111. }
  112. /**
  113. * {@link module:engine/view/documentfragment~DocumentFragment#_insertChild Insert} a child node or a list of child nodes at the end
  114. * and sets the parent of these nodes to this fragment.
  115. *
  116. * @param {module:engine/view/item~Item|Iterable.<module:engine/view/item~Item>} items Items to be inserted.
  117. * @returns {Number} Number of appended nodes.
  118. */
  119. _appendChild( items ) {
  120. return this._insertChild( this.childCount, items );
  121. }
  122. /**
  123. * Gets child at the given index.
  124. *
  125. * @param {Number} index Index of child.
  126. * @returns {module:engine/view/node~Node} Child node.
  127. */
  128. getChild( index ) {
  129. return this._children[ index ];
  130. }
  131. /**
  132. * Gets index of the given child node. Returns `-1` if child node is not found.
  133. *
  134. * @param {module:engine/view/node~Node} node Child node.
  135. * @returns {Number} Index of the child node.
  136. */
  137. getChildIndex( node ) {
  138. return this._children.indexOf( node );
  139. }
  140. /**
  141. * Gets child nodes iterator.
  142. *
  143. * @returns {Iterable.<module:engine/view/node~Node>} Child nodes iterator.
  144. */
  145. getChildren() {
  146. return this._children[ Symbol.iterator ]();
  147. }
  148. /**
  149. * Inserts a child node or a list of child nodes on the given index and sets the parent of these nodes to
  150. * this fragment.
  151. *
  152. * @param {Number} index Position where nodes should be inserted.
  153. * @param {module:engine/view/item~Item|Iterable.<module:engine/view/item~Item>} items Items to be inserted.
  154. * @returns {Number} Number of inserted nodes.
  155. */
  156. _insertChild( index, items ) {
  157. this._fireChange( 'children', this );
  158. let count = 0;
  159. const nodes = normalize( this.document, items );
  160. for ( const node of nodes ) {
  161. // If node that is being added to this element is already inside another element, first remove it from the old parent.
  162. if ( node.parent !== null ) {
  163. node._remove();
  164. }
  165. node.parent = this;
  166. this._children.splice( index, 0, node );
  167. index++;
  168. count++;
  169. }
  170. return count;
  171. }
  172. /**
  173. * Removes number of child nodes starting at the given index and set the parent of these nodes to `null`.
  174. *
  175. * @param {Number} index Number of the first node to remove.
  176. * @param {Number} [howMany=1] Number of nodes to remove.
  177. * @returns {Array.<module:engine/view/node~Node>} The array of removed nodes.
  178. */
  179. _removeChildren( index, howMany = 1 ) {
  180. this._fireChange( 'children', this );
  181. for ( let i = index; i < index + howMany; i++ ) {
  182. this._children[ i ].parent = null;
  183. }
  184. return this._children.splice( index, howMany );
  185. }
  186. /**
  187. * Fires `change` event with given type of the change.
  188. *
  189. * @private
  190. * @param {module:engine/view/document~ChangeType} type Type of the change.
  191. * @param {module:engine/view/node~Node} node Changed node.
  192. * @fires module:engine/view/node~Node#change
  193. */
  194. _fireChange( type, node ) {
  195. this.fire( 'change:' + type, node );
  196. }
  197. // @if CK_DEBUG_ENGINE // printTree() {
  198. // @if CK_DEBUG_ENGINE // let string = 'ViewDocumentFragment: [';
  199. // @if CK_DEBUG_ENGINE // for ( const child of this.getChildren() ) {
  200. // @if CK_DEBUG_ENGINE // if ( child.is( 'text' ) ) {
  201. // @if CK_DEBUG_ENGINE // string += '\n' + '\t'.repeat( 1 ) + child.data;
  202. // @if CK_DEBUG_ENGINE // } else {
  203. // @if CK_DEBUG_ENGINE // string += '\n' + child.printTree( 1 );
  204. // @if CK_DEBUG_ENGINE // }
  205. // @if CK_DEBUG_ENGINE // }
  206. // @if CK_DEBUG_ENGINE // string += '\n]';
  207. // @if CK_DEBUG_ENGINE // return string;
  208. // @if CK_DEBUG_ENGINE // }
  209. // @if CK_DEBUG_ENGINE // logTree() {
  210. // @if CK_DEBUG_ENGINE // console.log( this.printTree() );
  211. // @if CK_DEBUG_ENGINE // }
  212. }
  213. mix( DocumentFragment, EmitterMixin );
  214. // Converts strings to Text and non-iterables to arrays.
  215. //
  216. // @param {String|module:engine/view/item~Item|Iterable.<String|module:engine/view/item~Item>}
  217. // @returns {Iterable.<module:engine/view/node~Node>}
  218. function normalize( document, nodes ) {
  219. // Separate condition because string is iterable.
  220. if ( typeof nodes == 'string' ) {
  221. return [ new Text( document, nodes ) ];
  222. }
  223. if ( !isIterable( nodes ) ) {
  224. nodes = [ nodes ];
  225. }
  226. // Array.from to enable .map() on non-arrays.
  227. return Array.from( nodes )
  228. .map( node => {
  229. if ( typeof node == 'string' ) {
  230. return new Text( document, node );
  231. }
  232. if ( node instanceof TextProxy ) {
  233. return new Text( document, node.data );
  234. }
  235. return node;
  236. } );
  237. }