TableWalker (table)
@ckeditor/ckeditor5-table/src/tablewalker
The table iterator class. It allows to iterate over table cells. For each cell the iterator yields
TableSlot with proper table cell attributes.
Filtering
Properties
-
The cell index in a parent row. For spanned cells when
_includeAllSlotsis set totrue, this represents the index of the next table cell. -
The current column index.
-
The current row index.
-
The index of the current row element in the table.
-
The walker's table element.
-
If set, the table walker will only output cells up to a given column.
-
A row index at which this iterator will end.
-
Enables output of spanned cells that are normally not yielded.
-
Indicates whether the iterator jumped to (or close to) the start row, ignoring rows that don't need to be traversed.
-
Index of the next column where a cell is anchored.
-
Row indexes to skip from the iteration.
-
private readonly
_spannedCells : Map<number, Map<number, CellData>>module:table/tablewalker~TableWalker#_spannedCellsHolds a map of spanned cells in a table.
-
If set, the table walker will only output cells from a given column and following ones or cells that overlap them.
-
A row index from which this iterator will start.
Methods
-
constructor( table, options )module:table/tablewalker~TableWalker#constructorCreates an instance of the table walker.
The table walker iterates internally by traversing the table from row index = 0 and column index = 0. It walks row by row and column by column in order to output values defined in the constructor. By default it will output only the locations that are occupied by a cell. To include also spanned rows and columns, pass the
includeAllSlotsoption to the constructor.The most important values of the iterator are column and row indexes of a cell.
See
TableSlotwhat values are returned by the table walker.To iterate over a given row:
const tableWalker = new TableWalker( table, { startRow: 1, endRow: 2 } ); for ( const tableSlot of tableWalker ) { console.log( 'A cell at row', tableSlot.row, 'and column', tableSlot.column ); }For instance the code above for the following table:
+----+----+----+----+----+----+ | 00 | 02 | 03 | 04 | 05 | | +----+----+----+----+ | | 12 | 14 | 15 | | +----+----+----+ + | | 22 | | |----+----+----+----+----+ + | 30 | 31 | 32 | 33 | 34 | | +----+----+----+----+----+----+
will log in the console:
'A cell at row 1 and column 2' 'A cell at row 1 and column 4' 'A cell at row 1 and column 5' 'A cell at row 2 and column 2'
To also iterate over spanned cells:
const tableWalker = new TableWalker( table, { row: 1, includeAllSlots: true } ); for ( const tableSlot of tableWalker ) { console.log( 'Slot at', tableSlot.row, 'x', tableSlot.column, ':', tableSlot.isAnchor ? 'is anchored' : 'is spanned' ); }will log in the console for the table from the previous example:
'Cell at 1 x 0 : is spanned' 'Cell at 1 x 1 : is spanned' 'Cell at 1 x 2 : is anchored' 'Cell at 1 x 3 : is spanned' 'Cell at 1 x 4 : is anchored' 'Cell at 1 x 5 : is anchored'
Note: Option
rowis a shortcut that sets bothstartRowandendRowto the same row. (Use eitherroworstartRowandendRowbut never together). Similarly thecolumnoption sets bothstartColumnandendColumnto the same column (Use eithercolumnorstartColumnandendColumnbut never together).Parameters
table : ElementA table over which the walker iterates.
options : TableWalkerOptionsAn object with configuration.
Defaults to
{}
-
Symbol.iterator() → IterableIterator<TableSlot>module:table/tablewalker~TableWalker#Symbol.iterator -
Gets the next table walker's value.
Returns
IteratorResult<TableSlot, undefined>The next table walker's value.
-
skipRow( row ) → voidmodule:table/tablewalker~TableWalker#skipRowMarks 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 to output.
Parameters
row : numberThe row index to skip.
Returns
void
-
private
_advanceToNextRow() → IteratorResult<TableSlot, undefined>module:table/tablewalker~TableWalker#_advanceToNextRow -
-
private
_formatOutValue( cell, anchorRow, anchorColumn ) → IteratorYieldResult<TableSlot>module:table/tablewalker~TableWalker#_formatOutValueA common method for formatting the iterator's output value.
Parameters
cell : ElementThe table cell to output.
anchorRow : numberThe row index of a cell anchor slot.
Defaults to
...anchorColumn : numberThe column index of a cell anchor slot.
Defaults to
...
Returns
IteratorYieldResult<TableSlot>
-
Returns a number of columns in a row taking
colspaninto consideration.Parameters
rowIndex : number
Returns
number
-
Returns the cell element that is spanned over the current cell location.
Returns
null | CellData
-
-
-
private
_jumpToNonSpannedRowClosestToStartRow() → voidmodule:table/tablewalker~TableWalker#_jumpToNonSpannedRowClosestToStartRowSets the current row to
this._startRowor the first row before it that has the number of cells equal to the number of columns in the table.Example: +----+----+----+ | 00 | 01 | 02 | |----+----+----+ | 10 | 12 | | +----+ | | 22 | | +----+ | | 32 | <--- Start row +----+----+----+ | 40 | 41 | 42 | +----+----+----+
If the 4th row is a
this._startRow, this method will: 1.) Count the number of columns this table has based on the first row (3 columns in this case). 2.) Check if the 4th row contains 3 cells. It doesn't, so go to the row before it. 3.) Check if the 3rd row contains 3 cells. It doesn't, so go to the row before it. 4.) Check if the 2nd row contains 3 cells. It does, so set the current row to that row.Setting the current row this way is necessary to let the
next()method loop over the cells spanning multiple rows or columns and update thethis._spannedCellsproperty.Returns
void
-
private
_markSpannedCell( row, column, data ) → voidmodule:table/tablewalker~TableWalker#_markSpannedCellMarks the cell location as spanned by another cell.
Parameters
row : numberThe row index of the cell location.
column : numberThe column index of the cell location.
data : CellDataA spanned cell details (cell element, anchor row and column).
Returns
void
-
private
_recordSpans( cell, rowspan, colspan ) → voidmodule:table/tablewalker~TableWalker#_recordSpansUpdates spanned cells map relative to the current cell location and its span dimensions.
Parameters
cell : ElementA cell that is spanned.
rowspan : numberCell height.
colspan : numberCell width.
Returns
void
-
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.