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.