documentfragment.js 5.7 KB

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