PivotTable

Runtime representation of a pivot table. Wraps the JSF PivotTable definition and provides methods for computing layout, writing to sheet cells, and looking up values for GETPIVOTDATA.

Constructors

Constructor

new PivotTable(jsf): PivotTable;

Parameters

jsf

PivotTable

Returns

PivotTable

Properties

cacheIndex

readonly cacheIndex: number = -1;

Position in the owning manager’s _caches array, or -1 when unbound. Used only for serialization correlation; runtime lookups go through the attached cache directly. Readonly because the invariant “matches manager._caches.indexOf(_cache)” must be updated atomically with the cache attachment.

---

jsf

readonly jsf: PivotTable;

Accessors

colFieldIndices

Get Signature

get colFieldIndices(): readonly number[];

Column field indices with negative placeholders (e.g. -2 for “Values”) filtered out.

Returns

readonly number[]

---

colGrandTotals

Get Signature

get colGrandTotals(): boolean | undefined;

Returns

boolean | undefined

---

colRoles

Get Signature

get colRoles(): PivotColRole[];

Column-axis style roles --- the rowRoles mirror for the column axis, as 0-based column offsets from the left of the output area. The renderer positions a declared table style’s firstSubtotalColumn region on these.

The column axis has no outline/separator placement modes (column subtotals always sit right-of-group), so every entry is a subtotal; there is no column subheading. A column subtotal materializes once per displayed data field --- the data fields multiply the columns, except in the hideValuesRow collapse where they show as a single block --- so this emits one role per (subtotal, displayed data field), at the same columns the cell emitter writes them to. The position mirrors the emitter’s subtotalCol closure (buildColumnPositioners in Compute-cellEmitter.ts), made ref-relative: when Values is the outer column field each data field claims a contiguous block of outputColCount columns, otherwise the data fields interleave at colStride. Verified against excel-test/pivot-valuesouter-colsubtotal-verify.

Returns

PivotColRole[]

---

colStride

Get Signature

get colStride(): number;

Columns each column-header group occupies in the computed output: normally one per data field, but collapses to 1 when the location lacks slack for the synthetic Values row (Excel’s hideValuesRow="1" signature: multi-data

• col-axis + no slack between firstHeaderRow and firstDataRow). Used by the compute step for position arithmetic and by getOutputBounds to size the pivot’s bounding box. Degenerate case (no data fields) yields 1.

Returns

number

---

dataFields

Get Signature

get dataFields(): PivotDataField[];

The data fields, defaulting to empty when absent.

Returns

PivotDataField[]

---

location

Get Signature

get location(): PivotTableLocation;

Returns

PivotTableLocation

---

name

Get Signature

get name(): string;

Returns

string

---

pageArea

Get Signature

get pageArea(): PivotPageArea | null;

Geometry of the page-field (report filter) area, or null when the pivot has no page fields. The renderer (mondrian) reads this to find the filter cells --- they sit above and outside ref, so its per-cell pivot index built from ref never reaches them --- e.g. to position a declared table style’s pageFieldLabels / pageFieldValues regions.

The geometry is purely positional: when the anchor sits too high for all the rows to fit (a hand-built JSF; Excel reserves the rows on creation), the reported region can extend above the top of the sheet, and getCellWrites omits the cells that fall there. Callers clip to the sheet.

Returns

PivotPageArea | null

---

ref

Get Signature

get ref(): string;

The A1-style range covering the pivot’s output area.

Returns

string

---

rowFieldIndices

Get Signature

get rowFieldIndices(): readonly number[];

Row field indices with negative placeholders (e.g. -2 for “Values”) filtered out.

Returns

readonly number[]

---

rowGrandTotals

Get Signature

get rowGrandTotals(): boolean | undefined;

Returns

boolean | undefined

---

rowRoles

Get Signature

get rowRoles(): PivotRowRole[];

Style roles of the output rows that are not plain data rows: the row axis’s subheading (group label) and subtotal rows, as 0-based row offsets from the top of the output area. The renderer (mondrian) reads this to position a declared table style’s firstRowSubheading / firstSubtotalRow regions. Blank separator rows (insertBlankRow="1") carry no role; the renderer styles them as plain body rows.

A row is a subheading when it is the group’s label row, and a subtotal only when it is a dedicated subtotal row below its group. Excel styles the above-group row (outline/compact “subtotal at top”, where the group label and its subtotal share one row) as a subheading, not a subtotal --- verified in Excel on PivotStyleLight16 (an above-group row shows no top border and no fill, the firstRowSubheading look, where firstSubtotalRow would add a top border). So outlineAbove rows classify as subheading alongside the bare separator rows; only below-group rows (outlineAbove === false) are subtotal.

Returns

PivotRowRole[]

---

sheet

Get Signature

get sheet(): string;

Returns

string

---

style

Get Signature

get style(): PivotTableStyle | undefined;

Returns

PivotTableStyle | undefined

Methods

adjustOutputRange()

adjustOutputRange(
   sheetName,
   dimension,
   index,
   count): boolean;

Adjust the output range after rows or columns are inserted or deleted on a sheet.

Parameters

sheetName

string

the sheet where the structural edit happened

dimension

Dimension

‘row’ or ‘col’

index

number

0-based index where insertion/deletion starts

count

number

positive for insertion, negative for deletion

Returns

boolean

false if the range was fully deleted (pivot table should be removed), true otherwise

---

clearLayout()

clearLayout(): void;

Invalidate the cached layout, lookup cache, and output bounds; next access recomputes.

Returns

void

---

computeLayout()

computeLayout(): PivotLayout;

Compute the pivot layout, grouping records by row/column field values and aggregating data.

Returns

PivotLayout

---

containsOutput()

containsOutput(row, col): boolean;

Check whether (row, col) falls within this pivot table’s output area.

Parameters

row

number

col

number

Returns

boolean

---

getCellWrites()

getCellWrites(options?): PivotCellWrite[];

Build a flat array of cell writes for the pivot table output. Each entry is [row, col, value, style?] in 0-based sheet coordinates. this.jsf is normalized at construction time, so layout offsets read from this.jsf.location directly yield the correct axis-label row. Returns an empty array when the pivot has no anchor or no layout content.

options.stampStructuralXfs enables the structural-xfs post-pass (pivotButton, row-label alignment). See computeCellWrites.

Parameters

options?

ComputeOptions

Returns

PivotCellWrite[]

---

getDataValue()

getDataValue(
   dataFieldName,
   criteria,
   options?):
  | CellValue
  | PivotLookupError;

Look up an aggregated value by data field name and field/item criteria (GETPIVOTDATA).

Parameters

dataFieldName

string

criteria

[string, CellValue][]

options?

caseSensitiveFieldNames?

boolean

Returns

| CellValue | PivotLookupError

---

getOutputBounds()

getOutputBounds(): OutputBounds | null;

Compute and cache the output bounds from the pivot layout. Unlike ref, which may be stale after a refresh that changes the number of rows or columns, these bounds reflect the current layout. Returns null for malformed refs.

Returns

OutputBounds | null

---

renameOutputSheet()

renameOutputSheet(oldName, newName): void;

Update the sheet name for this pivot table’s output location.

Parameters

oldName

string

newName

string

Returns

void

---

setCache()

setCache(cache): void;

Attach a cache to this pivot table.

Parameters

cache

PivotCache

Returns

void

---

syncLayoutToJSF()

syncLayoutToJSF(): void;

Update jsf.rowItems, jsf.colItems, and other JSF properties from the computed layout so jsf2xlsx can emit the XML elements Excel requires. Mutates this.jsf in place (field items, location, field indices) but is idempotent. The *FieldIndices arrays are replaced wholesale; external references to the old arrays go stale, so callers should re-read from this.jsf afterward. A -2 sentinel may be appended to jsf.colFieldIndices or jsf.rowFieldIndices for multi-data-field pivots; use the colFieldIndices/rowFieldIndices getters (which filter out negatives) rather than reading jsf.*FieldIndices directly.

Returns

void