@sheetxl/models
Version:
Models - A Headless javascript spreadsheet library.
449 lines • 14.7 kB
TypeScript
import { CellRangeCoords, CellCoords, RemoveListener } from "@sheetxl/common";
import { SerializableProperties } from "../primitives";
import { ICellModel, ISheetStyle, SheetStyleJSON, ICellValue, CellUpdateValue, SetCellOptions } from "../cell";
import { ISheetModel, SheetJSON, ISheetRange, ICellContainerOptions, ISheetRangeUpdate, ISheetModelOptions, FindCellOptions, ReplaceCellOptions, RangeListenerOptions, SheetRangeEvent } from "../sheet/ISheetModel";
import { IWorkbookView, IWorkbookViewListener } from "./IWorkbookView";
import { SheetCellCoords, SheetCellRangeCoords, SheetCellRangeCoordsAddress, SheetCellCoordsAddress } from "../range";
import { INamedItems, NamedItemsJSON } from "../named";
import { FunctionDescriptorAndScript } from "../formula";
import { IDocTheme, DocThemeValues } from "../theme";
import { TransactionStore, ITransactionStack } from "../transaction";
import { ISharedResourceCollection, SharedResourceJSON } from "../resource";
export interface SheetCoordsValuePair<T> {
coords: SheetCellCoords;
/**
* The value at the address
*/
value: T;
}
/**
* Calculation is the process of computing formulas and then displaying the results
* as values in the cells that contain the formulas
*/
export interface CalcProperties {
calcCompleted: boolean;
calcMode: string;
calcOnSave: boolean;
concurrentCalc: boolean;
concurrentManualCount: boolean;
forceFullCalc: boolean;
fullCalcOnLoad: boolean;
fullPrecision: boolean;
iterate: boolean;
iterateCount: number;
iterateDelta: number;
refMode: string;
}
export interface WorkbookProtection {
workbookPassword?: string;
revisionsPassword?: string;
lockStructure?: boolean;
lockWindows?: boolean;
lockRevision?: boolean;
}
export interface IWorkbookRange extends ISheetRange {
/**
* The bounds for the range.
*/
bounds(): SheetCellRangeCoords;
/**
* The current workbook
*/
workbook(): IWorkbookModel;
readonly isWorkbookRange: true;
}
export interface WorkbookRangeEvent extends SheetRangeEvent {
/**
* The source of the event
*/
getWorkbook(): IWorkbookModel;
/**
* The range that the event is for.
*/
getRange(): IWorkbookRange;
}
/**
* A callback for when a range or sheet has been modified
* @remarks
* It's important to check for null range as it's possible that
* this will be called if a range has been delete
* (either because the rows, columns, or the sheet was deleted)
*/
export type IWorkbookRangeListener = (event: WorkbookRangeEvent) => void;
export type WorkbookJSON = {
sheets: SheetRefJSON[];
style?: SheetStyleJSON;
resources?: SharedResourceJSON[];
view?: SerializableProperties<IWorkbookView>;
theme?: SerializableProperties<DocThemeValues>;
definedNames?: NamedItemsJSON;
scripts?: FunctionDescriptorAndScript;
calc?: SerializableProperties<CalcProperties>;
protection?: SerializableProperties<WorkbookProtection>;
date1904?: boolean;
};
export declare enum WorkbookFindCellScope {
/**
* Search the entire workbook
*/
Workbook = "workbook",
/**
* Search the current sheet or range
*/
Sheet = "sheet"
}
export interface FindWorkbookCellOptions extends Omit<FindCellOptions, 'to'> {
/**
* @defaultValue WorkbookFindCellScope.Sheet
*/
scope?: WorkbookFindCellScope;
}
export interface ReplaceWorkbookCellOptions extends ReplaceCellOptions {
findOptions: FindWorkbookCellOptions;
}
export interface IWorkbookModelOptions extends ICellContainerOptions {
/**
* Hook to allow for custom sheet creation
*
* @param name
* @param initialState
* @param options
* @returns ISheetModel
*/
sheetCreator?: (name: string, initialState?: SheetJSON | ISheetRangeUpdate | ICellValue[][], options?: ISheetModelOptions) => ISheetModel;
/**
* This is a function that will return a sheet name given a 1-based index.
* @defaultValue `Sheet${index}`
*/
sheetNameCreator?: (index: number) => string;
onGetCellAt?: (sheetName: string, key: string, cell: ICellModel) => void;
theme?: IDocTheme;
}
export interface IWorkbookModelListener extends IWorkbookViewListener {
/**
* Called when any cell has changed.
* @deprecated. Use the individual sheet listeners.
*/
onCellsChange?(): void;
/**
* Called when the sheetRefs have changed.
*/
onSheetsRefsChange?(update: SheetRef[] | null): void;
/**
* Called when the workbook theme has changed.
*/
onThemeChange?(update: IDocTheme | null): void;
/**
* Called when the workbook protection has changed.
* @remarks
* This is different from the sheet protection.
*/
onProtectionChange?(protection: WorkbookProtection): void;
/**
* Called when the workbook is closed.
*/
onClose?(model: IWorkbookModel): void;
/**
* Notify that everything has changed.
*/
onAllChange?(): void;
}
export declare enum SheetVisibility {
Visible = "visible",
Hidden = "hidden",
VeryHidden = "veryHidden"
}
/**
* The reference to a sheet with in a workbook.
* These are used for finding sheet and determining
* it's location/visibility within a workbook.
*/
export interface SheetRef {
/**
* This is a unique id for the sheet.
* Note - It is not the index and will not change if the sheet order is adjusted
*/
id: number;
/**
* The display name of the sheet
*/
name: string;
/**
* @defaultValue SheetVisibility.Visible
*/
visibility: SheetVisibility;
sheet: ISheetModel;
}
export interface SheetRefJSON {
name: string;
/**
* @defaultValue SheetVisibility.Visible
*/
visibility?: SheetVisibility;
sheet?: SheetJSON;
}
/**
* Most operations that operate on a sheet take a SheetKey that is either:
* 1. The sheet instance
* 2. The sheet ref
* 3. The sheet name
* 4. The sheet index - Note - This is the index for the elements that are visible.
*/
export type SheetKey = ISheetModel | SheetRef | string | number;
/**
* The workbook model is the top level model that contains resources to
* a collection of the sheets, named ranges, and formulas.
*/
interface IWorkbookModel extends ITransactionStack {
/**
* Adds a sheet at the given index with the given name.
* This will throw an exception if the sheetName is invalid
* or already used.
*
* @param sheetName
* @param index
* @returns ISheetModel the newly added/created ISheetModel.
*/
addSheet(sheetName?: string, index?: number): ISheetModel;
/**
* Delete the sheet.
*
* @param key ISheetModel, SheetRef, sheetName, or index
*/
deleteSheet(key: SheetKey): ISheetModel;
/**
* Return the sheet for the given key.
* If no key is specified then the current active sheet is returned.
* @param key
*/
getSheet(key?: SheetKey): ISheetModel;
/**
* Fires onSheetRefsChange
*/
setSheetName(key: SheetKey, sheetName: string): ISheetModel;
/**
* Fires onSheetRefsChange
*/
setSheetVisibility(key: SheetKey, visibility: SheetVisibility): ISheetModel;
moveSheet(indexFrom: number, indexTo: number): ISheetModel;
/**
* Will create a duplicate of the the specified sheet or the current active sheet if no sheet is specified.
* @param key
*/
duplicateSheet(key?: SheetKey): Promise<ISheetModel>;
/**
* Get the sheet reference. @see {@link SheetRef}
* Will return null if not available ether because it was not found or did not match the visibility
*
* @param key SheetKey
* @param visibility
*/
getSheetRef(key: SheetKey, visibility?: SheetVisibility): SheetRef;
/**
* Return a sheetRef by it's unique id.
* @param id
*/
getSheetRefById(id: number): SheetRef;
/**
* Get all of the Sheet handles within the workbook for a given SheetVisibility.
* By default this will only return the visible sheets
* @param visibility
*/
getSheetRefs(visibility?: SheetVisibility): SheetRef[];
/**
* Ordered list of sheetNames. This will only return SheetVisibility.Visible
*/
getSheetNames(): string[];
/**
* Set the sheet to active. If this sheet was not Visible it will be made visible
* Fires onWorkbookSelectionChange
*/
setActiveSheet(key: SheetKey): ISheetModel;
/**
* Returns the currently active sheet within the workbook
*/
getActiveSheetIndex(): number;
/**
* Returns the active cell as an A1 style reference
*/
getActiveAddressCoordsA1(): string;
/**
* Return the active address as a SheetCellCoords
*/
getActiveAddressCoords(): SheetCellCoords;
/**
* Returns a single value for the found result or null if not found.
* @param options
*/
find(findText: string, options?: FindWorkbookCellOptions): SheetCoordsValuePair<ICellModel> | null;
/**
* Replaces all options that match.
* @param options
*/
replace(findText: string, replaceText: string, options?: ReplaceWorkbookCellOptions): {
next: SheetCellCoordsAddress;
count: number;
};
/**
* This will activate the next sheet unless there is only one.
* This is a convenience method for @see {@link setActiveSheet}.
*/
activateNextSheet(): ISheetModel;
/**
* This will activate the previous sheet unless there is only one.
* This is a convenience method for @see {@link setActiveSheet}.
*/
activatePreviousSheet(): ISheetModel;
/**
* Given the name return a valid name that closely matches.
* @param sheetName
*/
findValidSheetName(sheetName: string): string;
/**
* The view specific properties.
*/
getView(): IWorkbookView;
/**
* Views have their own lifecycle because in a collaborative
* environment each user can have their own view.
*/
setView(view: IWorkbookView): void;
/**
* Returns the current sheet style associated with this Workbook.
*/
sheetStyle(): ISheetStyle;
/**
* Returns the current shared resources
*/
getResources(): ISharedResourceCollection;
/**
* Get the current theme
*/
getTheme(): IDocTheme;
/**
* Set the current theme
* @remarks
*
* If null sets back to the default theme.
* This will not fire theme updated event.
*/
setTheme(theme: IDocTheme): IDocTheme;
/**
* Is date resolution 1904 instead of 1900 based.
* @see {@link https://support.microsoft.com/en-us/office/date-systems-in-excel-e7fe7167-48a9-4b96-bb53-5612a800b487}
*/
is1904DateSystem(): boolean;
/**
* Determine if dates should be 1904 instead of 1900 based
* @defaultValue false
*/
set1904DateSystem(is1904Date: boolean): void;
/**
* Return the current transaction store for the workbook.
* @remarks
* Custom transaction stores must be provided via the constructor.
*/
getTransactionStore(): TransactionStore;
/**
* Add a listener for workbook events
* @param listener
*/
addListener(listener: IWorkbookModelListener): RemoveListener;
/**
* Return the getCell for the given address or the active cell if no address is specified.
* @remarks
* This will never return null.
*/
getCell(address?: SheetCellCoordsAddress): ICellModel;
/**
* Set a single value. This is a convenience method that wraps setCellPairs
* to provide a simpler interface. For higher performance
* use @see {@link ISheetRange.update} or @see {@link ISheetModel.setCellPairs} directly.
*
* @remarks
* This operation also runs synchronously.
*/
setCell(address: SheetCellCoordsAddress, value: CellUpdateValue, options?: SetCellOptions): ICellModel;
/**
* Returns all cells bounded with the specified range.
* These allow for interaction with the cells.
*
* @remarks
* If empty will return all the cells
* @see {@link ISheetRange}
*/
getRange(address?: SheetCellRangeCoordsAddress): IWorkbookRange;
/**
* Return an array of cell ranges for the given address.
* @param address
*/
decodeAddress(address: SheetCellRangeCoordsAddress | SheetCellCoords | CellRangeCoords | CellCoords): SheetCellRangeCoords[];
/**
* If null then there is no protection
* @defaultValue null
*/
getProtection(): Readonly<WorkbookProtection> | null;
/**
* Set the protection for the workbook.
*
* @remarks Pass null to clear all protections.
* @param protection
*/
setProtection(protection: Partial<WorkbookProtection> | null): void;
/**
* Return the names of the ranges.
* These are sorted/filtered by type then by name.
*/
getNamedItems(): INamedItems;
/**
* Return any user defined functions stored with the workbook.
* @remark
*/
getUserDefinedFunctions(): FunctionDescriptorAndScript;
/**
* Set the user defined functions store with the workbook. If null
* is passed in than these are cleared.
* @param descriptorAndScript
*/
setUserDefinedFunctions(descriptorAndScript: FunctionDescriptorAndScript): void;
/**
* Add a listener for a specific range.
*
* @remarks
* By default insert/remove of headers or sheets will alter the range listener.
* To see the actual bounds use the range in the callback.
*
* @param address
* @param listener @see {@link IWorkbookRangeListener}
* @param options @see {@link RangeListenerOptions}
*/
addRangeListener(address: SheetCellRangeCoordsAddress, listener: IWorkbookRangeListener, options?: RangeListenerOptions): RemoveListener;
/**
* Load the state from a JSON
*/
fromJSON(json: WorkbookJSON): void;
/**
* Serialize the workbook to a JSON.
*/
toJSON(): Promise<WorkbookJSON>;
/**
* This returns any custom workbook options that are provided in constructor.
*/
readonly options: IWorkbookModelOptions;
/**
* Close the workbook and release any resources.
* No further operations are allowed after a close
*/
close(): void;
/**
* Indicates if the model has been closed
*/
isClosed(): boolean;
/**
* Used for runtime reflection.
*/
readonly isIWorkbookModel: true;
}
export default IWorkbookModel;
export { IWorkbookModel };
//# sourceMappingURL=IWorkbookModel.d.ts.map