Optionaloptions: string | IWorkbook.ConstructorOptionsFor runtime type checking.
Returns any custom workbook options that are provided in constructor.
Add Listeners.
Optionaloptions: IListener.OptionsAdds a new sheet to the workbook.
Optionaloptions: string | number | IWorksheetCollection.AddOptionsBatches all 'transactional' changes until they have all be committed or rolled back.
Optionaloptions: string | ITransaction.OperationOptions
Description of the operation or additional options. Used for tracking undo/redo and history. Default Value User Operation.
Any changes that are made to this object will be reflected in the local record but not committed to the transactional store until the batch is popped.
Useful for operations that are longer running but generally not recommended as it keeps a transaction open. doBatch is the preferred option.
Parses a formula expression and returns a transient formula object.
The formula expression to parse.
Optionalcoords: Partial<CellCoords>
Optional anchor coordinates.
Optionaloptions: CreateFormulaOptions
Optional parse options; the expression is storage text unless target is 'display'.
This is a convenience method for getCalculation().createFormula(expression, coords, options).
A bare reference (A2) resolves against the active cell's sheet; use
IWorksheet.createFormula to anchor against a specific sheet.
Performs a set of operations as one: one commit, one undo step, one round of events.
Performs the operations. Handed the commit being written and workbook,
this workbook bound to the batch.
Optionaloptions: string | ITransaction.OperationOptions
Description of the operation or additional options. Used for undo/redo and history.
Work through workbook rather than this one. Everything reached through it - sheets, ranges,
tables - is part of the batch, and a listener added through it takes part in the batch by
default (IListener.Options.transactional). A range listener added through it hears each
operation as it is made, rather than once when the batch lands, and what it writes joins the
batch (ICellRange.ListenerOptions.transactional). A listener added any other way, while
the batch is open, is outside it.
The objects reached through workbook are not === to the ones reached through this workbook,
though the same object always compares equal to itself. They can be passed to any method of
either.
A batch that performs no writes is elided: the commit id is unchanged, no events fire, and nothing is added to the undo stack or commit log.
Evaluates a formula in the context of the sheet and returns the resulting value.
The formula to evaluate.
Optionaloptions: number | EvaluateOptions & Partial<CellCoords> & CreateFormulaOptions
Optional evaluation options.
Fetches as the workbook does, with the standard fetch signature: what IMAGE, a web
service function, and a renderer drawing a picture use.
Optionalinit: RequestInitA resource with a fetchedFrom is the workbook's copy of that URL, and answers a fetch of it
without a request. Anything else goes to getFetcher. The fetch saves nothing itself: a
successful answer to a plain GET that is not a picture is cached until the workbook closes and
answers later fetches of that URL. A response whose bytes are a picture says what they are,
whatever the server called them. Plain GETs of one URL in flight together share one request;
aborting one caller's signal does not stop it for the others. cache: 'reload' skips all of
these and asks the source.
The workbook saves a resource while a value holds it: IMAGE adds the picture it fetched for
its values. A picture of the host's own goes in a cell the same way, under a URL the host mints:
const source = `resource:${crypto.randomUUID()}`;
const resource = workbook.getResources().add({ source: { buffer: bytes }, fetchedFrom: source });
workbook.getRange('A1').setValue({ type: 'image', data: { source, resource } });
Search the entire Workbook.
The text to search for or ICellRange.FindOptions
Given the name return a valid name that closely matches.
The string to validate.
{@inheritDoc IWorkbook.getActiveSheet}
{@inheritDoc IWorkbook.getActiveWorksheet}
Returns the regions of the anomalies feature across every sheet, in reading order.
Optionaloptions: GetAnomaliesOptionsThe workbook form of ICellRange.getAnomalies: every sheet contributes, hidden and very hidden included, in one order, and each region's address names its sheet. The listing spans sheets, so its ICellRegions.getRange is the selected sheet's; each region is clipped against its own sheet.
Returns the ICalculation for the workbook.
What a commit wrote: the IWorksheet.ChangeEvents it announced, one for each sheet and kind (data, formatting, merges, spills).
OptionalcommitId: string
The commit to describe. Omit for the current one.
Empty for a commit that changed no cells (a view, a name, a chart).
The same events the sheets announced when the commit landed, read afterwards: the
previous commit is its parent, and an undo is reported as the commit it moved to, so
IWorksheet.ChangeEvent.isUndo is always false here.
The workbook's VBA code name — conventionally ThisWorkbook — or null if it has none.
The workbook-level counterpart to IWorksheet.getCodeName: the identifier VBA binds the
workbook's own document module through, where workbook event handlers such as Workbook_Open
live. Like a sheet's, it is carried from the file and read-only — see
IWorksheet.getCodeName for why SheetXL never mints one.
Returns the comments and notes on every sheet, in sheet order.
A view over each sheet's IWorksheet.getComments; getById and getByReplyId search
them all. A comment is added on a sheet's collection.
The workbook's external books — cached snapshots of other workbooks, addressed from a formula
as [n]Sheet1!$A$1. In [n] order.
A link is made by a formula — typing 'C:\path\[Budget.xlsx]Sheet1'!A1 adds a book here —
and removed by breaking it (IExternalBookCollection.breakLink). Each book lists the
formulas that cite it (IExternalBook.getDependents). The engine's collection, so
available once the calculation is constructed, which is before any sheet is.
The fetcher the workbook reaches outside itself with: the handlers per URL scheme a host registered, given as IWorkbook.ConstructorOptions.fetcher.
Returns the IFontCollection the workbook measures text with.
The sheet's id: what formulas and operations identify it by. Unique among all in-memory sheets.
Returns the workbook's locale-profile overrides (the regional-override patch), or
null when the profile is entirely Intl-derived from IWorkbook.getLocale.
Returns the modules this workbook owns.
The workbook half of IWorksheet.getModules, and the same collection
getScripts().getModules() answers with — modules belong to the model, whereas
IScript is what runs them.
Holds the globally scoped modules, whose functions ARE in the formula namespace, and the workbook-scoped ones, whose functions are not (IModule.getScope). A sheet's modules are not in here at all; they hang off the sheet.
Like every module collection, this filters to TypeScript unless asked otherwise; imported VBA
is read with getItems({ language: 'vba' }).
Returns the display name for the workbook — a pure, read-only derivation of its
origin's name — or null for an unbound, unnamed workbook.
A workbook has no intrinsic name (like Excel: a workbook's name is its file name). Display fallbacks (a localized "Untitled") are a UI concern. Renaming is an origin-level operation (see IWorkbookIO.Origin.setName), never a model edit — it is not undoable.
Every INamed in the workbook — global names, every sheet's scoped names, and every table — sorted by type then by name.
The name-manager view: what EXISTS, not what any one sheet can see. A global name and a sheet-scoped name that share a name are two items here and both are returned; ask IWorksheet.getNames for the one a formula on that sheet would resolve to.
Returns the next visible sheet, of any kind, after the given tab position. If the last one it will return the first.
Returns the workbook's origin — the file handle it lives in.
Always present: a new in-memory workbook holds an unbound origin (getPath() null). Like
the DOM's document.URL, which origin can change — a save that resolves a new destination (a
first save, a Save As) moves the workbook to the file it wrote, firing
onOriginChange. So read it when needed rather than
holding it; to follow the current file, listen for onOriginChange.
The model never mutates its origin, and the origin is not part of the persisted document (toJSON); a copy mints a fresh unbound origin.
Returns the people the workbook knows: the authors of its comments.
Returns the locale explicitly pinned on the workbook, or null when it
follows the environment locale.
IWorkbook.getLocale always resolves to a concrete tag; this is the only way to tell a pinned locale from an environment fallback that happens to match it. Only a pinned locale is persisted.
Returns the pivot tables on every sheet, in sheet order.
A view over each sheet's IWorksheet.getPivotTables; getByName searches them all.
Read-only for now: each table is carried as it was read and written back unchanged.
Returns the previous visible sheet, of any kind, before the given tab position. If the first one it will return the last.
The workbook's document properties: author, title, company and the like.
Returns the protection object for the workbook.
Returns ranges scoped to a sheet.
Optionaladdress: ICellRange.Address
Address of the ranges. Omit for the selected range — selection is modeled
by the SDK (not a UI mode), and many operations default to it. getSelectedRange remains
the explicit form.
Optionaloptions: ICellRange.GetRangeOptionsWhen accessing ranges from the IWorkbook ranges include a sheet name.
This enables cross-sheet references when working at the workbook level.
Some examples of cross-sheet reference are:
Linking data and formulas across multiple sheets.
Consolidating data from different sheets for analysis or reporting.
Performing calculations or comparisons that involve values from multiple sheets.
Returns an a set of ranges including sheet names.
Address of the ranges.
Optionaloptions: ICellRange.GetRangeOptionsReturns the current shared resources.
Returns the runtime used for this workbook.
Returns any user defined functions stored with the workbook.
Returns a range of cells for the current selection.
Optionaloptions: ICellRange.GetRangeOptionsReturns ranges of cells for the current selection.
Optionaloptions: ICellRange.GetRangeOptionsReturns the active tab, whatever its kind.
Use getSelectedWorksheet for the active grid.
Returns the position of the active tab among the visible sheets of every kind.
Returns the active worksheet, or null when the active tab is not a worksheet.
A chart sheet (or a macro or dialog sheet) can be the active tab, and then there is no active
worksheet: like VBA's ActiveCell, this is null rather than some other worksheet.
getSelectedSheet returns the active tab whatever its kind.
Returns the sheet of any kind with the given name, or the selected sheet when no name is given.
Optionalname: string
The name of the sheet, ignoring case.
Throws when there is no sheet with that name. Use getWorksheet when the sheet must be a grid.
Returns every sheet in tab order, of every kind: worksheets, chart sheets, macro sheets and dialog sheets.
Optionaloptions: GetSheetsOptions
Which sheets to return; by default the visible ones.
Use getWorksheets for the grids alone.
Returns the statistics for the used cells across all sheets.
Optionaloptions: GetStatsOptions
Iterator options the stats are created with. At workbook scale prefer
{ onError: 'ignore' } — some error value existing somewhere is likely, and the
default 'throw' policy treats one as a fault when aggregating.
The workbook form of IWorksheet.getStats: every sheet's used range contributes,
including hidden and very-hidden sheets — visibility is a display concern, not a data
one. A workbook with no used cells returns empty statistics (getSize() === 0),
never null.
Cross-sheet value ordering (where observable) follows sheet index order.
Returns the current shared resources.
Returns the current IStyleCollection associated with this Workbook.
Get the current theme.
Returns the current shared resources.
When the cached values of getExternalBooks should be re-read from their sources on
open, or null where the source file said nothing (which Excel reads as userSet).
Carried, not obeyed — SheetXL never refreshes a link, so every mode behaves as never until
a resolver exists. Round-trips as workbookPr@updateLinks.
The mode is IExternalBookCollection.UpdateLinks: it governs the books as a set, and no single book has one. It is read and written HERE because it is a property of the workbook in both Excel's object model and the file, not of the collection the books live in.
Every committed update gives the record a new, strictly increasing version id.
Used with getId to uniquely identify a version of the record.
The id is an identity, not a per-record count: ids are drawn from a single store-wide sequence bumped once per commit, so all records written in the same commit share an id and a given record's ids increase but are not sequential.
Records are immutable so a restore/revert doesn't change them — it repoints, and the version id reported is the one for the snapshot the store is currently at. Version ids are never reused: a write after an undo receives an id higher than any previously issued, so a stale reader can always detect the change.
Returns the current view settings.
View settings determine how specific workbook level elements are displayed but does not affect the underlying data itself.
Returns the worksheet for the given name, or the selected worksheet when no name is given.
Optionalname: string | number
The name of the sheet. Omit for the selected sheet — "the sheet", unqualified,
is the one the user (or agent) is looking at. getSelectedWorksheet remains the explicit form.
The visibility of the sheet.
Throws when the sheet is not a worksheet: a chart sheet, say, or the selected tab when that is not a worksheet. Use getSheet for any kind.
Returns the worksheet at the given offset among the worksheets.
A 0-based index into the worksheets with the given visibility. Sheets of other kinds are not counted, so this is not the tab position (ISheet.getIndex).
The visibility of the sheet.
Returns the collection of worksheets within the workbook.
Only the grids. Use getSheets for every tab, chart sheets included.
Indicates if the model has been closed.
Indicate if the current character is a valid character for a sheetName.
The string to validate.
Replace all items in the iterator
An iterator of cells to replace.
The ICell.Update or a callback to replace with.
Optionaloptions: ReplaceOptionsDetermine if dates should be 1904 instead of 1900 based.
default value false
Set the regional locale of the workbook.
A BCP 47 tag, e.g. de-DE. Pass null to follow the
environment locale.
Patch individual derived regional settings on top of the locale — the escape
hatch for the OS-level customizations (a custom decimal symbol, a different
currency) that browser Intl cannot see.
A literal patch over the derived LocaleProfile (e.g.
{ decimal: '.', currencySymbol: 'CHF' }), or null to clear. Applied
literally — nothing is re-derived, so patch listSeparator too if you patch
decimal. Persisted in .sxl alongside the locale tag (never in .xlsx).
Sets getUpdateLinks. null writes no attribute at all.
Views have their own lifecycle because in a collaborative environment each user can have their own view.
Serialize the workbook to a JSON.
Optionaloptions: ToJSONOptions
Options to control the JSON output.
Returns a string representation of an object.
Returns when all calculations are complete and there are no pending calculations.
getCalculation().ready(), which starts the engine if
it has not been started.Returns when every font the workbook measures with has loaded and every autofit that was taken with a stand-in meanwhile has been taken again.
Measuring never waits: a style naming a face not yet loaded measures with a related or built-in one and the lookup starts the load, the way a browser paints with a fallback until a web font arrives. This is the point after which sizes are final. Fonts are shared, so this also waits for faces other workbooks started loading; a load that fails leaves its stand-in and still settles.
Returns when the workbook is settled: whenCalculationReady and whenFontsReady both hold.
The Base implementation of IWorkbook.