WorkbookView

A single workbook view, bound to its index in workbook.views. Provides access to the active sheet and per-sheet view state (selection, layout, zoom, frozen panes).

Obtain via workbook.views.get(index) / .require(index); do not construct directly.

All methods throw if the view has been removed from the workbook.

The getters fill in defaults: a field the stored sheet view omits is reported as the value that applies in its absence. getSheetView is the raw reader, returning only the fields the view stores, for callers that must tell “unset” from “explicitly set to the default”.

Example

const view = workbook.views.require();
view.setActiveSheetName('Inputs');
view.setSelection('Inputs', {
  activeCell: 'B5',
  activeRanges: ['B5:D10', 'F1'],
});

Constructors

Constructor

new WorkbookView(workbook, index): WorkbookView;

Parameters

workbook

Workbook

index

number

Returns

WorkbookView

Accessors

index

Get Signature

get index(): number;

The zero-based index of this workbook view.

Returns

number

Methods

freezePanes()

freezePanes(sheetName, panes): void;

Freezes panes for one particular sheet in this workbook view.

Parameters

sheetName

string

Name of the sheet whose panes should be frozen

panes

Omit<WorksheetViewFrozenPanes, "type"> & object

Details of how the sheet view’s panes should be frozen

Returns

void

Throws

If a sheet with the given name doesn’t exist

Throws

If this view has been orphaned from its workbook

Throws

If the frozen panes are invalid (see validateFrozenPanes)

---

getActiveSheetIndex()

getActiveSheetIndex(): number;

Index of the active sheet. Returns 0 when not explicitly set (OOXML default).

Returns

number

---

getActiveSheetName()

getActiveSheetName(): string | null;

Name of the active sheet, or null if the stored index does not resolve to a sheet. Returns the first sheet when not explicitly set (OOXML default).

Note: deleting a sheet does not update the stored activeSheet index, so this may return null or the wrong sheet after a deletion.

Returns

string | null

---

getFrozenPanes()

getFrozenPanes(sheetName): WorksheetViewFrozenPanes | null;

Return the frozen panes for a given sheet in this workbook view, if the sheet has them.

Parameters

sheetName

string

Name of the sheet whose frozen panes you want

Returns

WorksheetViewFrozenPanes | null

A copy of the JSF frozen panes, or null if the sheet has none

Throws

If a sheet with the given name doesn’t exist

Throws

If this view has been orphaned from its workbook

---

getSelection()

getSelection(sheetName): ViewSelection;

Returns the active cell and active ranges for a sheet.

Unlike getSheetView, activeCell is always present: when the stored view has none it is resolved from the stored ranges (see anchorCellOf), and 'A1' when there is no range to anchor on. A stored activeCell is reported as is, even one outside the stored ranges.

Parameters

sheetName

string

Returns

ViewSelection

Throws

if sheetName does not exist

---

getSheetView()

getSheetView(sheetName): WorksheetView | null;

Returns the raw stored sheet view, or null if no view entry exists.

Unlike getSelection, this doesn’t include activeCell if it’s not set on the view explicitly.

Parameters

sheetName

string

Returns

WorksheetView | null

Throws

if sheetName does not exist

---

hasFrozenPanes()

hasFrozenPanes(sheetName): boolean;

Returns true if the given sheet has frozen panes in this workbook view, false otherwise.

Parameters

sheetName

string

Name of the sheet you want to check for frozen panes

Returns

boolean

Throws

If a sheet with the given name doesn’t exist

Throws

If this view has been orphaned from its workbook

---

setActiveSheetName()

setActiveSheetName(sheetName): void;

Set the active sheet by name.

Parameters

sheetName

string

Returns

void

Throws

if sheetName is empty or does not exist

---

setSelection()

setSelection(sheetName, options?): void;

Sets the active cell and active ranges for a sheet. This replaces the full selection state — any field you omit is cleared, not preserved. Passing activeCell: 'A1' (or omitting it) with no activeRanges resets the selection to default.

Parameters

sheetName

string

options?

activeCell?

string

activeRanges?

string[]

Returns

void

Throws

if the sheet is not found

Throws

if activeCell is not a valid cell reference

Throws

if activeRanges contains an invalid range reference

Throws

if activeCell is not contained within any of activeRanges

---

unfreezePanes()

unfreezePanes(sheetName): void;

Unfreezes panes for one particular sheet in this workbook view.

If a sheet with the given name exists but doesn’t have frozen panes, this is a no-op.

Parameters

sheetName

string

Name of the sheet whose frozen panes should be removed

Returns

void

Throws

If a sheet with the given name doesn’t exist

Throws

If this view has been orphaned from its workbook