AddWorkbookOptions

Extends

• WorkbookOptions

Properties

assumeArrayFormulas?

optional assumeArrayFormulas?: boolean;

Whether formulas should be assumed to be of array type even if not accompanied by an F property. Set this to true in tests specs, unless specifically testing implicit intersection and the like.

Default

false

Inherited from

WorkbookOptions.assumeArrayFormulas

---

extractExpressions?

optional extractExpressions?: boolean;

Try to extract repeated expressions; default true

---

filename?

optional 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

WorkbookOptions.filename

---

isExternal?

optional 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

false

Inherited from

WorkbookOptions.isExternal

---

iterativeCalculation?

optional iterativeCalculation?: IterativeCalculationOptions;

Settings for iterative calculations (nullish to disable; that’s the default)

Inherited from

WorkbookOptions.iterativeCalculation

---

mode?

optional 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

WorkbookOptions.mode

---

readOnly?

optional 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

WorkbookOptions.readOnly

---

recalcAll?

optional 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?

optional 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.

---

recalcUncached?

optional 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. 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.

---

recalcVolatiles?

optional 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.