8
0

documentfragment.js 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237
  1. /**
  2. * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  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/node~Node|Iterable.<module:engine/view/node~Node>} [children]
  26. * A list of nodes to be inserted into the created document fragment.
  27. */
  28. constructor( children ) {
  29. /**
  30. * Array of child nodes.
  31. *
  32. * @protected
  33. * @member {Array.<module:engine/view/element~Element>} module:engine/view/documentfragment~DocumentFragment#_children
  34. */
  35. this._children = [];
  36. if ( children ) {
  37. this._insertChild( 0, children );
  38. }
  39. }
  40. /**
  41. * Iterable interface.
  42. *
  43. * Iterates over nodes added to this document fragment.
  44. *
  45. * @returns {Iterable.<module:engine/view/node~Node>}
  46. */
  47. [ Symbol.iterator ]() {
  48. return this._children[ Symbol.iterator ]();
  49. }
  50. /**
  51. * Number of child nodes in this document fragment.
  52. *
  53. * @readonly
  54. * @type {Number}
  55. */
  56. get childCount() {
  57. return this._children.length;
  58. }
  59. /**
  60. * Is `true` if there are no nodes inside this document fragment, `false` otherwise.
  61. *
  62. * @readonly
  63. * @type {Boolean}
  64. */
  65. get isEmpty() {
  66. return this.childCount === 0;
  67. }
  68. /**
  69. * Artificial root of `DocumentFragment`. Returns itself. Added for compatibility reasons.
  70. *
  71. * @readonly
  72. * @type {module:engine/model/documentfragment~DocumentFragment}
  73. */
  74. get root() {
  75. return this;
  76. }
  77. /**
  78. * Artificial parent of `DocumentFragment`. Returns `null`. Added for compatibility reasons.
  79. *
  80. * @readonly
  81. * @type {null}
  82. */
  83. get parent() {
  84. return null;
  85. }
  86. /**
  87. * Checks whether given view tree object is of given type.
  88. *
  89. * Read more in {@link module:engine/view/node~Node#is}.
  90. *
  91. * @param {String} type
  92. * @returns {Boolean}
  93. */
  94. is( type ) {
  95. return type == 'documentFragment';
  96. }
  97. /**
  98. * {@link module:engine/view/documentfragment~DocumentFragment#_insertChild Insert} a child node or a list of child nodes at the end
  99. * and sets the parent of these nodes to this fragment.
  100. *
  101. * @param {module:engine/view/item~Item|Iterable.<module:engine/view/item~Item>} items Items to be inserted.
  102. * @returns {Number} Number of appended nodes.
  103. */
  104. _appendChild( items ) {
  105. return this._insertChild( this.childCount, items );
  106. }
  107. /**
  108. * Gets child at the given index.
  109. *
  110. * @param {Number} index Index of child.
  111. * @returns {module:engine/view/node~Node} Child node.
  112. */
  113. getChild( index ) {
  114. return this._children[ index ];
  115. }
  116. /**
  117. * Gets index of the given child node. Returns `-1` if child node is not found.
  118. *
  119. * @param {module:engine/view/node~Node} node Child node.
  120. * @returns {Number} Index of the child node.
  121. */
  122. getChildIndex( node ) {
  123. return this._children.indexOf( node );
  124. }
  125. /**
  126. * Gets child nodes iterator.
  127. *
  128. * @returns {Iterable.<module:engine/view/node~Node>} Child nodes iterator.
  129. */
  130. getChildren() {
  131. return this._children[ Symbol.iterator ]();
  132. }
  133. /**
  134. * Inserts a child node or a list of child nodes on the given index and sets the parent of these nodes to
  135. * this fragment.
  136. *
  137. * @param {Number} index Position where nodes should be inserted.
  138. * @param {module:engine/view/item~Item|Iterable.<module:engine/view/item~Item>} items Items to be inserted.
  139. * @returns {Number} Number of inserted nodes.
  140. */
  141. _insertChild( index, items ) {
  142. this._fireChange( 'children', this );
  143. let count = 0;
  144. const nodes = normalize( items );
  145. for ( const node of nodes ) {
  146. // If node that is being added to this element is already inside another element, first remove it from the old parent.
  147. if ( node.parent !== null ) {
  148. node._remove();
  149. }
  150. node.parent = this;
  151. this._children.splice( index, 0, node );
  152. index++;
  153. count++;
  154. }
  155. return count;
  156. }
  157. /**
  158. * Removes number of child nodes starting at the given index and set the parent of these nodes to `null`.
  159. *
  160. * @param {Number} index Number of the first node to remove.
  161. * @param {Number} [howMany=1] Number of nodes to remove.
  162. * @returns {Array.<module:engine/view/node~Node>} The array of removed nodes.
  163. */
  164. _removeChildren( index, howMany = 1 ) {
  165. this._fireChange( 'children', this );
  166. for ( let i = index; i < index + howMany; i++ ) {
  167. this._children[ i ].parent = null;
  168. }
  169. return this._children.splice( index, howMany );
  170. }
  171. /**
  172. * Fires `change` event with given type of the change.
  173. *
  174. * @private
  175. * @param {module:engine/view/document~ChangeType} type Type of the change.
  176. * @param {module:engine/view/node~Node} node Changed node.
  177. * @fires module:engine/view/node~Node#change
  178. */
  179. _fireChange( type, node ) {
  180. this.fire( 'change:' + type, node );
  181. }
  182. }
  183. mix( DocumentFragment, EmitterMixin );
  184. // Converts strings to Text and non-iterables to arrays.
  185. //
  186. // @param {String|module:engine/view/item~Item|Iterable.<String|module:engine/view/item~Item>}
  187. // @returns {Iterable.<module:engine/view/node~Node>}
  188. function normalize( nodes ) {
  189. // Separate condition because string is iterable.
  190. if ( typeof nodes == 'string' ) {
  191. return [ new Text( nodes ) ];
  192. }
  193. if ( !isIterable( nodes ) ) {
  194. nodes = [ nodes ];
  195. }
  196. // Array.from to enable .map() on non-arrays.
  197. return Array.from( nodes )
  198. .map( node => {
  199. if ( typeof node == 'string' ) {
  200. return new Text( node );
  201. }
  202. if ( node instanceof TextProxy ) {
  203. return new Text( node.data );
  204. }
  205. return node;
  206. } );
  207. }