Appearance
Class: Table ​
A table: a grid of rows and cells inside a graphic frame.
Constructors ​
Constructor ​
new Table(
tbl,part,themeContext,opc,rels):Table
Parameters ​
| Parameter | Type | Description |
|---|---|---|
tbl | Element | - |
part | Part | - |
themeContext | ThemeContext | The owning slide's theme colour context, threaded to each cell's text for Run.resolvedColor. |
opc | OpcPackage | The deck package, for resolving a:tableStyleId against tableStyles.xml (style-graph cell fills). |
rels | Relationships | The owning slide's relationships, for resolving a cell picture fill's r:embed to a partname. |
Returns ​
Table
Accessors ​
bandedColumns ​
Get Signature ​
get bandedColumns():
boolean
Whether columns are banded (a:tblPr/@bandCol), from addTable's hasBandedColumns.
Returns ​
boolean
bandedRows ​
Get Signature ​
get bandedRows():
boolean
Whether rows are banded (a:tblPr/@bandRow), from addTable's hasBandedRows.
Returns ​
boolean
columnCount ​
Get Signature ​
get columnCount():
number
Number of grid columns (a:tblGrid/a:gridCol).
Returns ​
number
columnWidths ​
Get Signature ​
get columnWidths(): (
number|null)[]
Column widths in EMU (a:gridCol/@w), one per grid column.
Returns ​
(number | null)[]
element_ ​
Get Signature ​
get element_():
Element
Escape hatch: the underlying a:tbl element. After mutating it call markDirty, or save() writes the original bytes.
Returns ​
Element
fillSchemeColor ​
Get Signature ​
get fillSchemeColor():
string|null
The raw schemeClr token of the table's own background (a:tblPr/a:solidFill/a:schemeClr/@val), or null for an absent or srgbClr fill. resolvedFill is the literal it resolves to; this is the unresolved reference, which is what a replica should carry so the copy still tracks its theme.
Returns ​
string | null
firstColumnHeader ​
Get Signature ​
get firstColumnHeader():
boolean
Whether the first column is emphasised (a:tblPr/@firstCol), from addTable's hasFirstColumn.
Returns ​
boolean
firstRowHeader ​
Get Signature ​
get firstRowHeader():
boolean
Whether the first row is styled as a header (a:tblPr/@firstRow), which addTable writes from hasHeader.
This and the five below are PowerPoint's Table Style Options, the six flags that decide which regions of the table style paint. Two of them were readable and four were not, although resolvedStyle has always read all six to resolve a cell: addTable writes every one, so a table read back and re-authored lost its footer row, its banded columns and its first and last column emphasis with nothing to say so.
Returns ​
boolean
gradientFill ​
Get Signature ​
get gradientFill():
GradientFill|null
The table's gradient background (a:tblPr/a:gradFill), or null when it is not gradient-filled. Needed for the same reason pictureFill is: resolvedFill decodes only solid colours.
Returns ​
GradientFill | null
lastColumnFooter ​
Get Signature ​
get lastColumnFooter():
boolean
Whether the last column is emphasised (a:tblPr/@lastCol), from addTable's hasLastColumn.
Returns ​
boolean
lastRowFooter ​
Get Signature ​
get lastRowFooter():
boolean
Whether the last row is styled as a footer (a:tblPr/@lastRow), from addTable's hasFooter.
Returns ​
boolean
patternFill ​
Get Signature ​
get patternFill():
PatternFill|null
The table's pattern (hatch) background (a:tblPr/a:pattFill), or null when it is not pattern-filled.
Returns ​
PatternFill | null
pictureFill ​
Get Signature ​
get pictureFill():
PictureFill|null
The table's picture background (a:tblPr/a:blipFill), or null when the table is not image-backed. The table-level twin of TableCell.pictureFill, and needed for the same reason: resolvedFill decodes only solid colours, so without this an image-backed table is indistinguishable from an unfilled one.
Returns ​
PictureFill | null
resolvedFill ​
Get Signature ​
get resolvedFill():
ResolvedColor|null
The table's own background (a:tblPr fill) resolved against the slide's theme colour context to a literal hex, or null when the table carries no solid background.
This is the table-level counterpart of TableCell.resolvedFill, and it is a genuinely different thing from a cell fill: a a:tblPr fill sits behind the grid, so a cell with no fill of its own shows it through. Reports null for a non-solid choice (a:blipFill/a:gradFill/a:pattFill/a:noFill) — read pictureFill for an image background.
Returns ​
ResolvedColor | null
resolvedStyle ​
Get Signature ​
get resolvedStyle():
ResolvedTableStyle|null
The table's style graph entry (styleId, name, raw a:tblStyle) resolved from the deck's tableStyles.xml, or null when the table names no a:tableStyleId, the deck has no tableStyles.xml, or the id is a built-in [MS-OE376] style the deck does not materialise. This is what supplies the banded-row / header shading a cell with no own fill inherits — read the resolved per-cell colour off TableCell.resolvedFill.
Resolved afresh on every read, not through the per-instance memo the cells share, so an edit made through the returned element_ shows in the next read's name. A caller reads this once per table; the memo exists for the per-cell path that reads it hundreds of times.
Returns ​
ResolvedTableStyle | null
rowCount ​
Get Signature ​
get rowCount():
number
Number of rows (a:tr).
Returns ​
number
rows ​
Get Signature ​
get rows():
TableRow[]
The table's rows (a:tr) in document (top-to-bottom) order.
Returns ​
TableRow[]
styleId ​
Get Signature ​
get styleId():
string|null
The table's style GUID (a:tblPr/a:tableStyleId text), e.g. {5940675A-B579-460E-94D1-54222C63F5DA}, or null when the table carries no a:tableStyleId. This is the reference into ppt/tableStyles.xml (or a built-in [MS-OE376] style) that supplies the banded-row / header shading the firstRow/bandRow flags activate — without it a replica loses the whole table style, so it is the read counterpart of the writer's tableStyle option.
Returns ​
string | null
Methods ​
addColumn() ​
addColumn(
index?,widthEmu?):void
Insert a column, defaulting to the right-hand end. Updates a:tblGrid and every row, which is the pair that has to stay in step.
The mirror of addRow's merge case: inserting inside a horizontal merge widens it instead of splitting it.
Parameters ​
| Parameter | Type | Description |
|---|---|---|
index? | number | where to insert, 0..columnCount; appended when omitted |
widthEmu? | number | the new column's width; defaults to 1 inch |
Returns ​
void
Throws ​
when index is outside that range
addRow() ​
addRow(
index?):TableRow
Insert a row, defaulting to the bottom of the table. Returns the new TableRow.
The new row is auto-height (a:tr/@h="0") and its cells are empty. Inserting through a vertical merge extends that merge rather than interrupting it: the span's origin grows by a row and the new cell joins as a continuation, because an origin claiming more rows than it has continuations is a table PowerPoint reports as corrupt.
Parameters ​
| Parameter | Type | Description |
|---|---|---|
index? | number | where to insert, 0..rowCount; appended when omitted |
Returns ​
Throws ​
when index is outside that range
cell() ​
cell(
rowIndex,columnIndex):TableCell|null
The cell at (rowIndex, columnIndex) (both zero-based), or null when out of range. Column index counts a:tc elements in the row, so a cell that spans columns (gridSpan) occupies a single index here.
Parameters ​
| Parameter | Type |
|---|---|
rowIndex | number |
columnIndex | number |
Returns ​
TableCell | null
markDirty() ​
markDirty():
void
Mark the owning part dirty so save() reserializes it. Call after mutating element_.
Returns ​
void
mergeCells() ​
mergeCells(
row1,col1,row2,col2):void
Merge the rectangle between two cell positions into one cell. The top-left cell keeps its content; the rest become covered cells and are emptied, since a covered cell is never rendered.
A rectangle that cuts through an existing merge is rejected, not silently widened to fit — the caller asked for a specific region, and quietly producing a different one is how a layout ends up wrong with nothing to point at. Unmerge first.
Parameters ​
| Parameter | Type |
|---|---|
row1 | number |
col1 | number |
row2 | number |
col2 | number |
Returns ​
void
Throws ​
when an index is out of range, the range covers one cell, or it partially overlaps an existing merge
removeColumn() ​
removeColumn(
index):void
Remove the column at index, from a:tblGrid and from every row.
Inside a horizontal merge the region narrows by one and keeps its content: a covered cell is dropped rather than the origin. Elsewhere the column's cells go with it.
Parameters ​
| Parameter | Type |
|---|---|
index | number |
Returns ​
void
Throws ​
when index is out of range
removeRow() ​
removeRow(
index):void
Remove the row at index, with its content.
A cell in the row that continues a vertical merge shortens that merge. A cell that starts one hands the region to its first continuation, which becomes the new origin — the merged region survives one row shorter, and only the removed row's own text is lost.
Parameters ​
| Parameter | Type |
|---|---|
index | number |
Returns ​
void
Throws ​
when index is out of range
unmergeCell() ​
unmergeCell(
row,col):void
Split the merged cell whose origin is (row, col) back into individual cells. A no-op on a cell that is not merged; addressing a covered cell instead of the origin throws, and the message names the origin to use.
Parameters ​
| Parameter | Type |
|---|---|
row | number |
col | number |
Returns ​
void
Throws ​
when an index is out of range or the cell is a covered cell