Workbook

Workbook root model: sheets, defined names, properties, calc settings.

51 exports from 13 source files

Workbook

Name	Type	Description
`opts?`	`{ date1904?: boolean }`

getSheet function

Look up a Worksheet by title. Returns undefined for missing names or chartsheets.

function getSheet(wb: Workbook, title: string): Worksheet | undefined

Parameters

Name	Type	Description
`wb`	`Workbook`
`title`	`string`

Returns

Worksheet | undefined

Look up a Worksheet by its 0-based tab-strip index. Returns undefined both for an out-of-range index and for a slot holding a chartsheet, so one check on the result covers the bounds test and the sheet-kind discrimination.

function getSheetByIndex(wb: Workbook, idx: number): Worksheet | undefined

Parameters

Name	Type	Description
`wb`	`Workbook`
`idx`	`number`

Returns

Worksheet | undefined

getSheetState function

src/workbook/workbook.ts:501

Look up the current visibility state. Throws on unknown title.

function getSheetState(wb: Workbook, title: string): SheetState

Parameters

Name	Type	Description
`wb`	`Workbook`
`title`	`string`

Returns

SheetState

getWorkbookCellsByKind function

src/workbook/workbook.ts:758

Workbook-wide value-kind histogram. Sums countCellsByKind across every Worksheet (chartsheets contribute no cells). Buckets have the same shape as the per-worksheet result; an empty workbook returns all-zero counts.

function getWorkbookCellsByKind(wb: Workbook): CellsByKindCounts

Parameters

Name	Type	Description
`wb`	`Workbook`

Returns

CellsByKindCounts

getWorkbookStats function

src/workbook/workbook.ts:712

function getWorkbookStats(wb: Workbook): WorkbookStats

Parameters

Name	Type	Description
`wb`	`Workbook`

Returns

WorkbookStats

iterWorksheets function

src/workbook/workbook.ts:1080

Iterate over every Worksheet in the workbook (skips chartsheets). Yields each worksheet in tab-strip order.

function iterWorksheets(wb: Workbook): IterableIterator<Worksheet>

Parameters

Name	Type	Description
`wb`	`Workbook`

Returns

IterableIterator<Worksheet>

listCustomXmlParts function

src/workbook/workbook.ts:1388

Read-only view onto the customXml/* pass-through parts.

function listCustomXmlParts(wb: Workbook): { content: Uint8Array; path: string }[]

Parameters

Name	Type	Description
`wb`	`Workbook`

Returns

{ content: Uint8Array; path: string }[]

moveSheet function

src/workbook/workbook.ts:559

Move a sheet to a new tab-strip position. toIndex is clamped to [0, sheets.length - 1]. Adjusts activeSheetIndex so the same sheet stays active across the move.

function moveSheet(wb: Workbook, title: string, toIndex: number): void

Parameters

Name	Type	Description
`wb`	`Workbook`
`title`	`string`
`toIndex`	`number`

Returns

void

removeSheet function

src/workbook/workbook.ts:431

Remove a sheet and its local defined names; reindex surviving scopes. No-op for an unknown title. Formula text is not rewritten.

function removeSheet(wb: Workbook, title: string): void

Parameters

Name	Type	Description
`wb`	`Workbook`
`title`	`string`

Returns

void

renameSheet function

src/workbook/workbook.ts:454

Rename a sheet from oldTitle to newTitle. Throws if no sheet matches oldTitle, or if newTitle collides with an existing sheet (Excel requires sheet names to be unique within a workbook). Formula text and defined-name expressions are retained verbatim; callers must update sheet references. PivotTable sources (ws.pivotTables[].source.sheet) do follow the rename.

function renameSheet(wb: Workbook, oldTitle: string, newTitle: string): void

Parameters

Name	Type	Description
`wb`	`Workbook`
`oldTitle`	`string`
`newTitle`	`string`

Returns

void

setActiveSheet function

src/workbook/workbook.ts:441

Set the active sheet by title; throws on unknown title.

function setActiveSheet(wb: Workbook, title: string): void

Parameters

Name	Type	Description
`wb`	`Workbook`
`title`	`string`

Returns

void

setCellAtAddress function

src/workbook/workbook.ts:856

Set a single cell by sheet-qualified A1 address. Throws on malformed addresses, missing sheets, or range inputs.

The address names the sheet, so there is no Worksheet argument. Use setCellByCoord(ws, 'A1', value) from @office-kit/xlsx/worksheet when the worksheet is already in hand.

function setCellAtAddress(wb: Workbook, address: string, value: CellValue): Cell

Parameters

Name	Type	Description
`wb`	`Workbook`
`address`	`string`
`value`	`CellValue`

Returns

Cell

setSheetState function

src/workbook/workbook.ts:477

Set the visibility state on a sheet by title. Throws on unknown title. Refuses to hide the last visible sheet: an .xlsx with every sheet hidden fails to open in Excel ("Excel cannot use the object linking and embedding features because no sheet is visible"). Catching it here keeps the workbook recoverable instead of producing a save Excel will reject.

function setSheetState(wb: Workbook, title: string, state: SheetState): void

Parameters

Name	Type	Description
`wb`	`Workbook`
`title`	`string`
`state`	`SheetState`

Returns

void

sheetNames function

src/workbook/workbook.ts:409

Every sheet title in tab-strip order, chartsheets included, so a title in the list is not necessarily one getSheet resolves.

function sheetNames(wb: Workbook): string[]

Parameters

Name	Type	Description
`wb`	`Workbook`

Returns

string[]

Calc properties

src/workbook/calc-properties.ts

makeCalcProperties function

src/workbook/calc-properties.ts:34

function makeCalcProperties(opts?: CalcProperties): CalcProperties

Parameters

Name	Type	Description
`opts?` = {}	`CalcProperties`

Returns

CalcProperties

setCalcMode function

src/workbook/calc-properties.ts:50

Set the recalculation mode. 'auto' is Excel's default; 'manual' requires F9 to recompute formulas; 'autoNoTable' recomputes everything except data-table cells.

function setCalcMode(wb: Workbook, mode: CalcMode): void

Parameters

Name	Type	Description
`wb`	`Workbook`
`mode`	`CalcMode`

Returns

void

setCalcOnSave function

src/workbook/calc-properties.ts:71

Toggle "Recalculate workbook before saving" (workbook-level).

function setCalcOnSave(wb: Workbook, on: boolean): void

Parameters

Name	Type	Description
`wb`	`Workbook`
`on`	`boolean`

Returns

void

setFullCalcOnLoad function

src/workbook/calc-properties.ts:83

Toggle "Recalculate workbook on load". A calculating app (Excel, LibreOffice, Google Sheets) then recomputes every formula on open instead of trusting the cached values in the file, which is what a generated workbook wants when the producer could not compute a cached value for every formula, or is not certain the ones it wrote are current. Viewers that never calculate ignore the flag and keep showing only what is cached.

function setFullCalcOnLoad(wb: Workbook, on: boolean): void

Parameters

Name	Type	Description
`wb`	`Workbook`
`on`	`boolean`

Returns

void

setFullPrecision function

src/workbook/calc-properties.ts:88

Toggle "Set precision as displayed" (false = full 15-digit precision).

function setFullPrecision(wb: Workbook, on: boolean): void

Parameters

Name	Type	Description
`wb`	`Workbook`
`on`	`boolean`

Returns

void

setIterativeCalc function

src/workbook/calc-properties.ts:59

Toggle iterative calculation (Excel's "Enable iterative calculation" option). When enable is true and count / delta are provided, they replace the default Excel limits (100 iterations, 0.001 delta).

function setIterativeCalc(wb: Workbook, enable: boolean, opts?: { count?: number; delta?: number }): void

Parameters

Name	Type	Description
`wb`	`Workbook`
`enable`	`boolean`
`opts?` = {}	`{ count?: number; delta?: number }`

Returns

void

Defined names

src/workbook/defined-names.ts

addDefinedName function

src/workbook/defined-names.ts:63

Add a workbook-scope or sheet-scope defined name. If a defined name with the same name (and scope) already exists, it's replaced — Excel allows one workbook-scope and one per-sheet-scope name, but not two with the same scope. Returns the resulting DefinedName.

function addDefinedName(wb: Workbook, opts: Partial<DefinedName> & { name: string; value: string }): DefinedName

Parameters

Name	Type	Description
`wb`	`Workbook`
`opts`	`Partial<DefinedName> & { name: string; value: string }`

Returns

DefinedName

getDefinedName function

src/workbook/defined-names.ts:121

Look up a defined name by identifier and (optional) sheet scope.

function getDefinedName(wb: Workbook, name: string, scope?: number): DefinedName | undefined

Parameters

Name	Type	Description
`wb`	`Workbook`
`name`	`string`
`scope?`	`number`

Returns

DefinedName | undefined

getDefinedNameTarget function

src/workbook/defined-names.ts:141

Resolve a defined name's value into one or more DefinedNameTargets. Comma-separated values (e.g. _xlnm.Print_Titles typically sets Sheet!$1:$1,Sheet!$A:$A) yield one entry per leg; a plain Sheet!A1:B5 yields a single-element array.

A leg with no sheet prefix on a sheet-scoped name resolves to the sheet the scope points at. Files written by other tools, and by earlier versions of setPrintArea, store _xlnm.Print_Area that way.

Returns undefined when the name doesn't exist; throws when the value can't be parsed (e.g. a constant or a non-range formula — defined names are sometimes used for things like =42 or =SUM(A:A) which aren't ranges).

function getDefinedNameTarget(wb: Workbook, name: string, scope?: number): DefinedNameTarget[] | undefined

Parameters

Name	Type	Description
`wb`	`Workbook`
`name`	`string`
`scope?`	`number`

Returns

DefinedNameTarget[] | undefined

listDefinedNames function

src/workbook/defined-names.ts:213

Every defined name. Pass { scope } to narrow to workbook-scope (scope: 'workbook') or one specific sheet (scope: 0); omit the option, or pass 'all', to list every name. 'workbook' is the only spelling that narrows to the unscoped ones: the option is number | 'workbook' | 'all', so there is no undefined to pass for them.

A narrowed call filters, so it hands back a fresh array. Listing all hands back a read-only view of the live one, which addDefinedName and renameDefinedName are visible through and which removeDefinedNames replaces outright.

function listDefinedNames(wb: Workbook, opts?: { scope?: number | "all" | "workbook" }): readonly DefinedName[]

Parameters

Name	Type	Description
`wb`	`Workbook`
`opts?` = {}	`{ scope?: number \| "all" \| "workbook" }`

Returns

readonly DefinedName[]

makeDefinedName function

src/workbook/defined-names.ts:27

function makeDefinedName(opts: Partial<DefinedName> & { name: string; value: string }): DefinedName

Parameters

Name	Type	Description
`opts`	`Partial<DefinedName> & { name: string; value: string }`

Returns

DefinedName

removeDefinedName function

src/workbook/defined-names.ts:194

Remove a defined name by identifier + scope. Returns true if any entry was removed.

function removeDefinedName(wb: Workbook, name: string, scope?: number): boolean

Parameters

Name	Type	Description
`wb`	`Workbook`
`name`	`string`
`scope?`	`number`

Returns

boolean

Shared strings

src/workbook/shared-strings.ts

addSharedString function

src/workbook/shared-strings.ts:55

Insert a string and return its index. Idempotent: calling with the same value twice gives the same index. Empty strings are deduped just like everything else.

function addSharedString(table: SharedStringsTable, value: string): number

Parameters

Name	Type	Description
`table`	`SharedStringsTable`
`value`	`string`

Returns

number

getSharedStringAt function

src/workbook/shared-strings.ts:90

Read a shared-string by its 0-based index. Returns undefined for out-of-range. Rich-text entries surface their concatenated plain text so callers that want only the textual body don't need to know about the discriminated union.

function getSharedStringAt(table: SharedStringsTable, index: number): string | undefined

Parameters

Name	Type	Description
`table`	`SharedStringsTable`
`index`	`number`

Returns

string | undefined

getSharedStringIndex function

src/workbook/shared-strings.ts:80

Look up a shared-string index by its literal text. Returns undefined for unknown values.

function getSharedStringIndex(table: SharedStringsTable, value: string): number | undefined

Parameters

Name	Type	Description
`table`	`SharedStringsTable`
`value`	`string`

Returns

number | undefined

makeSharedStrings function

src/workbook/shared-strings.ts:46

function makeSharedStrings(): SharedStringsTable

Returns

SharedStringsTable

sharedStringCount function

src/workbook/shared-strings.ts:98

Number of unique entries in the SST.

function sharedStringCount(table: SharedStringsTable): number

Parameters

Name	Type	Description
`table`	`SharedStringsTable`

Returns

number

Function groups

src/workbook/function-groups.ts

makeFunctionGroup function

src/workbook/function-groups.ts:18

function makeFunctionGroup(name: string): FunctionGroup

Parameters

Name	Type	Description
`name`	`string`

Returns

FunctionGroup

makeFunctionGroups function

src/workbook/function-groups.ts:20

function makeFunctionGroups(opts?: Partial<FunctionGroups>): FunctionGroups

Parameters

Name	Type	Description
`opts?` = {}	`Partial<FunctionGroups>`

Returns

FunctionGroups

Smart tags

src/workbook/smart-tags.ts

makeSmartTagProperties function

src/workbook/smart-tags.ts:20

function makeSmartTagProperties(opts?: SmartTagProperties): SmartTagProperties

Parameters

Name	Type	Description
`opts?` = {}	`SmartTagProperties`

Returns

SmartTagProperties

makeSmartTagType function

src/workbook/smart-tags.ts:22

function makeSmartTagType(opts?: SmartTagType): SmartTagType

Parameters

Name	Type	Description
`opts?` = {}	`SmartTagType`

Returns

SmartTagType

Views

src/workbook/views.ts

makeCustomWorkbookView function

src/workbook/views.ts:73

function makeCustomWorkbookView(opts: Pick<CustomWorkbookView, "guid" | "name" | "windowWidth" | "windowHeight" | "activeSheetId"> & Partial<CustomWorkbookView>): CustomWorkbookView

Parameters

Name	Type	Description
`opts`	`Pick<CustomWorkbookView, "guid" \| "name" \| "windowWidth" \| "windowHeight" \| "activeSheetId"> & Partial<CustomWorkbookView>`

Returns

CustomWorkbookView

makeWorkbookView function

src/workbook/views.ts:38

function makeWorkbookView(opts?: WorkbookView): WorkbookView

Parameters

Name	Type	Description
`opts?` = {}	`WorkbookView`

Returns

WorkbookView

File recovery

src/workbook/file-recovery.ts

makeFileRecoveryProperties function

src/workbook/file-recovery.ts:18

function makeFileRecoveryProperties(opts?: FileRecoveryProperties): FileRecoveryProperties

Parameters

Name	Type	Description
`opts?` = {}	`FileRecoveryProperties`

Returns

FileRecoveryProperties

File sharing

src/workbook/file-sharing.ts

Name	Type	Description
`opts?` = {}	`FileSharing`

File version

src/workbook/file-version.ts

makeFileVersion function

src/workbook/file-version.ts:20

function makeFileVersion(opts?: FileVersion): FileVersion

Parameters

Name	Type	Description
`opts?` = {}	`FileVersion`

Returns

FileVersion

Persons

src/workbook/persons.ts

makePerson function

src/workbook/persons.ts:20

Build a person with a new id. Without an account Excel records the display name as the user id under provider None, so that is the default here too.

function makePerson(opts: { displayName: string; providerId?: string; userId?: string }): Person

Parameters

Name	Type	Description
`opts`	`{ displayName: string; providerId?: string; userId?: string }`

Returns

Person

Protection

src/workbook/protection.ts

makeWorkbookProtection function

src/workbook/protection.ts:37

function makeWorkbookProtection(opts?: WorkbookProtection): WorkbookProtection

Parameters

Name	Type	Description
`opts?` = {}	`WorkbookProtection`

Returns

WorkbookProtection

Workbook properties

src/workbook/workbook-properties.ts

makeWorkbookProperties function

src/workbook/workbook-properties.ts:44

function makeWorkbookProperties(opts?: WorkbookProperties): WorkbookProperties

Parameters

Name	Type	Description
`opts?` = {}	`WorkbookProperties`

Returns

WorkbookProperties