ReadonlyisFor runtime type checking.
ReadonlyisFor runtime type checking.
Creates a 'light' table used for stateful filtering and sorting with-in a sheet.
Optionaladdress: ICellRangeOptionaloptions: AddAutoTableOptionsAdds a page break before the top row of the range. The same as
getPageLayout().addHorizontalPageBreak().
Optionaloptions: ITransaction.OperationOptionsAdd Listeners.
Optionaloptions: IListener.OptionsAdds a page break before the left column of the range. The same as
getPageLayout().addVerticalPageBreak().
Optionaloptions: ITransaction.OperationOptionsBatches 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.
Recalculates THIS sheet — Excel's "Calculate Sheet" (Shift+F9) / Worksheet.Calculate.
Optionalfull: boolean
When true, recalculate every formula on the sheet. Otherwise only the ones whose
inputs changed (plus volatiles), which is what Excel's Shift+F9 does.
Distinct from getEntireRange().calculate(full), which marks the range dirty first and is
therefore always a FORCE for those cells. This is the dirty-respecting sheet-scoped pass.
Only the SEED is scoped to this sheet: dependents on other sheets still recalculate, and volatiles are still workbook-wide. Excel leaves both stale; being more current is the safe direction, and the volatile registry is drained per pass, so skipping them would deregister them outright.
Free all resources associated with the sheet.
IWorksheet.addListeners for closeEvent
Creates a cell that is not including at a coordinate but adopts all rendering.
Cell Update
Optionalcoords: FixableCellCoords
Optional CellCoord
Optionaloptions: CreateCellOptions
How the update is read. See ICell.CreateCellOptions.
A detached ICell
Parses a formula expression and returns a transient formula object anchored to this sheet.
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);
like everything reached through the sheet's getCalculation, a bare reference (A2)
resolves against THIS sheet rather than the selected one.
Removes from a container. This is usually the Workbook. If this is being
used standalone this operation will throw an exception.
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 sheet, this
sheet bound to the batch.
Optionaloptions: string | ITransaction.OperationOptions
Description of the operation or additional options. Used for undo/redo and history.
Work through sheet rather than this one: what is reached through it is part of the batch, as
for IWorkbook.doBatch.
Returns a promise that will resolve to a copy of the current sheet.
Evaluates a formula in the context of the sheet and returns the resulting value.
The formula to evaluate.
Optionaloptions: EvaluateOptions & Partial<CellCoords> & CreateFormulaOptions
Optional evaluation options.
Returns an iterator of ICells that match the results.
This is either a search string or ICellRange.FindOptions.
Returns the regions of the anomalies feature across the whole sheet, in reading order.
Optionaloptions: GetAnomaliesOptionsReturns the ITable created using addAutoTable.
Returns the ICalculation anchored to this sheet.
The engine itself is workbook-wide; this is a view over it that supplies THIS sheet as the context
whenever a caller doesn't name one. So an expression parsed or evaluated through it resolves a bare
reference (A2) against this sheet — not against whichever sheet happens to be selected.
That matters for anything anchored by coords alone, e.g.
sheet.getCalculation().createFormula('=A2+B2', cell.getCoords()): reached through the
workbook (IWorkbook.getCalculation) the same call has no sheet context and falls back to the
active cell's sheet, which makes the parse depend on UI selection state. Pass an explicit
coords.scope to override the anchor (a cross-sheet reference is unaffected either way — it names its
own sheet).
Returns the cell controls on this sheet, such as checkboxes.
Every entry, in drawing order. To put a control on cells or read what is there, use ICellRange.setControl and ICellRange.getControls.
Returns the charts on this sheet.
A view over IWorksheet.getMovables: every chart is the content of a movable, which is what places and names it. Read-only for now — a chart is added by adding a movable with chart content.
The sheet's VBA code name, or null if it has none.
The identifier VBA binds a sheet through — Sheet1.Range("A1") in a macro resolves by code
name, never by tab name. It is a second, independent identity for the sheet: renaming the
tab does not change it, and it is not the sheet's position. Excel's default happens to look
positional (Sheet1, Sheet2, …) but drifts from position the moment sheets are reordered,
inserted or deleted, so it can only be carried — never derived.
Present on any workbook that has, or has ever had, a VBA project: it survives the project
being stripped, so an .xlsx saved down from an .xlsm still carries code names. A workbook
that never had one has none, and this is null throughout.
Read-only. SheetXL preserves what a file declared and never mints one — a code name is
assigned by the VBA editor, and inventing one would create a binding target no macro refers
to. There is deliberately no setCodeName.
Returns the column headers managed by the sheet.
Returns the column width as a font unit.
This is used as an informative tooltip.
Returns the comments and notes on this sheet.
One per cell. The workbook's IWorkbook.getComments walks every sheet's.
Returns a collection of conditional formats that are embedded in this sheet.
Returns a collection of validations that are embedded in this sheet.
Returns the range for the entire sheet.
Optionaloptions: ICellRange.GetRangeOptionsThis can be updated via IWorksheet.setEntireSize.
Returns the IFontCollection the sheet measures text with.
The manual page breaks before rows, in order. The same as
getPageLayout().getHorizontalPageBreaks().
The sheet's id: what formulas and operations identify it by. Unique among all in-memory sheets.
Returns the modules this sheet owns.
A sheet's modules are stored by the sheet rather than tagged with its name, so the state a tag would allow — a module left behind pointing at a sheet that no longer exists — cannot occur: delete the sheet and its modules go with it, which is also what Excel does.
These modules are scoped to the sheet (IModule.getScope), and scope is a visibility rule: a function declared here is not callable from a cell formula, on this sheet or any other. Only globally scoped modules contribute to the formula namespace.
The VBA document module for this sheet lands here, joined to it by IWorksheet.getCodeName — for a document module the module name is the code name.
As with IWorkbook.getScripts, the collection filters to TypeScript unless asked
otherwise; imported VBA is read with getItems({ language: 'vba' }).
Returns a collection of movables that are embedded in this sheet.
Returns the display name for the sheet.
The INameds visible from this sheet — what a formula written here can refer to.
The global items (every table among them, since a table name is always global) plus this sheet's own scoped names, with shadowing resolved: where a sheet-scoped name and a global share a name, only this sheet's is returned, because that is the one a formula here resolves to. Another sheet's scoped names are never included.
Everything is anchored to THIS sheet, not the selected one: getByName resolves against it, and
getByRanges reads unqualified coords as being on it — which is what lets this sheet's own
selection be passed straight in.
Use IWorkbook.getNames for every name in the workbook (a name manager), and IWorksheet.getTables for the tables that LIVE on this sheet — scope here is visibility, never location, so a table anchored to another sheet is still visible from this one.
The row and column groups on this sheet, and how they are laid out.
How the sheet is laid out on printed pages: paper, orientation, scale, margins, headers and footers, the print area and the rows and columns repeated on every page.
The counterpart of Office Scripts' Worksheet.getPageLayout. The manual page breaks are part
of it (IPageLayout.getHorizontalPageBreaks).
Returns the picture interface for the sheet.
Returns the pivot tables laid out on this sheet, in the order they were read.
Read-only for now: each table is carried as it was read and written back unchanged. The workbook's IWorkbook.getPivotTables walks every sheet's.
Returns a collection of ranges that stay editable while this sheet is protected.
Excel's Review → Allow Edit Ranges. Only consulted while IWorksheetProtection.isLocked is true.
Returns the sheet protection.
Returns an ICellRange used to interact with a a rectangular 2D collection of cells at a specific range.
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.GetRangeOptions
Options for the ranges.
Returns a 1×1 cell or an explicit range at the specified absolute sheet coordinates.
OptionalrowEnd: numberOptionalcolumnEnd: numberOptionaloptions: ICellRange.GetRangeOptionsICellRange.getRangeAt for relative coordinates.
Returns the range for a given pixel bounds.
Optionaloptions: ICellRange.GetRangeOptionsReturns an ICellRanges. An ICellRanges is an ordered list of ICellRanges. These are used to interact with a set of contiguous 2D ranges.
Address of the ranges.
Optionaloptions: ICellRange.GetRangeOptions
Options for the ranges.
Returns the uniform regions for the requested features across the whole sheet.
Optionalfeatures: ICellRange.Feature | readonly ICellRange.Feature[]Optionaloptions: GetRegionsOptionsThe partition operator belongs on the thing partitioned, and "where are the blocks in this
sheet" is the question an agent actually has — the ICellRange flavor is how you
constrain that query, not how you start it.
Equivalent to getEntireRange().getRegions(…): the partition reads the feature indexes, so
it costs the used cells rather than the address space.
Returns the current shared resources.
Returns the row headers managed by the sheet.
Returns the selected cell.
Returns a range of cells for the current selection.
Optionaloptions: ICellRange.GetRangeOptionsReturns ranges of cells for the current selection.
Optionaloptions: ICellRange.GetRangeOptionsReturns the current selection.
Returns the sparkline groups on this sheet.
Returns the statistics for the used cells of the sheet.
Optionaloptions: GetStatsOptions
Iterator options the stats are created with — most usefully
{ onError: 'ignore' } so aggregate reads degrade instead of faulting on error values.
Equivalent to getUsedRange().getStats(…) except null-safe — an empty sheet returns
empty statistics (getSize() === 0) rather than forcing the caller to branch on
getUsedRange returning null.
Returns the current shared resources.
Returns IStyleCollection associated with this sheet.
The sheet's synchronized scrolling, or null when it has none.
Returns a collection of tables that are embedded in this sheet.
Returns the current shared resources.
Returns the smallest range within the sheet that contains any used cells.
Optionaloptions: ICellRange.GetRangeOptionsEvery 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.
The manual page breaks before columns, in order. The same as
getPageLayout().getVerticalPageBreaks().
Returns the current view settings View settings determine how the sheet is displayed and interacted with (e.g., frozen panes, zoom level, selection) but do not affect the underlying data itself.
The IWorksheetView object representing the current view settings.
Returns the visibility of the sheet.
Returns true if the sheet has been closed.
Whether conditional formats on this sheet are recalculated as the sheet changes.
Returns if the sheet has been deleted from its container.
Whether formulas on this sheet are entered by Lotus 1-2-3 rules ("Transition formula entry" in Excel's Lotus compatibility settings).
Whether formulas on this sheet are evaluated by Lotus 1-2-3 rules ("Transition formula evaluation" in Excel's Lotus compatibility settings).
Removes every page break before a row. The same as
getPageLayout().removeAllHorizontalPageBreaks().
Optionaloptions: ITransaction.OperationOptionsRemoves every page break before a column. The same as
getPageLayout().removeAllVerticalPageBreaks().
Optionaloptions: ITransaction.OperationOptionsAttempt to scroll the range into view.
The partial coords to scroll to.
Set the entire size of the sheet: where its last column and row are.
Optionalsize: Partial<EntireSize> | null
The number of columns and rows. 'fit' ends that axis where the sheet's content does,
and keeps it there: an insert grows the sheet instead of being refused for pushing content off
the end, and a delete shrinks it. A number fixes the axis at that size. An axis left out keeps
its size and whether it fits; null resets both to the default.
Optionaloptions: ITransaction.OperationOptionsSet the display name for the sheet.
Optionaloptions: ITransaction.OperationOptionsSet the picture interface for the entire sheet.
The picture interface to set for the sheet, or null to remove it.
Optionaloptions: ITransaction.OperationOptionsChange the visibility of the sheet.
Optionalvisibility: boolean | ISheet.VisibilityOptionaloptions: ITransaction.OperationOptionsReturns a JSON representation of the sheet.
Optionaloptions: ToJSONOptions
Options to control the JSON output.
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 sheet 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 sheets and workbooks started loading; a load that fails leaves its stand-in and still settles.
The same point as IWorkbook.whenFontsReady; a sheet without a workbook has it here.
Returns when the sheet is settled: whenCalculationReady and whenFontsReady both hold.
An
IWorksheetrepresents a collection of elements (such as ranges, tables, etc) contained within and visualized through a view.This interface provides methods for accessing its elements and event handling.
Most interactions with a sheet are done using either a range or ranges.
Remarks
While a sheet can be used stand-alone it is typically used within the context of a workbook.
Key Methods
ISheets.