WorkSheet
An object describing a sheet of A1-addressable spreadsheet cells.
Extends
Section titled “Extends”emitter
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new WorkSheet(
name,workbookKey,index,styles,hidden,workbookType):WorkSheet
Parameters
Section titled “Parameters”string
workbookKey
Section titled “workbookKey”number
number
styles
Section titled “styles”hidden
Section titled “hidden”0 | 1 | 2
workbookType
Section titled “workbookType”The origin of the workbook (Excel, Google Sheets, CSV, etc).
"unknown" | "airtable" | "notion" | "smartsheet" | "csv" | "excel" | "form-submissions" | "google-sheets" | "native"
Returns
Section titled “Returns”WorkSheet
Overrides
Section titled “Overrides”EventEmitter.constructor
Properties
Section titled “Properties”_cells
Section titled “_cells”_cells:
Cells
columns
Section titled “columns”columns:
GridSize[]
colWidths
Section titled “colWidths”colWidths:
Record<string,number>
defaults
Section titled “defaults”defaults:
object
colWidth?
Section titled “colWidth?”
optionalcolWidth:number
rowHeight?
Section titled “rowHeight?”
optionalrowHeight:number
drawings
Section titled “drawings”drawings:
DrawingCSF[]
hidden
Section titled “hidden”hidden:
0|1|2
index:
number
locallyScopedNames
Section titled “locallyScopedNames”locallyScopedNames:
Record<string,DefinedName> ={}
merged_cells
Section titled “merged_cells”merged_cells:
string[]
merges
Section titled “merges”merges:
Record<string, [number,number]>
name:
string
rowHeights
Section titled “rowHeights”rowHeights:
Record<number,number>
rows:
GridSize[]
showGridLines
Section titled “showGridLines”showGridLines:
boolean=true
views?
Section titled “views?”
optionalviews:WorksheetView[]
workbookKey
Section titled “workbookKey”workbookKey:
number
Accessors
Section titled “Accessors”cellCount
Section titled “cellCount”Get Signature
Section titled “Get Signature”get cellCount():
number
Returns
Section titled “Returns”number
tableName
Section titled “tableName”Get Signature
Section titled “Get Signature”get tableName():
null|string
Returns
Section titled “Returns”null | string
Methods
Section titled “Methods”_convertToStructuredSheet()
Section titled “_convertToStructuredSheet()”_convertToStructuredSheet(
table):void
Parameters
Section titled “Parameters”Table
Returns
Section titled “Returns”void
_setRowHeight()
Section titled “_setRowHeight()”_setRowHeight(
rowNum,height):boolean
Parameters
Section titled “Parameters”rowNum
Section titled “rowNum”number
0-based row index
height
Section titled “height”number
non-negative
Returns
Section titled “Returns”boolean
true if visibility changed (the row height was previously 0 and now isn’t, or vice versa)
Throws
Section titled “Throws”if rowNum is not present in the sheet, or if height is a negative number
_splitUpOverlappingRangeWrites()
Section titled “_splitUpOverlappingRangeWrites()”_splitUpOverlappingRangeWrites(
ref):undefined|Cell
Look for range write nodes in the R-Tree that overlap with the given range, and if there are any, split them up such that the remaining set of range write nodes cover any cells previously covered, but do not overlap the given range. If the given range is a single-cell address, and there exists a formula cell at that address (which will have been neutralized by one of the overlapping range writes), then reinstate the cell R-tree node for that cell (else it would not be covered by any R-tree cell).
Parameters
Section titled “Parameters”Returns
Section titled “Returns”undefined | Cell
the cell whose neutralized formula was reinstated, if any
_updateColumnMetadata()
Section titled “_updateColumnMetadata()”_updateColumnMetadata(
column,wasInserted,count):void
Adjust the columns attribute after insertion/deletion of one or more columns
Parameters
Section titled “Parameters”column
Section titled “column”number
0-based column index of the first inserted/deleted column
wasInserted
Section titled “wasInserted”boolean
true if inserted, false if deleted
number = 1
number of affected columns
Returns
Section titled “Returns”void
Throws
Section titled “Throws”if column is negative or not an integer, or if count is less than 1 or not an integer
_updateParsedFormula()
Section titled “_updateParsedFormula()”_updateParsedFormula(
cell,ctx?,validateNow?):void
Precondition: formula parser has finished importing (formulaParserReady has resolved).
NOTE: this function does not assert this precondition; callers must do so.
Parameters
Section titled “Parameters”validateNow?
Section titled “validateNow?”boolean = true
Returns
Section titled “Returns”void
_writeCellData()
Section titled “_writeCellData()”_writeCellData(
cellLocation,cellData,ctx?):object
Write the given cell data attributes (.v, .f, etc.) to an existing or new cell at the given ID.
NOTE: clients should update cells using Workbook.writeCellData; this should be called only from Workbook.
If cell value is an error value, normalize it to the corresponding the singleton error value in errorTable.
If the cell has a formula, it is parsed and (if parsing succeeds) the AST is stored in the cell object.
Precondition: formula parser has finished importing (formulaParserReady has resolved).
Parameters
Section titled “Parameters”cellLocation
Section titled “cellLocation”zero-based sheet coordinates of cell to write
number
number
cellData
Section titled “cellData”object with attributes to write to the cell
evaluation context (for looking up lambdas in formula, to not misreport calls to unsupported functions)
Returns
Section titled “Returns”object
the existing or new cell, and any other ranges which may have been affected by masking/unmasking
cell:
Cell
changedRanges
Section titled “changedRanges”changedRanges:
Range[]
Throws
Section titled “Throws”if precondition is not satisfied (the formula parser has not finished importing)
clearCellsByRange()
Section titled “clearCellsByRange()”clearCellsByRange(
range): (CellVertexId|RangeVertexId)[]
Parameters
Section titled “Parameters”Returns
Section titled “Returns”(CellVertexId | RangeVertexId)[]
The places that got changed. This can include cells outside of
range, which may have been changed in ways other than clearing them,
because of spill ranges getting unblocked by the clearing of range.
emit()
Section titled “emit()”emit(
event, …arguments_):Emitter
Emit an event, invoking all handlers registered for it.
Parameters
Section titled “Parameters”string
The name of the event to emit.
arguments_
Section titled “arguments_”…any[]
Arguments to pass to the event handlers.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.emit
getBounds()
Section titled “getBounds()”getBounds():
SlimRange
Returns
Section titled “Returns”getCell()
Section titled “getCell()”getCell(
cellID):null|Cell
Parameters
Section titled “Parameters”cellID
Section titled “cellID”string
Returns
Section titled “Returns”null | Cell
getCellByCoords()
Section titled “getCellByCoords()”getCellByCoords(
row,col,willEdit,formulaCell):null|Cell
Parameters
Section titled “Parameters”number
number
willEdit
Section titled “willEdit”boolean = false
formulaCell
Section titled “formulaCell”boolean = false
Returns
Section titled “Returns”null | Cell
getCellByID()
Section titled “getCellByID()”getCellByID(
cellID):null|Cell
Parameters
Section titled “Parameters”cellID
Section titled “cellID”string
cell address in A1 form without prefix
Returns
Section titled “Returns”null | Cell
getCellByRange()
Section titled “getCellByRange()”getCellByRange(
range):null|Cell
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”null | Cell
getCells()
Section titled “getCells()”getCells(
includeStyleOnly?):IterableIterator<Cell>
Returns an iterator of all cells contained in this sheet, even individual cells within spilled ranges.
Parameters
Section titled “Parameters”includeStyleOnly?
Section titled “includeStyleOnly?”boolean = false
include cells that have never had a value but only style info
Returns
Section titled “Returns”IterableIterator<Cell>
getColumns()
Section titled “getColumns()”getColumns():
object[]
Returns
Section titled “Returns”object[]
getDataCellByCoords()
Section titled “getDataCellByCoords()”getDataCellByCoords(
row,col):null|Cell
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”null | Cell
getSize()
Section titled “getSize()”getSize(): [
number,number]
Returns
Section titled “Returns”[number, number]
getSpillAnchoredAtRange()
Section titled “getSpillAnchoredAtRange()”getSpillAnchoredAtRange(
range):null|Range
Get the area which a spilled range covers, given a reference to the spilled range’s anchor cell.
Parameters
Section titled “Parameters”Returns
Section titled “Returns”null | Range
hasListeners()
Section titled “hasListeners()”Call Signature
Section titled “Call Signature”hasListeners(
event):boolean
Check if there are any handlers registered for a specific event.
Parameters
Section titled “Parameters”string
The name of the event.
Returns
Section titled “Returns”boolean
true if there are one or more handlers, false otherwise.
Inherited from
Section titled “Inherited from”EventEmitter.hasListeners
Call Signature
Section titled “Call Signature”hasListeners():
boolean
Check if there are any handlers registered for any event.
Returns
Section titled “Returns”boolean
true if there are one or more handlers for any event, false otherwise.
Inherited from
Section titled “Inherited from”EventEmitter.hasListeners
isStructuredSheet()
Section titled “isStructuredSheet()”isStructuredSheet():
boolean
Returns
Section titled “Returns”boolean
iterAnchorCellsInRange()
Section titled “iterAnchorCellsInRange()”iterAnchorCellsInRange(
range):IterableIterator<Cell>
Iterate all cells in range, except spilled cells
Parameters
Section titled “Parameters”Returns
Section titled “Returns”IterableIterator<Cell>
iterFormulaCells()
Section titled “iterFormulaCells()”iterFormulaCells():
IterableIterator<Cell>
Yield all formula cells.
Returns
Section titled “Returns”IterableIterator<Cell>
iterValueCellsInColumn()
Section titled “iterValueCellsInColumn()”iterValueCellsInColumn(
columnIndex,maxRow):Generator<Cell,void,unknown>
Parameters
Section titled “Parameters”columnIndex
Section titled “columnIndex”number
maxRow
Section titled “maxRow”number = Infinity
Returns
Section titled “Returns”Generator<Cell, void, unknown>
listenerCount()
Section titled “listenerCount()”Call Signature
Section titled “Call Signature”listenerCount(
event):number
Get the count of listeners for a specific event.
Parameters
Section titled “Parameters”string
The name of the event.
Returns
Section titled “Returns”number
The number of listeners for the event.
Inherited from
Section titled “Inherited from”EventEmitter.listenerCount
Call Signature
Section titled “Call Signature”listenerCount():
number
Get the count of all event handlers in total.
Returns
Section titled “Returns”number
The total number of event handlers.
Inherited from
Section titled “Inherited from”EventEmitter.listenerCount
listeners()
Section titled “listeners()”listeners(
event): (…arguments_) =>void[]
Retrieve the event handlers registered for a specific event.
Parameters
Section titled “Parameters”string
The name of the event.
Returns
Section titled “Returns”(…arguments_) => void[]
An array of functions registered as handlers for the event.
Inherited from
Section titled “Inherited from”EventEmitter.listeners
makeCell()
Section titled “makeCell()”makeCell(
cellLocation):Cell
Parameters
Section titled “Parameters”cellLocation
Section titled “cellLocation”number
number
Returns
Section titled “Returns”moveCells()
Section titled “moveCells()”moveCells(
otherSheet,from,to):object
Parameters
Section titled “Parameters”otherSheet
Section titled “otherSheet”WorkSheet
Returns
Section titled “Returns”object
changedRefsInFrom
Section titled “changedRefsInFrom”changedRefsInFrom:
Reference[]
changedRefsInTo
Section titled “changedRefsInTo”changedRefsInTo:
Reference[]
nextBoundaryByCoords()
Section titled “nextBoundaryByCoords()”nextBoundaryByCoords(
row,col,direction):null| {further: {cell:null;col:number;id:string;row:number; };nearer: {cell:Cell;col:number;id:string;row:number; }; } | {further: {cell:Cell;col:number;id:string;row:number; };nearer: {cell:null;col:number;id:string;row:number; }; }
Find the next boundary between an empty and non empty cell in the given direction relative to (row, col).
Parameters
Section titled “Parameters”number
number
direction
Section titled “direction”string
Direction relative to (row, col) to search in; can be ‘left’, ‘right’, ‘up’, ‘down’, or case variations of those.
Returns
Section titled “Returns”null | { further: { cell: null; col: number; id: string; row: number; }; nearer: { cell: Cell; col: number; id: string; row: number; }; } | { further: { cell: Cell; col: number; id: string; row: number; }; nearer: { cell: null; col: number; id: string; row: number; }; }
nextBoundaryByID()
Section titled “nextBoundaryByID()”nextBoundaryByID(
cellAddr,direction):null| {further: {cell:null;col:number;id:string;row:number; };nearer: {cell:Cell;col:number;id:string;row:number; }; } | {further: {cell:Cell;col:number;id:string;row:number; };nearer: {cell:null;col:number;id:string;row:number; }; }
Find the next boundary between an empty and non empty cell in the given direction relative to the given cell.
Parameters
Section titled “Parameters”cellAddr
Section titled “cellAddr”string
Cell which search is relative to
direction
Section titled “direction”string
Direction relative to cellAddr to search in; can be ‘left’, ‘right’, ‘up’, ‘down’,
or case variations of those.
Returns
Section titled “Returns”null | { further: { cell: null; col: number; id: string; row: number; }; nearer: { cell: Cell; col: number; id: string; row: number; }; } | { further: { cell: Cell; col: number; id: string; row: number; }; nearer: { cell: null; col: number; id: string; row: number; }; }
nextValueCellByCoords()
Section titled “nextValueCellByCoords()”nextValueCellByCoords(
row,col,direction):null|Cell
Find the next non-blank cell in the given direction relative to (row, col). The search ignores the cell at exacly (row, col).
Parameters
Section titled “Parameters”number
Row index
number
Column index
direction
Section titled “direction”string
Direction relative to (row, col) to search in; can be ‘left’, ‘right’, ‘up’, ‘down’, or case variations of those.
Returns
Section titled “Returns”null | Cell
Non-blank cell or null
nextValueCellByID()
Section titled “nextValueCellByID()”nextValueCellByID(
cellAddr,direction):null|Cell
Find the next non-blank cell in the given direction relative to the given
cell. The search ignores the cell at cellAddr.
Parameters
Section titled “Parameters”cellAddr
Section titled “cellAddr”string
Cell which search is relative to
direction
Section titled “direction”string
Direction relative to cellAddr to search in; can be ‘left’, ‘right’, ‘up’, ‘down’,
or case variations of those.
Returns
Section titled “Returns”null | Cell
Non-blank cell or null
Call Signature
Section titled “Call Signature”off(
event,listener):Emitter
Remove a specific event handler for a specified event.
Parameters
Section titled “Parameters”string
The name of the event.
listener
Section titled “listener”(…arguments_) => void
The specific handler function to remove.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.off
Call Signature
Section titled “Call Signature”off(
event):Emitter
Remove all event handlers for a specified event.
Parameters
Section titled “Parameters”string
The name of the event for which to remove all handlers.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.off
Call Signature
Section titled “Call Signature”off():
Emitter
Remove all event handlers for all events.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.off
on(
event,listener):Emitter
Register an event handler that listens to a specified event.
Parameters
Section titled “Parameters”string
The name of the event to listen to.
listener
Section titled “listener”(…arguments_) => void
The function to execute when the event is emitted.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.on
once()
Section titled “once()”once(
event,listener):Emitter
Register a one-time event handler for a specified event.
Parameters
Section titled “Parameters”string
The name of the event to listen to.
listener
Section titled “listener”(…arguments_) => void
The function to execute once when the event is emitted.
Returns
Section titled “Returns”Emitter
The Emitter instance for method chaining.
Inherited from
Section titled “Inherited from”EventEmitter.once
prepareCellMerges()
Section titled “prepareCellMerges()”prepareCellMerges():
void
Returns
Section titled “Returns”void
reset()
Section titled “reset()”reset():
void
Returns
Section titled “Returns”void
resolveArea()
Section titled “resolveArea()”resolveArea<
O>(range,options):ResolveAreaResult<O>
Type Parameters
Section titled “Type Parameters”O extends ResolveAreaOptions<Readonly<{ returnBoxed: boolean; returnCells: boolean; returnLambda: boolean; }>>
Parameters
Section titled “Parameters”options
Section titled “options”O = ...
Returns
Section titled “Returns”ResolveAreaResult<O>
setColumnWidth()
Section titled “setColumnWidth()”setColumnWidth(
column,width):void
Parameters
Section titled “Parameters”column
Section titled “column”number
0-based column index
number
non-negative
Returns
Section titled “Returns”void
Throws
Section titled “Throws”if column or width is negative, or column is not an integer
setDataFromCSF()
Section titled “setDataFromCSF()”setDataFromCSF(
csfSheetData,ctx?,options?):Reference[]
Fast path for setting data from CSF format directly, bypassing JSF conversion. This provides significantly better performance when the source data is in CSF format.
Parameters
Section titled “Parameters”csfSheetData
Section titled “csfSheetData”CSFSheetWithJSFCells
Sheet data in CSF format
Evaluation context for formula parsing
options?
Section titled “options?”PopulateOptions = {}
Population options (willRecalc, assumeArrayFormulas)
Returns
Section titled “Returns”References to cells that need recalculation
Precondition
Section titled “Precondition”The formula parser must be loaded before calling this method
Throws
Section titled “Throws”if precondition is not satisfied (the formula parser has not finished importing)
setDataFromJSF()
Section titled “setDataFromJSF()”setDataFromJSF(
jsfSheetData,ctx?,jsfContext?,options?):Reference[]
Populate this sheet with data from JSF (native path).
Cells are expanded on-demand using workbook-level JSF context (formulas, styles, dateAdjust).
Precondition: formula parser has finished importing (formulaParserReady has resolved).
Parameters
Section titled “Parameters”jsfSheetData
Section titled “jsfSheetData”JSFWorksheetRelaxed
the JSF sheet data
context for looking up names (to not record calls to named lambdas as calls to unsupported functions)
jsfContext?
Section titled “jsfContext?”workbook-level JSF context (provides formulas array, styles array, and dateAdjust for cell expansion)
dateAdjust
Section titled “dateAdjust”number
formulas?
Section titled “formulas?”string[]
styles
Section titled “styles”StyleRelaxed[]
options?
Section titled “options?”PopulateOptions = {}
populate options
Returns
Section titled “Returns”Throws
Section titled “Throws”if precondition is not satisfied (the formula parser has not finished importing)
setIndex()
Section titled “setIndex()”setIndex(
index):void
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”void
visitFormulaCellsIntersecting()
Section titled “visitFormulaCellsIntersecting()”visitFormulaCellsIntersecting(
range,callback):void
Visits all formula cells within the given range. Also includes formula cells that spill into the range.
Parameters
Section titled “Parameters”callback
Section titled “callback”CallbackWithStop<Cell>
Returns
Section titled “Returns”void