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
Section titled “Constructors”Constructor
Section titled “Constructor”new PivotTable(jsf): PivotTable;Parameters
Section titled “Parameters”PivotTable
Returns
Section titled “Returns”PivotTable
Properties
Section titled “Properties”cacheIndex
Section titled “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.
readonly jsf: PivotTable;Accessors
Section titled “Accessors”colFieldIndices
Section titled “colFieldIndices”Get Signature
Section titled “Get Signature”get colFieldIndices(): readonly number[];Column field indices with negative placeholders (e.g. -2 for “Values”) filtered out.
Returns
Section titled “Returns”readonly number[]
colGrandTotals
Section titled “colGrandTotals”Get Signature
Section titled “Get Signature”get colGrandTotals(): boolean | undefined;Returns
Section titled “Returns”boolean | undefined
colRoles
Section titled “colRoles”Get Signature
Section titled “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, and in the row-axis
Values (onRows) layout where they multiply rows instead --- so this emits one role per
(subtotal, displayed data-field column), at the same columns the cell emitter writes them to:
the positions come from the emitter’s own subtotalCol closure (see _refRelativeEmitter).
Verified against excel-test/pivot-valuesouter-colsubtotal-verify and
excel-test/pivot-values-inner-position.
Returns
Section titled “Returns”colStride
Section titled “colStride”Get Signature
Section titled “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
firstHeaderRowandfirstDataRow). Used by the cell emitter for column position arithmetic --- except the row-axis Values layout, which overrides the column stride to 1 and expands rows by the data-field count instead (see resolveRowAxisStrides). Degenerate case (no data fields) yields 1.
Returns
Section titled “Returns”number
dataFields
Section titled “dataFields”Get Signature
Section titled “Get Signature”get dataFields(): readonly PivotDataField[];The data fields (a fresh deep copy on every read --- elements too, since the readonly
array typing would not stop element mutation), defaulting to empty when absent. Mutations
belong on jsf.dataFields (followed by clearLayout), never here.
Returns
Section titled “Returns”readonly PivotDataField[]
location
Section titled “location”Get Signature
Section titled “Get Signature”get location(): PivotTableLocation;Returns
Section titled “Returns”PivotTableLocation
Get Signature
Section titled “Get Signature”get name(): string;Returns
Section titled “Returns”string
pageArea
Section titled “pageArea”Get Signature
Section titled “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
Section titled “Returns”PivotPageArea | null
Get Signature
Section titled “Get Signature”get ref(): string;The A1-style range covering the pivot’s output area.
Returns
Section titled “Returns”string
rowFieldIndices
Section titled “rowFieldIndices”Get Signature
Section titled “Get Signature”get rowFieldIndices(): readonly number[];Row field indices with negative placeholders (e.g. -2 for “Values”) filtered out.
Returns
Section titled “Returns”readonly number[]
rowGrandTotals
Section titled “rowGrandTotals”Get Signature
Section titled “Get Signature”get rowGrandTotals(): boolean | undefined;Returns
Section titled “Returns”boolean | undefined
rowRoles
Section titled “rowRoles”Get Signature
Section titled “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.
In the row-axis Values (dataOnRows) layout each aggregate subtotal spans one sheet row per
data field, so it contributes that many entries --- regardless of its role, since an
outline-above aggregate (Values nested at a non-innermost row position) classifies as a
subheading yet still expands (see below). Only the separator and blank rows stay single-row
(the positioner collapses their data-field offset).
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
Section titled “Returns”Get Signature
Section titled “Get Signature”get sheet(): string;Returns
Section titled “Returns”string
Get Signature
Section titled “Get Signature”get style(): PivotTableStyle | undefined;Returns
Section titled “Returns”PivotTableStyle | undefined
Methods
Section titled “Methods”containsOutput()
Section titled “containsOutput()”containsOutput(row, col): boolean;Check whether (row, col) falls within this pivot table’s output area.
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”boolean
getDataValue()
Section titled “getDataValue()”getDataValue( dataFieldName, criteria, options?): | CellValue | PivotLookupError;Look up an aggregated value by data field name and field/item criteria (GETPIVOTDATA).
Parameters
Section titled “Parameters”dataFieldName
Section titled “dataFieldName”string
criteria
Section titled “criteria”[string, CellValue][]
options?
Section titled “options?”caseSensitiveFieldNames?
Section titled “caseSensitiveFieldNames?”boolean
Returns
Section titled “Returns”| CellValue
| PivotLookupError
getOutputBounds()
Section titled “getOutputBounds()”getOutputBounds(): | Readonly<OutputBounds> | null;Compute and cache the output bounds from the materialized cell writes. Unlike ref, which is
only rewritten when a refresh/repaint runs and so can lag a source-data change, these bounds
always reflect the current data. Returns null for malformed refs. Every call returns a fresh
copy: the bounds behind containsOutput, PivotManager.findAt, and the pivot write guards
must not be reachable through the return value.
Returns
Section titled “Returns”| Readonly<OutputBounds>
| null
getProtectedBounds()
Section titled “getProtectedBounds()”getProtectedBounds(): | Readonly<OutputBounds> | null;The pivot’s full protected footprint: its output area (getOutputBounds) extended to
cover the page-field (report-filter) area, which materializes ABOVE the anchor (and, when the
page fields wrap into multiple column-groups, to the RIGHT of the body) and outside ref (see
PivotPageArea). Identical to getOutputBounds when the pivot has no page fields.
The range/structural write guards (clearCells, moveCells, insert/delete cells, insert/delete
rows or columns) use this rather than getOutputBounds so they agree with the single-cell write
guard, which blocks writes anywhere in the per-sheet R-tree footprint (fed from
boundsOfWrites, which already covers the page-field caption cells). Without it, a range or
structural edit overlapping only the page area would slip past while a direct write to the same
cell is blocked.
Body-bounds consumers keep using getOutputBounds: syncLayoutToJSF’s ref excludes the page
area by Excel convention, and the adopted-output export scrub deliberately reads only the body.
Returns
Section titled “Returns”| Readonly<OutputBounds>
| null