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.constructorProperties
Section titled “Properties”columns
Section titled “columns”columns: GridSize[];colWidths
Section titled “colWidths”colWidths: Record<string, number>;comments
Section titled “comments”comments: ThreadedComment[];Threaded comments.
Top-level comments may have replies. Each top-level comment is linked to a single cell in the
sheet. Comment bodies are plain text. Structured annotations such as @mentions and hyperlinks
are expressed via the optional runs array, which references character ranges within the text.
defaults
Section titled “defaults”defaults: object;colWidth?
Section titled “colWidth?”optional colWidth: number;rowHeight?
Section titled “rowHeight?”optional rowHeight: 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;notes: Note[];Cell notes.
Each note is linked to a single cell and contains plain text content.
rowHeights
Section titled “rowHeights”rowHeights: Record<number, number>;rows: GridSize[];views?
Section titled “views?”optional views: WorksheetView[];Accessors
Section titled “Accessors”cellCount
Section titled “cellCount”Get Signature
Section titled “Get Signature”get cellCount(): number;Returns
Section titled “Returns”number
dataTableCells
Section titled “dataTableCells”Get Signature
Section titled “Get Signature”get dataTableCells(): ReadonlySet<Cell>;Returns
Section titled “Returns”ReadonlySet<Cell>
Methods
Section titled “Methods”_parseFormulasAndInferArrayType()
Section titled “_parseFormulasAndInferArrayType()”_parseFormulasAndInferArrayType( refsNeedingRecalc, assumeArrayFormulas?, ctx?): void;Parse formulas and infer array type for all formula cells. Also collects HYPERLINK cells that need recalculation into the provided array.
Parameters
Section titled “Parameters”refsNeedingRecalc
Section titled “refsNeedingRecalc”assumeArrayFormulas?
Section titled “assumeArrayFormulas?”boolean
Returns
Section titled “Returns”void
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.emitgetBounds()
Section titled “getBounds()”getBounds(): SlimRange;Returns
Section titled “Returns”getCell()
Section titled “getCell()”getCell(cellID): Cell | null;Parameters
Section titled “Parameters”cellID
Section titled “cellID”string
Returns
Section titled “Returns”Cell | null
getCellByCoords()
Section titled “getCellByCoords()”getCellByCoords( row, col, willEdit, formulaCell): Cell | null;Parameters
Section titled “Parameters”number
number
willEdit
Section titled “willEdit”boolean = false
formulaCell
Section titled “formulaCell”boolean = false
Returns
Section titled “Returns”Cell | null
getCellByID()
Section titled “getCellByID()”getCellByID(cellID): Cell | null;Parameters
Section titled “Parameters”cellID
Section titled “cellID”string
cell address in A1 form without prefix
Returns
Section titled “Returns”Cell | null
getCellByRange()
Section titled “getCellByRange()”getCellByRange(range): Cell | null;Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”Cell | null
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>
getComments()
Section titled “getComments()”getComments(options): ThreadedComment[];Get threaded comments on this sheet with optional filtering.
Parameters
Section titled “Parameters”options
Section titled “options”FilterOptions = {}
Returns
Section titled “Returns”ThreadedComment[]
getNotes()
Section titled “getNotes()”getNotes(): Note[];Gets the notes attached to cells within this worksheet.
Copies are returned to prevent external mutation of the sheet’s notes.
Returns
Section titled “Returns”Note[]
getSize()
Section titled “getSize()”getSize(): [number, number];Returns
Section titled “Returns”[number, number]
getSpillAnchoredAtRange()
Section titled “getSpillAnchoredAtRange()”getSpillAnchoredAtRange(range): Range | null;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”Range | null
getViews()
Section titled “getViews()”getViews(): WorksheetView[];Gets the worksheet’s saved view configurations (selected cell, zoom, layout, etc).
Copies are returned to prevent external mutation of the sheet’s views.
Returns
Section titled “Returns”WorksheetView[]
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.hasListenersCall 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.hasListenersiterAnchorCellsInRange()
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.listenerCountCall 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.listenerCountlisteners()
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.listenersmergeCells()
Section titled “mergeCells()”mergeCells(rangeStr): void;Merge a range of cells. The range must span at least 2 cells and must not overlap any existing merge.
Existing values in non-anchor cells are discarded (cleared to empty). The anchor cell’s value is left as-is; no values are moved into it.
Parameters
Section titled “Parameters”rangeStr
Section titled “rangeStr”string
range in A1 notation, e.g. “A1:B2”
Returns
Section titled “Returns”void
Throws
Section titled “Throws”if the range is a single cell or overlaps an existing merge
nextBoundaryByCoords()
Section titled “nextBoundaryByCoords()”nextBoundaryByCoords( row, col, direction): | { 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; };} | null;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”| {
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;
};
}
| null
nextBoundaryByID()
Section titled “nextBoundaryByID()”nextBoundaryByID(cellAddr, direction): | { 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; };} | null;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”| {
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;
};
}
| null
nextValueCellByCoords()
Section titled “nextValueCellByCoords()”nextValueCellByCoords( row, col, direction): Cell | null;Find the next non-blank cell in the given direction relative to (row, col). The search ignores the cell at exactly (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”Cell | null
Non-blank cell or null
nextValueCellByID()
Section titled “nextValueCellByID()”nextValueCellByID(cellAddr, direction): Cell | null;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”Cell | null
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.offCall 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.offCall 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.offon(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.ononce()
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.onceresolveArea()
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
unmergeCells()
Section titled “unmergeCells()”unmergeCells(rangeStr): void;Unmerge cells. Any existing merge that overlaps the given range is fully removed. If no merges overlap, this is a no-op.
Parameters
Section titled “Parameters”rangeStr
Section titled “rangeStr”string
range in A1 notation, e.g. “A1:B2”
Returns
Section titled “Returns”void