documentfragment.js 5.3 KB

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