- Spreadsheet docs
- Developers
TypeScript
The TypeScript declarations that ship with 8sheets and its components, the types you will use, and the few places that are typed loosely.
@8sheets/core ships its declarations, generated from the source, so import { mountWorkbook } from '@8sheets/core' is typed with no setting, paths entry or @types package. The React, Vue and Angular components ship their own types, built on the core ones. Plain JavaScript projects get the same completions in editors that read declarations.
Typed in each framework
JavaScript
import { mountWorkbook, type SheetsWorkbook, type SheetRange } from '@8sheets/core';
type MountOptions = NonNullable<Parameters<typeof mountWorkbook>[1]>;
type StylePatch = SheetRange['style'];
const options: MountOptions = { chrome: 'light', parts: { titleBar: false } };
const header: StylePatch = { bold: true, fill: { theme: 'accent1' }, color: '#FFFFFF' };
const wb: SheetsWorkbook = await mountWorkbook(document.querySelector<HTMLElement>('#sheet')!, options);
wb.activeSheet.range('A1:D1').style = header;
wb.events.on('cells-changed', (e) => console.log(e.count));React
import { useRef } from 'react';
import { Sheet, type SheetRef, type SheetOptions, type SheetsEvent } from '@8sheets/react';
import type { SheetsWorkbook } from '@8sheets/core';
const options: SheetOptions = { chrome: 'light', parts: { titleBar: false } };
export function Budget() {
const sheet = useRef<SheetRef>(null);
const onReady = (wb: SheetsWorkbook) => { wb.activeSheet.range('A1').values = [['Item', 'Cost']]; };
const onCells = (e: SheetsEvent) => console.log(e.count, sheet.current?.workbook?.activeSheet.name);
return (
<div style={{ height: 480 }}>
<Sheet ref={sheet} options={options} onReady={onReady} onCellsChanged={onCells} />
</div>
);
}Vue
<script setup lang="ts">
import { Sheet, useSheet, type SheetOptions, type SheetEventObject } from '@8sheets/vue';
import type { SheetsWorkbook } from '@8sheets/core';
const options: SheetOptions = { chrome: 'light', parts: { titleBar: false } };
const { sheet, workbook } = useSheet(); // ShallowRef<SheetExposed | null>, ComputedRef<SheetsWorkbook | null>
function onReady(wb: SheetsWorkbook) {
wb.activeSheet.range('A1').values = [['Item', 'Cost']];
}
function onCells(e: SheetEventObject) {
console.log(e.count, workbook.value?.activeSheet.name);
}
</script>
<template>
<Sheet ref="sheet" :options="options" style="height: 480px" @ready="onReady" @cells-changed="onCells" />
</template>Angular
import { Component } from '@angular/core';
import { SheetComponent, type SheetEventPayload, type SheetOptions, type SheetsWorkbook } from '@8sheets/angular';
import type { SheetRange } from '@8sheets/core';
@Component({
selector: 'app-budget',
imports: [SheetComponent],
template: `<eight-sheet class="grid" [options]="options" (ready)="onReady($event)" (cellsChanged)="onCells($event)" />`,
styles: `.grid { height: 480px; }`,
})
export class Budget {
options: SheetOptions = { chrome: 'light', parts: { titleBar: false } };
header: SheetRange['style'] = { bold: true, fill: { theme: 'accent1' } };
onReady(wb: SheetsWorkbook) {
wb.activeSheet.range('A1:B1').style = this.header;
}
onCells(e: SheetEventPayload) {
console.log(e['count']);
}
}In Angular, import from @8sheets/core with import type only: the component loads the library at run time, and a value import would bundle a second copy.
The types you will use
| From | Types |
|---|---|
@8sheets/core | SheetsWorkbook, SheetHandle (a sheet), SheetRange, SheetTable, SheetObject, SheetChart, SheetShape, SheetPivot, SheetSlicer, CommentThread, FunctionsApi, NamesApi, History, CommandManager, ThemeApi, UserDirectory, SheetPrint, SheetEvent |
@8sheets/react | SheetProps, SheetRef, SheetOptions, SheetsEvent, SheetEventHandler |
@8sheets/vue | SheetOptions, SheetEventName, SheetEventObject, SheetExposed |
@8sheets/angular | SheetOptions, SheetsWorkbook, SheetEventPayload |
The package exports only its entry point, so types declared inside it but not exported by name are reached through the classes that use them:
import type { SheetRange, SheetHandle, mountWorkbook } from '@8sheets/core';
type MountOptions = NonNullable<Parameters<typeof mountWorkbook>[1]>; // parts, chrome, theme, …
type PartsOption = NonNullable<MountOptions['parts']>;
type StylePatch = SheetRange['style']; // bold, fill, numFmt, …
type CellValue = SheetRange['values'][number][number]; // number | string | boolean | Date | null
type TableOptions = NonNullable<Parameters<SheetHandle['addTable']>[1]>;
type ValidationRule = Parameters<SheetHandle['setValidation']>[1];
Where the types are loose
The declarations are generated from JSDoc in the source, and a few parts are typed broadly:
- Event objects in
wb.events.on(type, fn)areany, so their fields (count,cells(),sheet,text) aren't checked; event names are plain strings. The list of all events gives each event's fields. The component types are a little tighter: React'sSheetsEventand Vue'sSheetEventObjectdeclaretype,workbook,cancelledandcancel(), and Vue'sSheetEventNamelists every event name. - Options beyond the mount options are
Record<string, any>, so a misspelled option name passes the compiler.mountWorkbookandsetOptionscheck every key at run time and throw aRangeErrorfor an unknown one. wb.statusBar,wb.nameBoxandwb.settingsare declared, as… | undefined, because only a mounted workbook has them: usewb.statusBar?.setMessage(…)or check them first.sheet.chartsandsheet.shapesgive the raw records, typed loosely. Usesheet.chartHandles,sheet.shapeHandles,sheet.chart()andsheet.shape()for typedSheetChartandSheetShapehandles.- Conditional formatting rules for
addConditionalFormatRuleare typed withtype,operator,formulasandstopIfTrueonly, so rules with other file-format fields, such as{ type: 'top10', rank: 3 }or acolorScale, need a cast in TypeScript (as any, or a wider type of your own). They work at run time. - Cell type options are
{ type } & Record<string, any>: the type name is checked at run time (aRangeErrorfor an unknown one), and the options are cleaned, not checked. - Rules in the file format's own shape passed to
addValidationandaddConditionalFormatare typedobject. The newersetValidationandaddConditionalFormatRuletake typed rules, which you can name withParameters<SheetHandle['setValidation']>[1].
Node projects
The declarations name DOM types such as HTMLElement, because the same API mounts in a page. A Node project that checks library types (skipLibCheck: false) needs "DOM" in lib; with skipLibCheck: true, the default in most templates, nothing is needed.