tablewalker.js 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399
  1. /**
  2. * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module table/tablewalker
  7. */
  8. /**
  9. * Table iterator class. It allows to iterate over table cells. For each cell the iterator yields
  10. * {@link module:table/tablewalker~TableWalkerValue} with proper table cell attributes.
  11. */
  12. export default class TableWalker {
  13. /**
  14. * Creates an instance of the table walker.
  15. *
  16. * The table walker iterates internally by traversing the table from row index = 0 and column index = 0.
  17. * It walks row by row and column by column in order to output values defined in the constructor.
  18. * By default it will output only those locations that are occupied by a cell. To include also spanned rows and columns,
  19. * pass the `includeSpanned` option to the constructor.
  20. *
  21. * The most important values of the iterator are column and row indexes of a cell.
  22. *
  23. * See {@link module:table/tablewalker~TableWalkerValue} what values are returned by the table walker.
  24. *
  25. * To iterate over a given row:
  26. *
  27. * const tableWalker = new TableWalker( table, { startRow: 1, endRow: 2 } );
  28. *
  29. * for ( const cellInfo of tableWalker ) {
  30. * console.log( 'A cell at row ' + cellInfo.row + ' and column ' + cellInfo.column );
  31. * }
  32. *
  33. * For instance the code above for the following table:
  34. *
  35. * +----+----+----+----+----+----+
  36. * | 00 | 02 | 03 | 04 | 05 |
  37. * | +----+----+----+----+
  38. * | | 12 | 14 | 15 |
  39. * | +----+----+----+ +
  40. * | | 22 | |
  41. * |----+----+----+----+----+ +
  42. * | 30 | 31 | 32 | 33 | 34 | |
  43. * +----+----+----+----+----+----+
  44. *
  45. * will log in the console:
  46. *
  47. * 'A cell at row 1 and column 2'
  48. * 'A cell at row 1 and column 4'
  49. * 'A cell at row 1 and column 5'
  50. * 'A cell at row 2 and column 2'
  51. *
  52. * To also iterate over spanned cells:
  53. *
  54. * const tableWalker = new TableWalker( table, { startRow: 1, endRow: 1, includeSpanned: true } );
  55. *
  56. * for ( const value of tableWalker ) {
  57. * console.log( 'Cell at ' + value.row + ' x ' + value.column + ' : ' + ( value.isSpanned ? 'is spanned' : 'has data' ) );
  58. * }
  59. *
  60. * will log in the console for the table from previous example:
  61. *
  62. * 'Cell at 1 x 0 : is spanned'
  63. * 'Cell at 1 x 1 : is spanned'
  64. * 'Cell at 1 x 2 : has data'
  65. * 'Cell at 1 x 3 : is spanned'
  66. * 'Cell at 1 x 4 : has data'
  67. * 'Cell at 1 x 5 : has data'
  68. *
  69. * @constructor
  70. * @param {module:engine/model/element~Element} table A table over which the walker iterates.
  71. * @param {Object} [options={}] An object with configuration.
  72. * @param {Number} [options.column] A column index for which this iterator will output cells.
  73. * @param {Number} [options.startRow=0] A row index for which this iterator should start.
  74. * @param {Number} [options.endRow] A row index for which this iterator should end.
  75. * @param {Boolean} [options.includeSpanned=false] Also return values for spanned cells.
  76. */
  77. constructor( table, options = {} ) {
  78. /**
  79. * The walker's table element.
  80. *
  81. * @readonly
  82. * @member {module:engine/model/element~Element}
  83. */
  84. this.table = table;
  85. /**
  86. * A row index on which this iterator will start.
  87. *
  88. * @readonly
  89. * @member {Number}
  90. */
  91. this.startRow = options.startRow || 0;
  92. /**
  93. * A row index on which this iterator will end.
  94. *
  95. * @readonly
  96. * @member {Number}
  97. */
  98. this.endRow = typeof options.endRow == 'number' ? options.endRow : undefined;
  99. /**
  100. * Enables output of spanned cells that are normally not yielded.
  101. *
  102. * @readonly
  103. * @member {Boolean}
  104. */
  105. this.includeSpanned = !!options.includeSpanned;
  106. /**
  107. * If set, the table walker will only output cells of a given column or cells that overlap it.
  108. *
  109. * @readonly
  110. * @member {Number}
  111. */
  112. this.column = typeof options.column == 'number' ? options.column : undefined;
  113. /**
  114. * Row indexes to skip from the iteration.
  115. *
  116. * @readonly
  117. * @member {Set<Number>}
  118. * @private
  119. */
  120. this._skipRows = new Set();
  121. /**
  122. * The current row index.
  123. *
  124. * @readonly
  125. * @member {Number}
  126. * @private
  127. */
  128. this._row = 0;
  129. /**
  130. * The current column index.
  131. *
  132. * @readonly
  133. * @member {Number}
  134. * @private
  135. */
  136. this._column = 0;
  137. /**
  138. * The cell index in a parent row. For spanned cells when {@link #includeSpanned} is set to `true`,
  139. * this represents the index of the next table cell.
  140. *
  141. * @readonly
  142. * @member {Number}
  143. * @private
  144. */
  145. this._cellIndex = 0;
  146. /**
  147. * Holds a map of spanned cells in a table.
  148. *
  149. * @readonly
  150. * @member {Map<Number, Map.<Number, module:engine/model/element~Element>>}
  151. * @private
  152. */
  153. this._spannedCells = new Map();
  154. this._nextCellAtColumn = -1;
  155. }
  156. /**
  157. * Iterable interface.
  158. *
  159. * @returns {Iterable.<module:table/tablewalker~TableWalkerValue>}
  160. */
  161. [ Symbol.iterator ]() {
  162. return this;
  163. }
  164. /**
  165. * Gets the next table walker's value.
  166. *
  167. * @returns {module:table/tablewalker~TableWalkerValue} The next table walker's value.
  168. */
  169. next() {
  170. const row = this.table.getChild( this._row );
  171. // Iterator is done when there's no row (table ended) or the row is after `endRow` limit.
  172. if ( !row || this._isOverEndRow() ) {
  173. return { done: true };
  174. }
  175. let cell, skipCurrentValue, outValue;
  176. if ( this._isSpanned( this._row, this._column ) ) {
  177. cell = this._getSpanned( this._row, this._column );
  178. skipCurrentValue = !this.includeSpanned || this._shouldSkipRow() || this._shouldSkipColumn();
  179. outValue = this._formatOutValue( cell, this._column, true );
  180. } else {
  181. cell = row.getChild( this._cellIndex );
  182. if ( !cell ) {
  183. // If there are no more cells left in row advance to the next row.
  184. this._row++;
  185. this._column = 0;
  186. this._cellIndex = 0;
  187. this._nextCellAtColumn = -1;
  188. return this.next();
  189. }
  190. const colspan = parseInt( cell.getAttribute( 'colspan' ) || 1 );
  191. const rowspan = parseInt( cell.getAttribute( 'rowspan' ) || 1 );
  192. // Record this cell spans if it's not 1x1 cell.
  193. if ( colspan > 1 || rowspan > 1 ) {
  194. this._recordSpans( this._row, this._column, rowspan, colspan, cell );
  195. }
  196. this._nextCellAtColumn = this._column + colspan;
  197. skipCurrentValue = this._shouldSkipRow() || this._shouldSkipColumn();
  198. outValue = this._formatOutValue( cell, this._column, false, rowspan, colspan );
  199. }
  200. // Advance to the next column before returning value.
  201. this._column++;
  202. if ( this._column == this._nextCellAtColumn ) {
  203. this._cellIndex++;
  204. }
  205. // The current value will be returned only if current row and column are not skipped.
  206. return skipCurrentValue ? this.next() : outValue;
  207. }
  208. /**
  209. * Marks a row to skip in the next iteration. It will also skip cells from the current row if there are any cells from the current row
  210. * to output.
  211. *
  212. * @param {Number} row Row index to skip.
  213. */
  214. skipRow( row ) {
  215. this._skipRows.add( row );
  216. }
  217. /**
  218. * Checks if the current row is over {@link #endRow}.
  219. *
  220. * @private
  221. * @returns {Boolean}
  222. */
  223. _isOverEndRow() {
  224. // If {@link #endRow) is defined skip all rows above it.
  225. return this.endRow !== undefined && this._row > this.endRow;
  226. }
  227. /**
  228. * A common method for formatting the iterator's output value.
  229. *
  230. * @private
  231. * @param {module:engine/model/element~Element} cell The table cell to output.
  232. * @param {Number} column Column index (use the cached value).
  233. * @param {Boolean} isSpanned Whether the value is returned for a spanned cell location or actual cell.
  234. * @param {Number} rowspan Rowspan of the current cell.
  235. * @param {Number} colspan Colspan of the current cell.
  236. * @returns {{done: boolean, value: {cell: *, row: Number, column: *, rowspan: *, colspan: *, cellIndex: Number}}}
  237. */
  238. _formatOutValue( cell, column, isSpanned, rowspan = 1, colspan = 1 ) {
  239. return {
  240. done: false,
  241. value: {
  242. cell,
  243. row: this._row,
  244. column,
  245. isSpanned,
  246. rowspan,
  247. colspan,
  248. cellIndex: this._cellIndex
  249. }
  250. };
  251. }
  252. /**
  253. * Checks if the current row should be skipped.
  254. *
  255. * @private
  256. * @returns {Boolean}
  257. */
  258. _shouldSkipRow() {
  259. const rowIsBelowStartRow = this._row < this.startRow;
  260. const rowIsMarkedAsSkipped = this._skipRows.has( this._row );
  261. return rowIsBelowStartRow || rowIsMarkedAsSkipped;
  262. }
  263. /**
  264. * Checks if the current column should be skipped.
  265. *
  266. * @private
  267. * @returns {Boolean}
  268. */
  269. _shouldSkipColumn() {
  270. if ( this.column === undefined ) {
  271. // The {@link #column} is not defined so output all columns.
  272. return false;
  273. }
  274. return this.column != this._column;
  275. }
  276. /**
  277. * Checks if the current cell location (row x column) is spanned by another cell.
  278. *
  279. * @private
  280. * @param {Number} row Row index of a cell location to check.
  281. * @param {Number} column Column index of a cell location to check.
  282. * @returns {Boolean}
  283. */
  284. _isSpanned( row, column ) {
  285. if ( !this._spannedCells.has( row ) ) {
  286. // No spans for given row.
  287. return false;
  288. }
  289. const rowSpans = this._spannedCells.get( row );
  290. // If spans for given rows has entry for column it means that this location if spanned by other cell.
  291. return rowSpans.has( column );
  292. }
  293. /**
  294. * Returns the cell element that is spanned over `row` x `column` location.
  295. *
  296. * @private
  297. * @param {Number} row Row index of the cell location.
  298. * @param {Number} column Column index of the cell location.
  299. * @returns {module:engine/model/element~Element}
  300. */
  301. _getSpanned( row, column ) {
  302. return this._spannedCells.get( row ).get( column );
  303. }
  304. /**
  305. * Updates spanned cells map relative to the current cell location and its span dimensions.
  306. *
  307. * @private
  308. * @param {Number} row Row index of a cell.
  309. * @param {Number} column Column index of a cell.
  310. * @param {Number} rowspan Cell height.
  311. * @param {Number} colspan Cell width.
  312. * @param {module:engine/model/element~Element} cell Cell that is spanned.
  313. */
  314. _recordSpans( row, column, rowspan, colspan, cell ) {
  315. // This will update all cell locations after current column - ie a cell has colspan set.
  316. for ( let columnToUpdate = column + 1; columnToUpdate <= column + colspan - 1; columnToUpdate++ ) {
  317. this._markSpannedCell( row, columnToUpdate, cell );
  318. }
  319. // This will update all rows below current up to row's height.
  320. for ( let rowToUpdate = row + 1; rowToUpdate < row + rowspan; rowToUpdate++ ) {
  321. for ( let columnToUpdate = column; columnToUpdate <= column + colspan - 1; columnToUpdate++ ) {
  322. this._markSpannedCell( rowToUpdate, columnToUpdate, cell );
  323. }
  324. }
  325. }
  326. /**
  327. * Marks the cell location as spanned by another cell.
  328. *
  329. * @private
  330. * @param {Number} row Row index of the cell location.
  331. * @param {Number} column Column index of the cell location.
  332. * @param {module:engine/model/element~Element} cell Cell that is spanned.
  333. */
  334. _markSpannedCell( row, column, cell ) {
  335. if ( !this._spannedCells.has( row ) ) {
  336. this._spannedCells.set( row, new Map() );
  337. }
  338. const rowSpans = this._spannedCells.get( row );
  339. rowSpans.set( column, cell );
  340. }
  341. }
  342. /**
  343. * An object returned by {@link module:table/tablewalker~TableWalker} when traversing table cells.
  344. *
  345. * @typedef {Object} module:table/tablewalker~TableWalkerValue
  346. * @property {module:engine/model/element~Element} cell The current table cell.
  347. * @property {Number} row The row index of a cell.
  348. * @property {Number} column The column index of a cell. Column index is adjusted to widths and heights of previous cells.
  349. * @param {Boolean} isSpanned Whether the value is returned for a spanned cell location or actual cell.
  350. * @property {Number} colspan The `colspan` attribute of a cell. It the model attribute is not present, it is set to `1`. For spanned
  351. * table locations, it is set to `1`.
  352. * @property {Number} rowspan The `rowspan` attribute of a cell. It the model attribute is not present, it is set to `1`. For spanned
  353. * table locations, it is set to `1`.
  354. * @property {Number} cellIndex The index of the current cell in a parent row.
  355. */