AddWorkbookOptions
Extends
Section titled “Extends”Properties
Section titled “Properties”extractExpressions?
Section titled “extractExpressions?”extractExpressions?: boolean;Try to extract repeated expressions; default true
filename?
Section titled “filename?”filename?: string;Filename to associate with the workbook. Used by fromXLSX methods when loading from binary data, since the filename cannot be inferred. Should not include path, just filename with extension.
Inherited from
Section titled “Inherited from”WorkbookOptions.filename
isExternal?
Section titled “isExternal?”isExternal?: boolean;Whether this workbook was loaded as an external reference from another workbook. External workbooks can be replaced by “real” workbooks with the same name.
Default
Section titled “Default”falseInherited from
Section titled “Inherited from”WorkbookOptions.isExternal
iterativeCalculation?
Section titled “iterativeCalculation?”iterativeCalculation?: IterativeCalculationOptions;Overrides the iterative calculation settings stored in the workbook. When omitted, uses the stored settings instead of disabling iteration.
Inherited from
Section titled “Inherited from”WorkbookOptions.iterativeCalculation
mode?: WorkbookMode;Spreadsheet-engine compatibility mode, governing formula evaluation and other behaviors that differ between Excel,
Google Sheets, and Grid Sheets (e.g. coercion of formula results, number-format propagation, spill extents).
Defaults to the mode mapped from the workbook’s type ('excel' → Excel, 'google-sheets' → Google Sheets),
falling back to MODE_GRID_SHEET when no mapping applies. An XLSX load settles that type from the file’s
originating application, so it is not always 'excel'.
Inherited from
Section titled “Inherited from”WorkbookOptions.mode
readOnly?
Section titled “readOnly?”readOnly?: boolean;When true, skip formula validation and the initial-recalc scheduling
during workbook construction. Useful when loading a workbook only to
inspect its structure (saved values stay as-is) without paying the
recalc cost. Defaults to false.
Inherited from
Section titled “Inherited from”WorkbookOptions.readOnly
recalcAll?
Section titled “recalcAll?”recalcAll?: boolean;Whether to recalculate every formula cell on init.
If unset, defaults to true when the workbook’s calculationProperties.fullCalcOnLoad is
true and its calcMode is not "manual", mirroring the OOXML
<calcPr fullCalcOnLoad="1"/> semantics of ECMA-376 §18.2.2. Setting it explicitly
overrides what the file says, in either direction.
When effective, this runs an ALL_FORMULA_CELLS recalc over every workbook in the model,
not just the one being attached — stronger than recalcVolatiles,
recalcErrors or recalcUncached. Such a recalc evaluates even deferred
data-table cells, so a workbook with both calcMode: "autoNoTable" and fullCalcOnLoad has
its data tables evaluated once at load, as in Excel; Model.deferDataTables still
applies to later recalculations.
recalcErrors?
Section titled “recalcErrors?”recalcErrors?: boolean;Whether to recalculate cells whose saved value is an error, on init. Assumed false if not specified: the saved error is kept, as Excel keeps it on open.
Turning it on attaches an origin reference to each such error, and a detail message where
the engine produces one; no file format stores either. It also replaces the saved error code
wherever the engine’s own result differs, and in an error-heavy workbook the recalculation
can reach most of the model.
A cell saved as #REF! whose formula can only ever evaluate to #REF! is not recalculated,
since recalculating it cannot change its value. It still gets its origin. Nothing downstream
of such a cell is recalculated either, so a dependent whose own saved value disagrees is left
as saved.
recalcUncached?
Section titled “recalcUncached?”recalcUncached?: boolean;Whether to evaluate, on init, formula cells that the file cached no value for, instead of
leaving them blank until a full recalculation. Defaults the same way as
recalcVolatiles: true unless the workbook’s calculationProperties.calcMode is
"manual", where Excel leaves such cells uncomputed on open. Left uncomputed, such a cell
reads blank, except under "manual", where it holds an empty string as in Excel. Formula cells
that depend on such a cell are recalculated with it. A cell whose formula references something
unresolvable (a missing defined name, sheet or workbook, or a function nothing implements)
reads #NAME? or #REF!, and a later attach that resolves the reference recalculates it even
when that attach’s other recalc options are off. recalcAll supersedes this option.
recalcUntrusted?
Section titled “recalcUntrusted?”recalcUntrusted?: boolean;Whether to recalculate on load the formula cells of a Google Sheets export whose saved value
is "" or an error name. Such an export saves a blank result like "", and an error like text
naming it, so only the formula can tell them apart.
Default
Section titled “Default”trueInherited from
Section titled “Inherited from”WorkbookOptions.recalcUntrusted
recalcVolatiles?
Section titled “recalcVolatiles?”recalcVolatiles?: boolean;Whether to recalculate volatile cells on init.
If unset, defaults to true unless the workbook’s calculationProperties.calcMode is
"manual", in which case it defaults to false: such a workbook’s saved values are what
Excel shows on open. An explicit setting wins in either direction.