@jspreadsheet/parser
Version:
Convert XLSX to JSS spreadsheet parser. This is a premium extension and requires a license.
2,051 lines • 108 kB
TypeScript
/**
* Official Type definitions for Jspreadsheet Pro v11
* https://jspreadsheet.com/docs
*/
declare function jspreadsheet(element: HTMLElement|HTMLDivElement|null, options: jspreadsheet.Spreadsheet) : Array<jspreadsheet.worksheetInstance>;
declare namespace jspreadsheet {
let current: worksheetInstance | null;
/** ClientID */
let clientId: string | null;
/** License string. Use setLicense to define the license */
let license: string | null;
/** Default row height for a table */
let defaultRowHeight: number | string;
/** Default column width for a table */
let defaultColWidth: number;
/** Column index default width. Default: 50 */
let indexColumnWidth: number;
/** The container that holds all spreadsheet instances in the screen */
let spreadsheet: spreadsheetInstance[];
/** Advance excel like helpers */
let helpers: Helpers;
/** Native editors. You can have extra entries not defined here when working with custom editors */
let editors: Editors;
/** History tracker controllers */
let history: History;
/** Clipboard controller */
let clipboard: ClipBoardMethods;
/** Shortcuts */
let shortcuts: Shortcuts;
/** Get the worksheet instance by its name */
let getWorksheetInstanceByName: GetWorksheetInstanceByNameFunction;
/** Picker */
let picker: Picker;
/** Pause calculations */
function calculations(state: boolean) : void;
/** Define the translations from english to any other language. Ex.{ 'hello': 'Ola', 'Successfully Saved': 'Salvo com sucesso' } */
let setDictionary: SetDictionary;
/** Set the license */
function setLicense(license: string|object) : void;
/** Set extensions to the JSS spreadsheet or null to disable all extensions. Example { formula, parser, render } */
function setExtensions(extensions: object | null, options?: object) : void;
/** Destroy the spreadsheet. Full destroy will clear all JSS controllers and is not possible to re-create a new spreadsheet if true is used, until refresh the page. */
function destroy(element: HTMLElement | spreadsheetInstance, fullDestroy?: boolean) : void;
/** Destroy all the spreadsheets in all namespaces **/
function destroyAll() : void;
/** Jspreadsheet parser extension. More info at: https://jspreadsheet.com/products */
let parser: ((options?: parseOptions) => void) | undefined;
/** Jspreadsheet formula extension. More info at: https://jspreadsheet.com/products */
let formula: ((expression: string, variables: object, x: number, y: number, instance: worksheetInstance) => void) | undefined;
/** Jspreadsheet parser extension. More info at: https://jspreadsheet.com/products */
let render: ((element: HTMLElement, options: any) => void) | undefined;
/** Jspreadsheet forms extension. More info at: https://jspreadsheet.com/products */
let forms: ((options: any) => void) | undefined;
/** Jspreadsheet search extension. More info at: https://jspreadsheet.com/products */
let search: (() => void) | undefined;
/** Jspreadsheet importer extension. More info at: https://jspreadsheet.com/products */
let importer: (() => void) | undefined;
/** Jspreadsheet validations extension. More info at: https://jspreadsheet.com/products */
let validations: (() => void) | undefined;
/** Jspreadsheet bar extension. More info at: https://jspreadsheet.com/products */
let bar: ((options?: { suggestions?: boolean }) => void) | undefined;
/** Jspreadsheet charts extension. More info at: https://jspreadsheet.com/products */
let charts: (() => void) | undefined;
/** Jspreadsheet shapes extension. More info at: https://jspreadsheet.com/products */
let shapes: (() => void) | undefined;
/** Get the current version */
function version(): {
version: string,
edition: string,
host: string,
license: string,
print: () => [string],
};
type GetWorksheetInstanceByNameFunction = (worksheetName?: string | null | undefined, namespace?: string) => worksheetInstance | Record<string, worksheetInstance>;
interface Picker {
(el: HTMLElement, options: PickerOptions) : void;
cancel: () => void;
click: () => void;
e: Record<string, any> | null | undefined;
end: () => void;
getRangeFromNode: () => RangeCoords | null | undefined;
hasEvent: (focus?: boolean) => Record<string, any> | null | undefined;
input: (element: HTMLElement) => void;
keydown: (event: KeyboardEvent) => void;
palette: (colors: string[]) => void;
selection: (x1: number, y1: number, x2: number, y2: number, event: Event) => boolean | undefined;
start: (element: HTMLElement) => void;
update: (element: HTMLElement) => void;
validSelection: (acceptNewNodeOnly?: boolean) => boolean;
}
interface SetDictionary {
(dictionary: object) : void;
translate: (text: string, substitutions: string[]) => string;
}
interface Shortcuts {
get: (event: object) => Function | null;
set: (shortcut: string, method: Function | null) => void;
}
interface PickerOptions {
/** picker creates a range selection component. formula expect to be a formula starting with '=' */
type?: 'formula' | 'picker';
/** When the value is changed */
onchange?: (element: HTMLElement, mouseEvent: object) => void;
/** Each time the selection is updated */
onupdate?: (element: HTMLElement, mouseEvent: object) => void;
}
type RangeCoords = [number, number, number, number];
interface ClipBoard {
worksheet: worksheetInstance,
value: string,
selection: RangeCoords,
highlighted: RangeCoords | RangeCoords[],
cut: boolean,
hash: string | null,
}
interface ClipBoardMethods {
set(text: string, isCut?: boolean | undefined, coords?: RangeCoords, reset?: boolean): void,
get(): ClipBoard,
reset(resetClipboard?: boolean): void,
}
/** Common properties for all media types */
interface MediaBase {
// GUID string
id: string;
type: 'image' | 'chart' | 'shape';
top?: number;
left?: number;
width?: number;
height?: number;
zIndex?: number;
// Cell anchor if applicable
cellAnchor?: string;
}
/** Options for image media */
interface MediaImageOptions {
src: string;
absolute?: boolean;
}
/** Options for chart media (unchanged) */
interface MediaChartOptions {
type: 'area' | 'bar' | 'column' | 'doughnut' | 'filledRadar' | 'histogram' | 'line' | 'pareto' |
'percentArea' | 'percentBar' | 'percentColumn' | 'pie' | 'radar' | 'scatter' |
'stackedArea' | 'stackedBar' | 'stackedColumn';
range: string; // e.g., "A1:B10"
headers?: boolean;
orientation?: 0 | 1;
labels?: number;
datasets?: number[];
title?: {
text: string;
align?: 'left' | 'center' | 'right';
font?: { size?: number; bold?: boolean };
};
subtitle?: {
text: string;
align?: 'left' | 'center' | 'right';
};
legend?: {
display?: boolean;
position?: 'top' | 'bottom' | 'left' | 'right';
align?: 'left' | 'center' | 'right';
};
series?: Array<{
color?: string;
borderColor?: string;
yAxis?: 'left' | 'right';
}>;
axis?: {
base?: { title?: { text: string } };
side?: { title?: { text: string } };
};
cutout?: number;
separation?: {
type: 'piece-width';
value: number;
};
}
/** Options for shape media (updated with your list) */
interface MediaShapeOptions {
type: 'simpleLine' | 'lineWithArrow' | 'doubleArrowLine' | 'elbowConnector' | 'elbowArrowConnector' |
'doubleArrowElbowConnector' | 'curvedElbowConnector' | 'curvedArrowConnector' | 'curvedDoubleArrowConnector' |
'rectangle' | 'rounded-rectangle' | 'singleCutCornerRectangle' | 'doubleCutCornerRectangle' |
'oppositeCutCornerRectangle' | 'roundedTopRightRectangle' | 'roundedTopLeftRectangle' |
'roundedTopRightBottomLeftRectangle' | 'ellipse' | 'triangle' | 'right-triangle' | 'parallelogram' |
'trapezium' | 'diamond' | 'pentagon' | 'hexagon' | 'heptagon' | 'octagon' | 'decagon' |
'ovalInterfaceIcon' | 'cutCircle' | 'circlewithtoprightoutsideangle' | 'doubleLineSquare' |
'doubledtoprighangle' | 'doubleLineShape' | 'mouldingCrown' | 'crossIcon' | 'plaqueShape' |
'cylinderShape' | 'cubeShape' | 'bevelShape' | 'donutShape' | 'blockShape' | 'blockArk' |
'smileyFace' | 'heart' | 'lightningBolt' | 'sun' | 'crescentMoon' | 'cloud' | 'arcCurve' |
'leftSquareBrackets' | 'rightSquareBrackets' | 'squareBracketsPair' | 'leftFlowerBracket' |
'rightFlowerBracket' | 'flowerBrackets' | 'rightBlockArrow' | 'leftBlockArrow' | 'upBlockArrow' |
'downBlockArrow' | 'upDownArrow' | 'leftRightArrow' | 'quadArrow' | 'leftRightUpArrow' |
'bentArrow' | 'uTurnArrow' | 'leftUpArrow' | 'bentUpArrow' | 'curvedRightArrow' | 'curvedLeftArrow' |
'curvedUpArrow' | 'curvedDownArrow' | 'stripedRightArrow' | 'notchedRightArrow' | 'pentagonArrow' |
'chevron' | 'rightArrowCallout' | 'downArrowCallout' | 'leftArrowCallout' | 'upArrowCallout' |
'leftRightArrowCallout' | 'quadArrowCallout' | 'circularArrow' | 'plus' | 'minus' | 'multiplication' |
'division' | 'equal' | 'notEqualTo' | 'predefinedTask' | 'internalStorage' | 'document' |
'multitaskingDocuments' | 'terminator' | 'preparation' | 'manualInput' | 'manualOperation' |
'offpageConnector' | 'card' | 'punchedTape' | 'swimmingJunction' | 'orShape' | 'collateShape' |
'sortShape' | 'extractShape' | 'mergeShape' | 'storedDataShape' | 'delayShape' |
'sequentialAccessStorageShape' | 'directAccessStorage' | 'displayShape';
backgroundColor?: string;
borderColor?: string;
fontColor?: string;
borderWidth?: number;
text?: string;
}
/** Discriminated union for Media based on type */
interface MediaImage extends MediaBase {
type: 'image';
src: string;
options?: MediaImageOptions;
}
interface MediaChart extends MediaBase {
type: 'chart';
options?: MediaChartOptions;
}
interface MediaShape extends MediaBase {
type: 'shape';
options?: MediaShapeOptions;
}
/** Unified Media type */
type Media = MediaImage | MediaChart | MediaShape;
/** New column object */
interface newColumn {
column?: number,
data?: any[],
options: Column,
}
/* New row object */
interface newRow {
row?: number,
data?: any[],
options: Row,
[key: string]: any,
}
/** Advance comments */
interface Comment {
/** User unique identification */
user_id?: number,
/** User name */
name?: string,
/** Comment content */
comments?: string,
/** Date of the comments */
date?: string,
}
/** Global History */
interface History {
(changes: Record<string, any>): void;
/** History index cursor */
index: number;
/** History items */
actions: Record<string, any>[];
/** When true the next item is cascaded in the same existing history element */
cascade: boolean;
/** When true no history will be added to the tracker */
ignore: boolean;
/** A history redo or undo is in progress */
progress: 'undo' | 'redo' | null;
/** Undo last action */
undo: () => void;
/** Redo most recent action */
redo: () => void;
/** Reset history tracker */
reset: () => void;
}
/** Validation entry */
interface Validation {
/** Excel-like range format Sheet1!A1:A6 */
range: string;
/** Validation type */
type: 'number' | 'text' | 'date' | 'list' | 'textLength' | 'empty' | 'notEmpty';
/** Validation action can be a warning or reject when the condition are not match or a format when the condition matches */
action: 'warning' | 'reject' | 'format';
/** Criteria to be match */
criteria:
| '='
| '!='
| '>='
| '>'
| '<='
| '<'
| 'between'
| 'not between'
| 'valid date'
| 'valid email'
| 'valid url'
| 'contains'
| 'not contains'
| 'begins with'
| 'ends with'
/** Custom message to the user */
text?: string;
/** Ignore blank cells */
allowBlank?: boolean;
/** For type: format you can apply some CSS when condition is matched */
format?: Record<string, string>;
/** For type: format you can add a class when condition is matched */
className?: string;
/** Array with two positions, the second position used when criteria is between or not between. */
value?: number[] | string[],
/** Make sure run that as a dropdown */
dropdown: true,
}
/** Validations update format */
interface Validations {
/** Index position in the array of validations */
index?: number | null;
/** The validation definition object */
value: Validation;
}
/** Native editors */
interface Editors {
/** Create a DOM element for a cell edition */
createEditor: (type: 'input'|'div', cellReference: HTMLElement, value: any, instance: worksheetInstance) => HTMLElement;
/** Create a DOM for a floating editor container */
createDialog: (cell: HTMLElement, value: any, x: number, y: number, instance: worksheetInstance) => HTMLElement;
text: Editor;
number: Editor;
numeric: Editor;
percent: Editor;
notes: Editor;
dropdown: Editor;
autocomplete: Editor;
calendar: Editor;
color: Editor;
checkbox: Editor;
radio: Editor;
autonumber: Editor;
progressbar: Editor;
rating: Editor;
email: Editor;
url: Editor;
image: Editor;
html: Editor;
hidden: Editor;
tags: Editor;
record: Editor;
}
/** Helpers */
interface Helpers {
/**
* Compare two arrays to see if contains exact the same elements.
* @param a1 - Array 1.
* @param a2 - Array 2.
*/
compareArray: (a1: number[], a2: number[]) => boolean;
/**
* Get caret position for editable dom element.
*/
getCaretIndex: (element: HTMLElement) => number;
/**
* Invert the key and values in an object.
*/
invert: (obj: object) => object;
/**
* Get the excel-like letter based on the index number.
*/
getColumnName: (index: number) => string;
/**
* Get the cell name from its coordinates.
*/
getCellNameFromCoords: (x: number, y: number) => string;
/**
* Aliases or getCellNameFromCoords.
*/
getColumnNameFromCoords: (x: number, y: number) => string;
/**
* Get the coordinates from a cell name.
*/
getCoordsFromCellName: (name: string) => [number | null, number | null] | [];
/**
* Alias for getCoordsFromCellName.
*/
getCoordsFromColumnName: (name: string) => [number | null, number | null] | [];
/**
* Shift the formula by x and y positions in the matrix.
*/
shiftFormula: (formula: string, x: number, y: number) => string;
/**
* Get all the token names from a excel-like range.
*/
getTokensFromRange: (range: string, force?: boolean, worksheetName?: string, removeDuplicates?: boolean) => string[];
/**
* Get the range from an array of tokens.
*/
getRangeFromTokens: (tokens: string[], fixCurrencySymbol?: string) => string;
/**
* Get the coordinates as a number from a range string. Adjust helps to define the height dynamically when you have A:A ranges for example. Works in the same way for 1:1 ranges. Default: true.
*/
getCoordsFromRange: (range: string, adjust?: boolean) => RangeCoords;
/**
* Get range string from [x1,y1,x2,y2].
*/
getRangeFromCoords(coords: RangeCoords): string;
getRangeFromCoords(x1: number, y1: number, x2: number, y2: number): string;
/**
* Extract the configuration from JSS from a static HTML table.
*/
createFromTable: (element: HTMLElement, options?: Worksheet) => Worksheet;
/**
* CSV string to JS array.
* @param str - CSV string.
* @param delimiter - Default: ','.
*/
parseCSV: (str: string, delimiter?: string) => string[][];
/**
* Get all token names inside an range.
*/
getTokensFromCoords: (x1: number, y1: number, x2: number, y2: number, worksheetName?: string) => string[];
focus: (element: HTMLElement) => void;
setCaretIndex: (element: any, index: number) => void;
getCaretNode: (target: HTMLElement) => HTMLElement | null;
secureFormula: (oldValue: string, runtime?: boolean) => string;
insertLineBreak: () => void;
}
interface Tabs {
/** Show the create new tab button */
allowCreate?: boolean;
/** Allow drag and drop of the headers to change the tab position */
allowChangePosition?: boolean;
/** Allow the header border bottom animation. */
animation?: boolean;
/** Hide the tab headers if only one tab is present. */
hideHeaders?: boolean;
/** Default padding content */
padding?: number;
/** Position of the headers: top | bottom. Default: top */
position?: 'top' | 'bottom';
}
interface Toolbar {
/** Array of items for the toolbar */
items: Array<ToolbarItem>;
/** Responsive toolbar. Default: true. */
responsive?: boolean;
/** maxWidth */
maxWidth?: number;
/** Position of the extended hidden options when applicable */
bottom: boolean
}
interface ToolbarItem {
/** Toolbar item type */
type?: 'icon' | 'divisor' | 'label' | 'select';
/** Content of the toolbar element */
content?: string;
/** Tooltip for the toolbar element */
tooltip?: string;
/** Toolbar element width */
width?: number;
/** The initial selected option for the type: select */
value?: string;
/** Render method parser for the elements in the dropdown when type: select */
render?: Function;
/** When a item is clicked */
onclick?: (el: HTMLElement, iconObject: object, toolbarItem: HTMLElement) => void;
/** For the type select when a new item is selected */
onchange?: (el: HTMLElement, pickerObject: object, reservedValue: any, itemValue: string, itemKey: string, mouseEvent: object) => void;
/** To update the state of the toolbar */
updateState?: (toolbarObject: object, toolbarItem: HTMLElement, option: any, extendOption: any) => void;
}
interface Dropdown {
/** Endpoint to fetch data from a remote server */
url?: string;
/** Preloaded data items for the dropdown */
data?: DropdownItem[];
/** Format type of the data, typically { id: name } or { value: text } */
format?: number;
/** Indicates if multiple item selection is allowed */
multiple?: boolean;
/** Enables the autocomplete feature for user input */
autocomplete?: boolean;
/** Allows remote search for options */
remoteSearch?: boolean;
/** Enables the lazy loading feature for handling a large number of options */
lazyLoading?: boolean;
/** Rendering style of the dropdown: 'default', 'picker', or 'searchbar' */
type?: 'default' | 'picker' | 'searchbar',
/** Defines the dropdown's width */
width?: number;
/** Sets the maximum width of the dropdown */
maxWidth?: number;
/** Determines if the dropdown is opened when initialized */
opened?: boolean;
/** The initial value of the dropdown */
value?: string;
/** Placeholder text for the dropdown */
placeholder?: string;
/** Allows the user to add new options */
newOptions?: boolean;
/** Internal controller for the dropdown's position */
position?: boolean;
/** Event handler for value changes */
onchange?: (el: HTMLElement, obj: object, oldValue: string, newValue: string) => void;
/** Event handler for when the dropdown is ready */
onload?: (el: HTMLElement, obj: object, data: any, val: any) => void;
/** Event handler for when the dropdown opens */
onopen?: (el: HTMLElement) => void;
/** Event handler for when the dropdown closes */
onclose?: (el: HTMLElement) => void;
/** Event handler for when the dropdown receives focus */
onfocus?: (el: HTMLElement) => void;
/** Event handler for when the dropdown loses focus */
onblur?: (el: HTMLElement) => void;
/** Event handler for when a new option is added to the dropdown */
oninsert?: (obj: object, item: DropdownItem, newItem: DropdownItem) => void;
/** Event handler for just before a new option is added to the dropdown */
onbeforeinsert?: (obj: object, item: DropdownItem) => DropdownItem | false | undefined;
/** Event handler for before a search on autocomplete is performed */
onbeforesearch?: (obj: object, ajaxRequest: object) => object | false | undefined;
/** Event handler for processing search results */
onsearch?: (obj: object, result: object) => void;
/** Toggles the sorting of dropdown elements */
sortResults?: boolean;
/** Indicates if the dropdown should automatically receive focus upon creation */
autofocus?: boolean;
}
interface DropdownItem {
/** Value of the selected item. */
id?: string | number;
/** Label for the selected item. */
name?: string;
/** Description of the item */
title?: string;
/** Icon of the item */
image?: string;
/** Name of the group where the item belongs to */
group?: string;
/** Keywords to help finding one item */
synonym?: string[];
/** Item is disabled */
disabled?: boolean;
/** Color for the item */
color?: string;
}
interface ContextmenuItem {
/** Context menu item type: line | divisor | default */
type?: 'line' | 'divisor' | 'default';
/** Context menu item title */
title: string;
/** Context menu icon key. (Material icon key icon identification) */
icon?: string;
/** HTML id property of the item DOM element */
id?: string;
/** Item is disabled */
disabled?: boolean;
/** Onclick event for the contextmenu item */
onclick?: (instance: object, e: MouseEvent) => void;
/** A short description or instruction for the item. Normally a shortcut. Ex. CTRL + C */
shortcut?: string;
/** Show this text when the user mouse over the element */
tooltip?: string;
/** Submenu */
submenu?: Array<ContextmenuItem>;
}
interface Contextmenu {
/** The contextmenu menu */
(worksheet: worksheetInstance, x: number, y: number, e: MouseEvent, items: Array<ContextmenuItem>, section: string, section_argument1?: any, section_argument2?: any) : Array<ContextmenuItem> | boolean;
}
interface Calendar {
/** Specifies the type of calendar to render. Default is 'default'. Possible values are 'default' and 'year-month-picker'. */
type?: 'default' | 'year-month-picker';
/** An array of numbers specifying a range of valid dates. Dates outside this range will be disabled. */
validRange?: [number, number];
/** The day of the week the calendar starts on (0 for Sunday - 6 for Saturday). Default: 0. */
startingDay?: number;
/** Specifies the day of the week the calendar starts on, where 0 is Sunday and 6 is Saturday. Default is 0 (Sunday). */
format?: string;
/** Specifies whether the calendar input is readonly or not. Default is false. */
readonly?: boolean;
/** Specifies whether today's date is automatically selected when no date is defined. */
today?: boolean;
/** Specifies whether to display a dropdown for selecting hour and minute values. Default is false. */
time?: boolean;
/** Specifies whether to display a reset button. Default is true. */
resetButton?: boolean;
/** Specifies a placeholder text to display in the calendar input when no date is selected. */
placeholder?: string;
/** Auto select confirms the current date as the new value onblur. Default: true */
autoSelect?: boolean;
/** Open in fullscreen mode. */
fullscreen?: boolean;
}
interface DefinedNames {
index: string;
value?: string;
}
/**
* Cell value
*/
interface CellRecord {
/** Cached value of the cell */
value: string | number | boolean | undefined;
/** Coordinate X */
x: number;
/** Coordinate Y */
y: number;
}
/**
* Cell object
*/
interface Records {
/** CELL td element */
element: HTMLTableCellElement;
/** Cached value of the cell */
v: string | number | boolean | undefined;
/** Coordinate X */
x: number;
/** Coordinate Y */
y: number;
/** Associate to an array of values */
a?: Map<Records, any>;
/** Part of a merged cells */
merged?: any[];
/** Merged cells */
mergeCells?: [number, number];
/** Style */
s?: number;
/** Comments */
c?: string | Record<string, any>[];
/** Meta */
meta?: object;
/** Chain */
chain?: Map<Records, true>;
// Worksheet Instance
w: worksheetInstance;
}
type ColumnType = Editor | 'text' | 'number' | 'numeric' | 'percent' | 'notes' | 'dropdown' | 'autocomplete' | 'calendar' | 'color' | 'checkbox' | 'radio' | 'autonumber' | 'progressbar' | 'rating' | 'email' | 'url' | 'image' | 'html' | 'hidden' | 'tags' | 'record';
interface ColumnPrimitiveProperties {
/** Define the type of editor to use for the column. Can be a string to define a native editor, or a method to define a custom editor plugin. */
type?: ColumnType;
/** The alignment of the column content. Default: center. */
align?: 'center' | 'left' | 'right' | 'justify';
/** The URL to load items from for the dropdown in this column, or when used in a text cell it will be a create a link */
url?: string;
/** The items to show in the dropdown or autocomplete. */
source?: Array<DropdownItem> | Array<string> | Array<number>;
/** It defines the options of a dropdown from a cell range. Example: Sheet1!A1:A4 */
dynamicSource?: string;
/** Whether the column is an autocomplete field. */
autocomplete?: boolean;
/** Whether the dropdown or autocomplete can accept multiple options. */
multiple?: boolean;
/** The delimiter to use for separating multiple dropdown options. Default: ";". */
delimiter?: string;
/** The input mask to apply to the data cell. @see https://jsuites.net/v4/javascript-mask */
mask?: string;
/** The character to use as the decimal separator. */
decimal?: '.' | ',';
/** The maximum number of characters to display in the cell before truncating. */
truncate?: number,
/** Whether to disable the mask when editing. */
disabledMaskOnEdition?: boolean;
/** A renderer method or rule for the cell content. */
render?: string | ((td: HTMLElement, value: number|string, x: number | string, y: number | string, worksheet: worksheetInstance, options: Column) => void);
/** The format of the date or numbers in the cell. Default for the calendar: "DD/MM/YYYY". */
format?: string;
/** Locale for Intl.NumberFormat */
locale?: string,
/** Extended configuration for the column. */
options?: Calendar | Dropdown | object;
/** Whether the column is read-only. */
readOnly?: boolean;
/** Whether to process the raw data when copying or downloading. Default: true. */
process?: boolean;
/** Whether to try to cast numbers from a cell text. Default: true. */
autoCasting?: boolean;
/** Whether to wrap the text in the column. */
wrap?: boolean;
/** The rotation angle for the text value, between -90 and 90. Default: null. */
rotate?: number;
/** Can be used to map JSON properties or help to group type radio cells */
name?: string;
/** Record editor */
worksheetId?: string;
worksheetColumn?: number;
worksheetImage?: boolean;
locked?: boolean;
}
interface Column extends ColumnPrimitiveProperties {
/** The title of the column. */
title?: string;
/** The name or path of a property when the data is a JSON object. */
name?: string;
/** Define the tooltip text to display on mouseover for the column header. */
tooltip?: string;
/** The width of the column. Default: 100px */
width?: number;
/** Whether the column is visible. */
visible?: boolean,
/** A method to overwrite the column definitions in real-time just before the column is edited. */
filterOptions?: (worksheet: worksheetInstance, cell: HTMLElement, x: number, y: number, value: number|string, options: Column) => Column;
/** Whether the column is a primary key. */
primaryKey?: boolean;
/** Whether to shift the formula when copying and pasting. This option is only valid for custom column types. Default: false. */
shiftFormula?: boolean;
/** Whether to apply CSS odd-even background color to the column. Default: false. */
zebra?: boolean;
/** The number of columns to group together. */
group?: number;
/** State of the column group. */
state?: boolean;
/** Style index */
s?: number;
}
interface Cell extends ColumnPrimitiveProperties { }
interface Border {
/** HTML Element for the border */
element: HTMLElement;
/** Border color */
color: string;
/** Used on the marching ants border */
moveLeft?: HTMLElement;
/** Used on the marching ants border */
moveTop?: HTMLElement;
/** Used on the marching ants border */
moveRight?: HTMLElement;
/** Used on the marching ants border */
moveDown?: HTMLElement;
/** Current x1 coordinates for the border */
x1: number;
/** Current y1 coordinates for the border */
y1: number;
/** Current x2 coordinates for the border */
x2: number;
/** Current y2 coordinates for the border */
y2: number;
/** Border is active in the viewport */
active: boolean;
/** Position top of the border */
t: number;
/** Position left of the border */
l: number;
/** Current border width */
w: number;
/** Current border height */
h: number;
}
interface Row {
/** Height of the row in pixels. */
height?: number;
/** Title or name of the row. */
title?: string;
/** Determines whether the row is visible or not. */
visible?: boolean;
/** ID number that identifies the row. */
id?: number;
/** Number of rows that this row is grouped with. */
group?: number;
/** State of the row group (collapsed or expanded). */
state?: boolean;
/** Determines whether the row is read-only or not. */
readOnly?: boolean;
/** Style index */
s?: number;
}
interface RowInstance extends Row {
/** Element. */
element: HTMLTableRowElement;
/** Row index. */
y: number;
}
interface Editor {
/** createCell When a new cell is created. */
createCell?: (cell: HTMLTableCellElement, value: any, x: number, y: number, instance: worksheetInstance, options: Column | Cell) => any;
/** updateCell When the cell value changes. */
updateCell?: (cell: HTMLTableCellElement, value: any, x: number, y: number, instance: worksheetInstance, options: Column | Cell) => any;
/** openEditor When the user starts the edition of a cell. */
openEditor?: (cell: HTMLTableCellElement, value: any, x: number, y: number, instance: worksheetInstance, options: Column | Cell) => any;
/** closeEditor When the user finalizes the edition of a cell. */
closeEditor?: (cell: HTMLTableCellElement, confirmChanges: boolean, x: number, y: number, instance: worksheetInstance, options: Column | Cell) => any;
/** When a cell is destroyed. */
destroyCell?: (cell: HTMLTableCellElement, x: number, y: number, instance: worksheetInstance) => void;
/** Transform the raw data into processed data. It will show a text instead of an id in the type dropdown for example. */
get?: (options: object, value: any, extended: boolean, instance: worksheetInstance) => string
}
interface Plugin {
/** When a new worksheet is added. */
beforeinit?: (worksheet: worksheetInstance) => void;
/** When a new worksheet is added. */
init?: (worksheet: worksheetInstance) => void;
/** It would receive a call for every spreadsheet event. */
onevent?: (event: string, ...args: any[]) => any;
/** When the spreadsheet needs to save something in the server. */
persistence?: (method: string, args: object) => void;
/** When the user opens the context menu. */
contextMenu?: (instance: worksheetInstance, x: number, y: number, e: MouseEvent, items:Array<ContextmenuItem> , section: string, a: any, b?: any) => Array<ContextmenuItem>;
/** When the toolbar is created and clicked. */
toolbar?: (instance: worksheetInstance, toolbar: Toolbar) => Toolbar;
}
interface Nested {
/** Nested header title */
title?: string;
/** Nested header tooltip */
tooltip?: string;
/** Nested header colspan */
colspan?: number;
/** Alignment */
align?: 'left' | 'center' | 'right';
/** Frozen */
frozen?: boolean;
}
interface Spreadsheet {
/** Your application name */
application?: string;
/** Remote configuration with Jspreadsheet Server */
guid?: string;
/** DOM element for binding the javascript events. This property is normally used when JSS is running as a web component. */
root?: HTMLElement;
/** Global defined names. It defines global range variables. */
definedNames?: Record<string, string>,
/** Global sorting handler. */
sorting?: (direction: boolean, column: number) => (a: any, b: any) => number;
/** Remote URL for the persistence server */
server?: string;
/** Enable the toolbars */
toolbar?: boolean | Toolbar | ToolbarItem[] | ((toolbarOptions: Toolbar) => Toolbar);
/** Allow table edition */
editable?: boolean;
/** Allow data export */
allowExport?: boolean;
/** Include the table headers in the first row of the data */
includeHeadersOnDownload?: boolean;
/** Force update on paste for read-only cells */
forceUpdateOnPaste?: boolean;
/** Render jspreadsheet spreadsheet on full screen mode. Default: false */
fullscreen?: boolean;
/** Make sure the formulas are capital letter. Default: true */
secureFormulas?: boolean;
/** Enable formula debug. Default: false */
debugFormulas?: boolean,
/** Execute formulas. Default: true */
parseFormulas?: boolean;
/** Disable the formula editor. Default: true */
editorFormulas?: boolean;
/** Enable or disable formula picker with keyboard. Default: true */
keyboardFormulas?: boolean;
/** Auto increment cell data when using the corner copy, including formulas, numbers and dates. Default: true */
autoIncrement?: boolean;
/** Try to cast numbers from cell values when executing formulas. Default: true */
autoCasting?: boolean;
/** Parse HTML. Default: false (Use this with caution) */
parseHTML?: boolean;
/** Allow bar when extension bar is enabled. Default: true */
bar?: boolean;
/** Allow tabs. Default: false */
tabs?: boolean | Tabs;
/** Allow the user to delete worksheets. Default: true */
allowDeleteWorksheet?: boolean;
/** Allow the user to rename worksheets. Default: true */
allowRenameWorksheet?: boolean;
/** Allow the user to drag and drop the worksheets. Default: true */
allowMoveWorksheet?: boolean;
/** Move the cursor down when pressing enter during edition. Default: true */
moveDownOnEnter?: boolean;
/** This method is called when the data in the spreadsheet is ready. */
onload?: (spreadsheet: spreadsheetInstance) => void;
/** Spreadsheet is clicked */
onclick?: (worksheet: worksheetInstance, section: string, x: number, y: number, event: object) => void;
/** When undo is applied */
onundo?: (worksheet: worksheetInstance, historyRecord: object) => void;
/** When redo is applied */
onredo?: (worksheet: worksheetInstance, historyRecord: object) => void;
/** Before any data is sent to the backend. Can be used to overwrite the data or to cancel the action when return false. */
onbeforesave?: (spreadsheet: spreadsheetInstance, worksheet: worksheetInstance, data: object) => boolean | object | undefined;
/** After something is saved */
onsave?: (spreadsheet: spreadsheetInstance, worksheet: worksheetInstance, data: object, result: object) => void;
/** When something goes wrong during a persistence operation */
onerror?: (spreadsheet: spreadsheetInstance, result: object) => void;
/** Before a column value is changed. NOTE: It is possible to overwrite the original value, by return a new value on this method. */
onbeforechange?: (worksheet: worksheetInstance, cell: HTMLElement, x: number | string, y: number | string, value: any) => false | any | undefined;
/** After a column value is changed. */
onchange?: (worksheet: worksheetInstance, cell: HTMLElement, x: number | string, y: number | string, newValue: any, oldValue: any) => void;
/** When all data have been updated. Origin: 'paste', 'handle-fill' or undefined */
onafterchanges?: (worksheet: worksheetInstance, records: Record<string, any>[], origin: string | undefined) => void;
/** When a copy is performed in the spreadsheet. Any string returned will overwrite the user data or return null to progress with the default behavior. */
oncopy?: (worksheet: worksheetInstance, selectedCells: RangeCoords, data: string, cut: boolean | undefined) => false | string | undefined;
/** Before the paste action is performed. Can return parsed or filtered data. It is possible to cancel the action when the return is false. */
onbeforepaste?: (worksheet: worksheetInstance, data: Record<string, any>[][], x: number, y: number) => false | Record<string, any>[][] | undefined;
/** After a paste action is performed in the spreadsheet. */
onpaste?: (
worksheet: worksheetInstance,
records: {
x: number,
y: number,
[key: string]: any,
}[]
) => void;
/** Before a new row is inserted. You can cancel the insert event by returning false. */
onbeforeinsertrow?: (worksheet: worksheetInstance, newRow: Record<string, any>[]) => false | newRow[] | undefined;
/** After a new row is inserted. */
oninsertrow?: (worksheet: worksheetInstance, newRow: Record<string, any>[]) => void;
/** Before a row is deleted. You can cancel the delete event by returning false. */
onbeforedeleterow?: (worksheet: worksheetInstance, rows: number[]) => number[] | false | undefined;
/** After a row is excluded. */
ondeleterow?: (worksheet: worksheetInstance, rows: number[]) => void;
/** Before a new column is inserted. You can cancel the insert event by returning false. */
onbeforeinsertcolumn?: (worksheet: worksheetInstance, newColumn: Record<string, any>[]) => false | newColumn[] | undefined;
/** After a new column is inserted. */
oninsertcolumn?: (worksheet: worksheetInstance, affected: Record<string, any>[]) => void;
/** Before a column is excluded. You can cancel the insert event by returning false. */
onbeforedeletecolumn?: (worksheet: worksheetInstance, cols: number[]) => false | number[] | undefined;
/** After a column is excluded. */
ondeletecolumn?: (worksheet: worksheetInstance, cols: number[]) => void;
/** After a row is moved to a new position. */
onmoverow?: (worksheet: worksheetInstance, origin: number, destination: number, quantityOfRows: number) => void;
/** After a column is moved to a new position. */
onmovecolumn?: (worksheet: worksheetInstance, origin: number, destination: number, quantityOfColumns: number) => void;
/** After a height change for one or more rows. */
onresizerow?: (worksheet: worksheetInstance, row: number | Array<number>, height: number | Array<number>, oldHeight: number | Array<number>) => void;
/** After a column width change for one or more columns. */
onresizecolumn?: (worksheet: worksheetInstance, column: number | Array<number>, width: number | Array<number>, oldWidth: number | Array<number>) => void;
/** Before the selection happens */
onbeforeselection?: (worksheet: worksheetInstance, px: number, py: number, ux: number, uy: number, origin?: object) => boolean | undefined;
/** When the selection is changed. */
onselection?: (worksheet: worksheetInstance, px: number, py: number, ux: number, uy: number, origin?: object) => void;
/** Before the comments is added or updated. Return false to cancel the event, void to accept the action or a object. */
onbeforecomments?: (worksheet: worksheetInstance, cells: Record<string, string>) => false | Record<string, string> | undefined;
/** After a new comment is added or updated. */
oncomments?: (worksheet: worksheetInstance, newValues: Record<string, string>, previousValues: Record<string, string>) => void;
/** It runs before sorting a column. It should return an array with a custom sorting or false to cancel the user action. */
onbeforesort?: (worksheet: worksheetInstance, column: number, direction: number, newOrderValues: number[]) => false | number[] | undefined;
/** When a column is sorted. */
onsort?: (worksheet: worksheetInstance, column: number, direction: number, newOrderValues: number[]) => void;
/** When the spreadsheet gets the focus. */
onfocus?: (worksheet: worksheetInstance) => void;
/** When the spreadsheet loses the focus. */
onblur?: (worksheet: worksheetInstance) => void;
/** When merge cells is executed. */
onmerge?: (worksheet: worksheetInstance, newValue: object, oldValue: object) => void;
/** When the header title is changed. */
onchangeheader?: (worksheet: worksheetInstance, column: number, newValue: string, oldValue: string | undefined) => void;
/** When the footers are created or updated. */
onchangefooter?: (worksheet: worksheetInstance, newValue: string[][], oldValue: string[][] | undefined) => void;
/** When the value in a cell footer is changed. */
onchangefootervalue?: (worksheet: worksheetInstance, x: number, y: number, value: string) => void;
/** When the footer cell is rendered */
onrenderfootercell?: (worksheet: worksheetInstance, x: number, y: number, value: string, td: HTMLElement) => void;
/** On change nested headers */
onchangenested?: (worksheet: worksheetInstance, options: object) => void;
/** On change nested cell properties */
onchangenestedcell?: (worksheet: worksheetInstance, x: number, y: number, properties: object) => void;
/** When an editor is created. */
oncreateeditor?: (worksheet: worksheetInstance, cell: HTMLElement, x: number, y: number, element: HTMLElement, options: object) => void;
/** When the editor is opened. */
oneditionstart?: (worksheet: worksheetInstance, cell: HTMLElement, x: number, y: number) => boolean | undefined;
/** When the editor is closed. */
oneditionend?: (worksheet: worksheetInstance, cell: HTMLElement, x: number, y: number, newValue: any, save: boolean) => void;
/** When the style of a cell is changed. */
onchangestyle?: (worksheet: worksheetInstance, newValue: Record<string, string>, oldValue: Record<string, string | null>) => void;
/** When a cell meta information is added or updated. */
onchangemeta?: (worksheet: worksheetInstance, newValue: Record<string, any>) => void;
/** Before the page is changed. Can cancel the action when return is false. */
onbeforechangepage?: (worksheet: worksheetInstance, pageNumber: number, oldPage: number, quantityPerPage: number) => boolean | undefined;
/** When pagination is enabled and the user changes the page. */
onchangepage?: (worksheet: worksheetInstance, pageNumber: number, oldPageNumber: number, quantityPerPage: number) => void;
/** Add or change the options of a new worksheet. */
onbeforecreateworksheet?: (worksheetOptions: Worksheet, position: number) => Worksheet | false | undefined;
/** When the user creates a new worksheet. */
oncreateworksheet?: (worksheet: worksheetInstance, worksheetOptions: Worksheet, position: number) => void;
/** When the user renames a worksheet. */
onrenameworksheet?: (worksheet: worksheetInstance, position: number, newValue: string, oldValue: string) => void;
/** When the user deletes a worksheet. */
ondeleteworksheet?: (worksheet: worksheetInstance, position: number) => void;
/** When the user updates the worksheet tab position. */
onmoveworksheet?: (worksheet: worksheetInstance, from: number, to: number) => void;
/** When the user opens a worksheet. */
onopenworksheet?: (worksheet: worksheetInstance, index: number) => void;
/** When there is a row id update */
onchangerowid?: (worksheet: worksheetInstance, rows: any[] | Record<string, any>) => void;
/** Before the search method starts */
onsearchstart?: (worksheet: worksheetInstance, query: string) => void;
/** Before the search method starts */
onsearchrow?: (worksheet: worksheetInstance, row: number, query: string, terms: RegExp) => boolean;
/** Action to be executed before searching. The accepted method return would be: null to continue with the default behavior, false to cancel the user action or an array with the row numbers to overwrite the default result. */
onbeforesearch?: (worksheet: worksheetInstance, query: string, results: number[]) => number[] | false | undefined;
/** After the search is applied to the rows. */
onsearch?: (worksheet: worksheetInstance, query: string, results: number[]) => void;
/** Action to be executed before filtering rows. It can cancel the action by returning false. */
onbeforefilter?: (worksheet: worksheetInstance, filters: string[][], data: number[]) => false | number[] | undefined;
/** After the filter has been applied to the rows. */
onfilter?: (worksheet: worksheetInstance, filters: string[][], data: number[]) => void;
/** When a new cell is created */
oncreatecell?: (worksheet: worksheetInstance, cell: HTMLElement, x: number, y: number, value: any) => void;
/** When a new row is created */
oncreaterow?: (worksheet: worksheetInstance, rowNumber: number, tr: HTMLTableRowElement) => void;
/** When a new column is created */
oncreatecolumn?: (worksheet: worksheetInstance, columnNumber: number, td: HTMLElement, options: Column) => void;
/** A way to change the formula in real-time before execution */
onbeforeformula?: (worksheet: worksheetInstance, expression: string, x: number, y: number) => string | false | undefined;
/** Get the information about the expressions executed from the formula chain */
onformulachain?: (worksheet: worksheetInstance, expressions: Array<object>) => void;
/** Customize the items available when filter editor is open. */
onopenfilter?: (worksheet: worksheetInstance, column: number, options: Record<string, any>[]) => Record<string, any>[] | Promise<Record<string, any>[]> | undefined;
/** When the viewport dimension is updated. */
onresize?: (w: number, h: number) => void
/** Intercept the ajax call before save. XHR ajax object */
onbeforesend?: (worksheet: worksheetInstance, xhr: object) => void
/** When defined names is affected */
onchangedefinednames?: (worksheet: worksheetInstance, data: Record<string, any>[]) => void
/** Keyboard event */
onkeydown?: (worksheet: object, event: object) => void
/** New char is entered on editor. */
oninput?: (worksheet: object, event: object, text: string) => void
/** When change the row visibility */
onchangerowvisibility?: (worksheet: worksheetInstance, state: boolean, rows: number[]) => void
/** When change the column visibility */
onchangecolumnvisibility?: (worksheet: worksheetInstance, state: boolean, columns: number[]) => void
/** When a new row group is created */
ongrouprow?: (worksheet: worksheetInstance, row: number, numOfItems: number) => void
/** When open a row group */
onopenrowgroup?: (worksheet: worksheetInstance, row: number) => void
/** When close a row group */
oncloserowgroup?: (worksheet: worksheetInstance, row: number) => void
/** When a new column group is created */
ongroupcolumn?: (worksheet: worksheetInstance, column: number, numOfItems: number) => void
/** When open a column group */
onopencolumngroup?: (worksheet: worksheetInstance, column: number) => void
/** When close a column group */
onclosecolumngroup?: (worksheet: worksheetInstance, column: number) => void
/** When a media object is added, removed or updated. */
onchangemedia?: (worksheet: worksheetInstance, newValue: object[], oldValue: object[], affectedRecords: object[]) => void;
/** Before loading an image */
onbeforeloadimage?: (worksheet: worksheetInstance, img: HTMLImageElement, options: object) => undefined | string | false;
/** Update references. When a table structure changes */
onchangereferences?: (worksheet: object, affected: Record<string, any>, deletedTokens: string[], deletedColumns: number[], deletedRows: number[]) => void;
/** When the cell is changed */
onchangeproperty?: (worksheet: worksheetInstance, records: Record<string, any>[]) => void;
/** Fire when there is a change in the config */
onchangeconfig?: (config: string, spreadsheetLevel?: boolean) => void;
/** Fire when a worksheet's visibility is changed. */
onchangeworksheetstate?: (spreadsheet: spreadsheetInstance, worksheetIndex: number, state: boolean) => void;
/** General event handler */
onevent?: (worksheet: worksheetInstance, method: string, ...args: any[]) => any
/** Fire when a cell's metadata is reset. */
onresetmeta?: (worksheet: worksheetInstance, cellNames: string[] | undefined) => void;
/** Fire when a cell's style is reset. */
onresetstyle?: (worksheet: worksheetInstance, cellNames: string[]) => void;
/** Fire when a validation is created, changed or removed. */
onvalidation?: (worksheet: worksheetInstance, records: { index: number, value: Validation | null, oldValue: Validation | null }[]) => void;
/** Return false to cancel the contextMenu event, or return custom elements for the contextmenu. */
contextMenu?: Contextmenu | null;
/** About information */
about?: string,
/** Worksheets */
worksheets?: Worksheet[];
/** Validations */
validations?: Validation[];
/** Plugins */
plugins?: Record<string, Plugin>;
/** Global style */
style?: string[];
/** Snap the cells to the grid when scrolling. Default: false */
snapToGrid?: boolean;
/** Space between the table and the end of the container. Default: 100 */
spacing?: number;
/** Pre-calculation helps to calculate all formula and cache the results. Default true */
preCalculation?: boolean;
/** Consider the use of column name in formulas. Default: true [ For example: =Countries*10 ] */
columnNamesInFormulas?: boolean;
/** Namespace help with cross-calculations conflict names */
namespace?: string;
/** International configuration */
international?: International;
/** Persistence handler */
persistence?: (worksheet: worksheetInstance, method: string, args: object) => void;
/** Create a selection during the openWorksheet. Default: true */
autoSelect?: boolean;
}
interface Worksheet {
/** Load the data from an external server URL */
url?: string;
/** Persistence URL or true when the URL is the same of the URL of the data source */
persistence?: string | boolean;
/** Allow internal sequence for new rows */
sequence?: boolean;
/** Load the data into a new spreadsheet from an array of rows or objects */
data?: Array<Array<any>> | Array<Record<string, any>>;
/** Array with the rows properties definitions such as title, height. */
rows?: Row[] | Record<number, Row>;
/** The column properties define the behavior of a column and the associated editor */
columns?: Array<Column>;
/** Define the properties of a cell. This property overwrite the column definitions */
cells?: Record<string, Cell>;
/** Nested headers definition */
nestedHeaders?: Array<Array<Nested>>;
/** Default column width. Default: 50px */
defaultColWidth?: number | string;
/** Default row height. Default: null */
defaultRowHeight?: number | string;
/** Deprecated. The default alignment of a cell is defined by a CSS class from 8.2.0+ */
defaultColAlign?: 'center' | 'left' | 'right' | 'justify';
/** Minimum number of spare rows. Default: 0 */
minSpareRows?: number;
/** Minimum number of spare cols. Default: 0 */
minSpareCols?: number;
/** Minimum table dimensions: [numberOfColumns, numberOfRows] */
minDimensions?: [number, number];
/** CSV data source URL */
csv?: string;
/** CSV default filename for the jspreadsheet exports. Default: worksheetName */
csvFileName?: string;
/** Consider first line as header. Default: false */
csvHeaders?: boolean;
/** Delimiter to consider when dealing with the CSV data. Default: ',' */
csvDelimiter?: string;
/** Allow column sorting */
columnSorting?: boolean;
/** Sorting the column on dblclick in the header. Default: true */
columnSortingOnDblClick?: boolean;
/** Allow column dragging */
columnDrag?: boolean;
/** Allow column resizing */
columnResize?: boolean;
/** Allow row resizing */
rowResize?: boolean;
/** Allow row dragging */
rowDrag?: boolean;
/** Allow table edition */
editable?: boolean;
/** Allow new rows */
allowInsertRow?: boolean;
/** Allow new rows to be added using tab key. Default: true */
allowManualInsertRow?: boolean;
/** Allow new columns to be added using enter key. Default: true */
allowInsertColumn?: boolean;
/** Allow new rows to be added via script. Default: true */
allowManualInsertColumn?: boolean;
/** Allow rows to be deleted. Default: true */
allowDeleteRow?: boolean;
/** Allow columns to be deleted. Default: true */
allowDeleteColumn?: boolean;
/** Allow rename column. Default: true */
allowRenameColumn?: boolean;
/** Allow users to add comments to the cells. Default: true */
allowComments?: boolean;
/** Corner selection and corner data cloning. Default: true */
fillHandle?: boolean;
/** Merged cells. Default: null */
mergeCells?: Record<string, [number, number]>;
/** Allow search on the spreadsheet */
search?: boolean;
/** Activate pagination and defines the number of records per page. Default: false */
pagination?: number;
/** Dropdown for the user to change the number of records per page. Example: [10,25,50,100]. Default: false */
paginationOptions?: Array<number>;
/** Text Overflow. Default: false */
textOverflow?: boolean;
/** Table overflow. Default: false */
tableOverflow?: boolean;
/** Define the table overflow height. Example: '300px' */
tableHeight?: number | string;
/** Define the table overflow width. Example: '800px' */
tableWidth?: number | string;
/** Virtualization for columns. Works only when tableOverflow: true. Default: true */
virtualizationX?: boolean;
/** Virtualization for rows. Works only when tableOverflow: true. Default: true */
virtualizationY?: boolean;
/** Initial comments. Default: null */
comments?: Record<string, string|Comment[]>;
/** Initial meta information. Default: null */
meta?: Record<string, any>;
/** Style */
style?: Record<string, string|number>;
/** List of frozen column numbers. Should be a number or an array of consecutive numbers. Example: [4,5,6] */
freezeColumns?: number|number[];
/** List of frozen row numbers. Should be a number or an array of consecutive numbers. Example: [4,5,6] */
freezeRows?: number|number[];
/** Enable freeze column manual control. Default: false */
freezeColumnControl?: boolean,
/** Enable freeze row manual control. Default: false */
freezeRowControl?: boolean,
/** Worksheet Unique Id. */
worksheetId?: string;
/** Worksheet Name. */
worksheetName?: string;
/** Worksheet state: hidden | null. Hide a worksheet */
worksheetState?: 'hidden' | undefined;
/** Enable the column filters */
filters?: boolean | string;
/** Footers */
footers?: any[][];
/** Apply mask on footers. Default: true */
applyMaskOnFooters?: boolean;
/** This is a internal controller for the spreadsheet locked properties. Please use editable to make it readonly. */
locked?: boolean;
/** Allow the selection of unlocked cells. Default: true. */
selectUnLockedCells?: boolean;
/** Allow the selection of locked cells. Default: true. */
selectLockedCells?: boolean;
/** Enable resizable worksheet in on or both direction (horizontal | vertical | both). Default: none */
resize?: 'horizontal' | 'vertical' | 'both' | 'none' | undefined;
/** Show the worksheet gridlines. Default: true */
gridline?: boolean;
/** Floating images or charts. */
media?: Media[];
/** Cached values. This can be used to skip calculations during onload */
cache?: Record<string, string|number>;
/** Zoom value. Default 1 */
zoom?: number;
/** Detect column names from the data object given when the column names are not declared. Default: true */
autoNames?: boolean;
/** Ignore Undefined Columns. Default: false */
ignoreUndefinedColumns?: boolean;
}
interface SpreadsheetHTMLElement extends HTMLDivElement {
spreadsheet: spreadsheetInstance;
}
interface spreadsheetInstance {
/** Spreadsheet configuration */
config: Spreadsheet;
/** Contextmenu HTMLElement */
contextmenu: HTMLElement;
/** DOM Element */
el: SpreadsheetHTMLElement;
/** DOM Element. Alias for el */
element: SpreadsheetHTMLElement;
/** DOM Element container for the filters */
filter: HTMLElement;
/** Toggle the full screen mode */
fullscreen: (state: Boolean) => void;
/** HTMLElement Helper */
helper: HTMLElement,
/** Ignore events */
ignoreEvents: boolean;
/** Ignore persistence events */
ignorePersistence: boolean;
/** HTMLElement editor container */
input: HTMLElement;
/** HTMLElement loading element */
loading: HTMLElement;
/** Spreadsheet unique name */
name: string;
/** List of plugins loaded to the spreadsheet */
plugins: Record<string, Plugin>;
/** Show progressbar */
progress: (state: boolean) => void;
/** DOM Textarea helper */
textarea: HTMLElement;
/** DOM toolbar */
toolbar: HTMLElement;
/** Tools HTMLElement container */
tools: HTMLElement;
/** Worksheets container */
worksheets: Array<worksheetInstance>;
/** Load plugins into the spreadsheet */
setPlugins: (plugins: Record<string, Function>) => void;
/** Internal method: event dispatch controllers. */
dispatch: (event: string, ...args: any[]) => any;
/** Get the spreadsheet configuration */
getConfig: () => Spreadsheet;
/** Get the worksheet index by instance or worksheetId */
getWorksheet(worksheetIdent: worksheetInstance): number | false;
getWorksheet(worksheetIdent: string, instance?: boolean): worksheetInstance | number | false;
/** Get the worksheet name */
getWorksheetName: (position: number) => string | undefined;
/** Get the worksheet instance by its name */
getWorksheetInstanceByName: GetWorksheetInstanceByNameFunction;
/** Open a worksheet */
openWorksheet: (position: number, force?: boolean) => void;
/** Create a new worksheet */
createWorksheet: (worksheetOptions: Worksheet, position?: number) => worksheetInstance | false;
/** Delete an existing worksheet by its position. When position is omitted delete based on the call context. */
deleteWorksheet: (position?: number) => false | undefined;
/** Rename an existing worksheet by its position. When position is omitted rename based on the call context. */
renameWorksheet: (position: number | null, title: string) => false | undefined;
/** Move the position of a worksheet. ignoreDomUpdates: true will block updates to the DOM */
moveWorksheet: (from: number, to: number, ignoreDomUpdates?: boolean) => false | undefined;
/** Get the active worksheet when applicable */
getWorksheetActive: () => number;
/** Parse the toolbar definitions with defaults */
getToolbar: (toolbar?: Toolbar | ToolbarItem[] | Function) => object,
/** Set the toolbar */
setToolbar: (toolbar: Toolbar | ToolbarItem[] | Function) => void;
/** Show the toolbar */
showToolbar: () => void;
/** Hide the toolbar */
hideToolbar: () => void;
/** Refresh the toolbar based on the current worksheet */
refreshToolbar: (worksheet?: worksheetInstance) => void;
/** Set a worksheet state visibility */
setWorksheetState: (worksheetIndex: number, state: boolean) => void;
/** Change the spreadsheet settings */
setConfig: (config: Spreadsheet) => void;
/** Destroy the spreadsheet */
destroy: (spreadsheet?: spreadsheetInstance | SpreadsheetHTMLElement, destroyEventHandlers?: boolean) => void;
}
interface CustomArray<T> extends Array<T> {
[key: string]: any;
}
interface ColumnInstance extends Column {
x: number;
colElement: HTMLTableColElement;
element: HTMLTableCellElement
}
type DeleteMediaItem = string | { id: string };
type SetValueFirstArgument = string | { x: number, y: number, value: any, force?: boolean }[];
/** Maps cell names (e.g., "A1") to colspan and rowspan values (e.g., [3, 2]). */
type MergeConfig = Record<string, [number, number]>;
interface worksheetInstance {
/** Array with the borders information */
borders: CustomArray<Border>;
/** Close the edition for one cell */
closeEditor: (cell: HTMLElement|null, save: boolean) => void;
/** Close the filters */
closeFilter: (update: boolean) => void;
/** Column settings */
cols: ColumnInstance;
/** Hold the colgroup container */
colgroupContainer: HTMLElement;
/** DOM Worksheet container */
content: HTMLElement;
/** Copy */
copy: (cut?: boolean) => void;
/** HTML Element for the handler fill */
corner: HTMLElement;
/** Internal selected cell */
cursor: object;
/** Cut */
cut: () => void;
/** Alias to getData */
data: (highlighted?: boolean | RangeCoords, processed?: boolean, delimiter?: string, asJson?: boolean, includeFilteredRows?: boolean) => Array<Array<any>> | Array<Record<string, any>> | string;
/** Internal use control type to defined JSON (1) or ARRAY (0). */
dataType: number,
/** Delete one more columns */
deleteColumn(columnNumber: number[]): false | undefined;
deleteColumn(columnNumber: number, numOfColumns?: number): false | undefined;
/** Delete an existing row or rows */
deleteRow(rowNumber: number[]): false | undefined;
deleteRow(rowNumber: number, numOfRows?: number): false | undefined;
/** Destroy all merged cells */
destroyMerge: () => void;
/** Internal method: event dispatch controllers. */
dispatch: (event: string, ...args: any[]) => any;
/** Navigation down */
down: (shiftKey?: boolean, ctrlKey?: boolean, jump?: boolean) => void;
/** If extension render exists, execute render extension else download CSV */
download: (includeHeaders?: boolean, processed?: boolean, csv?: boolean) => false | string | undefined;
/** Download CSV */
downloadCSV: (includeHeaders?: boolean, processed?: boolean) => false | string | undefined;
/** DOM Worksheet. */
element: HTMLElement;
/** Internal method: Execute a formula. */
executeFormula: (expression: string, x?: number, y?: number, caching?: boolean, basic?: boolean) => any;
/** Navigation first */
first: (shiftKey?: boolean, ctrlKey?: boolean) => void;
/** Internal footer controllers */
footers: Record<string, any>;
/** Get the border */
getBorder: (alias: string) => Border;
/** Get the cell element from the cellName or via its coordinates x,y */
getCell(cellName: string): HTMLElement;
getCell(columnNumber: number, y: number): HTMLElement;
/** Alias to getCell */
getCellFromCoords(cellName: string): HTMLElement;
getCellFromCoords(columnNumber: number, y: number): HTMLElement;
/** Get attributes from one cell when applicable */
getCells: (cellName?: string) => Cell | Record<string, Cell> | undefined;
/** Get the column object by its position */
getColumn(): Column[];
getColumn(position: number): ColumnInstance | undefined;
/** Get the column data from its number */
getColumnData: (col: number, processed?: boolean) => false | Array<any>;
/** Get the column position by its name */
getColumnIdByName: (name: string) => number | false;
/** Alias for getProperties */
getColumnOptions: (x: number, y?: number) => Cell | ColumnInstance | undefined;
/** Get the comments from one cell or multiple cells. Example: getComments('A1') */
getComments: (cellName?: string) => string | Comment[] | Record<string, string | Comment[]> | undefined;
/** Get the cached values from one cell or multiple cells. Example: getCache('A1') */
getCache: (cellName?: string) => false | string | object;
/** Get the worksheet settings. Default: false */
getConfig: (spreadsheetLevel?: boolean) => Worksheet | Spreadsheet;
/**
* Fetches all or selected worksheet data in array or JSON format.
* @intent get-sheet-data, export-data
* @param highlighted - If true, returns only highlighted cells; if RangeCoords, specific range; defaults to all data.
* @param processed - If true, returns formatted values; if false, raw values for example formulas or keys. Where processed result for formulas or labels Defaults to false.
* @param delimiter - Delimiter for string output (e.g., "," for CSV-like). Normally used on download operations.
* @param asJson - Recommended to be used on data operations, default will always respect the internal format. Defaults to false.
* @param includeFilteredRows - If true, includes rows hidden by filters. Defaults to false.
* @returns {Array<Array<any>> | Array<Record<string, any>> | string} - Worksheet data in specified format or respecting the internal values
* @example
* const allData = getData(); // [["1", "2"], ["3", "4"]]
* const jsonData = getData(false, true, ",", true); // [{ "A": "1", "B": "2" }, ...]
* const selectedData = getData([0, 0, 1, 1]); // [["1", "2"], ["3", "4"]]
*/
getData: (highlighted?: boolean | RangeCoords, processed?: boolean, delimiter?: string, asJson?: boolean, includeFilteredRows?: boolean) => Array<Array<any>> | Array<Record<string, any>> | string;
/** Get the worksheet data from a range */
getDataFromRange: (range: string, processed?: boolean) => Array<Array<any>> | Array<Record<string, any>>;
/** Get the defined name or all defined names when key is null */
getDefinedNames: (key?: string) => any;
/** Internal method: Get the editor for one cell */
getEditor: (x: number, y: number) => [Editor, Cell | Column];
/** Internal method: Get the filter */
getFilter: (column: number, getAsSets?: boolean) => string[] | string[][] | Set<string> | Set<string>[] | undefined;
/** Get the footers configuration */
getFooter: () => Array<any> | undefined;
/** Get the footer value */
getFooterValue: (x: number, y: number) => any;
/** Get the header title */
getHeader: (columnNumber: number) => string;
/** Get all header elements */
getHeaders: (asArray: boolean) => string | string[];
/** Get the height of one row by its position when height is defined. */
getHeight: (row?: number) => Array<number> | number;
/** Bring an array of selection coordinates [x1,y1,x2,y2][]. */
getHighlighted: () => RangeCoords[];
/** Get the data as JSON. */
getJson: (highlighted?: boolean | RangeCoords, processed?: boolean, delimiter?: string, asJson?: boolean, includeFilteredRows?: boolean) => Array<Array<any>> | Array<Record<string, any>> | string;
/** Get the processed data cell shown to the user by the cell name or coordinates. */
getLabel: (cellNameOrColumnNumber: string|number, y?: number, extended?: boolean) => any;
/** Aliases for getLabel */
getLabelFromCoords: (cellNameOrColumnNumber: string|number, y?: number, extended?: boolean) => any;
/** Get the merged cells. Cell name: A1, A2, etc or null for all cells */
getMerge: (cellName?: string) => [number, number] | Record<string, [number, number]> | undefined;
/** Get one or all meta information for one cell. */
getMeta: (cellName: string) => object | undefined;
/** Get the nested cells */
getNestedCell: (x: number, y: number) => HTMLTableCellElement;
/** Get the nested headers */
getNestedHeaders: () => Nested[][] | undefined;
/** Get the next available number in the sequence */
getNextSequence: () => number | null;
/** Alias to getProperty */
getOptions: (x: number, y?: number) => Cell | ColumnInstance | undefined;
/** Get the primaryKey column when applicable. */
getPrimaryKey: () => number | false;
/** Get processed data by the coordinates of the cell. Extended process a color, progressbar and rating as raw. */
getProcessed: (x: number, y: number, extended?: boolean) => any;
/** Get the properties for one column when only x is present or the cell when x and y is defined. */
getProperties: (x: number, y?: number) => Cell | ColumnInstance | undefined;
/** Deprecated. Legacy alias to getProperties */
getProperty: (x: number, y?: number) => Cell | ColumnInstance | undefined;
/** Get the selection in a range format */
getRange: (coords?: RangeCoords, includeName?: boolean) => string;
/** Get a row data or meta information by Id. */
getRowById: (row: number, element?: boolean) => RowInstance | false | any[][] | Record<string, any>[];
/** Get the data from one row */
getRowData: (row: number, processed?: boolean) => any[] | Record<string, any> | undefined;
/** Get the row id from its position */
getRowId: (row: number, primaryKey?: boolean) => any;
/**
* Get the selected cells
* @param {boolean?} columnNameOnly - Return an array of cell names or cell DOM elements
*/
getSelected: (columnNameOnly?: boolean) => string[] | { x: number, y: number }[];
/** Get the coordinates of the main selection */
getSelection: (preserveOrder?: boolean) => RangeCoords | undefined;
/** Get the selected columns indexes */
getSelectedColumns: (visibleOnly?: boolean) => number[];
/** Get the selected rows indexes. */
getSelectedRows: (visibleOnly?: boolean) => number[];
/**
* Retrieves CSS styles for a cell or all cells.
* @intent get-cell-style, read-formatting
* @param cellName - Cell name (e.g., "A1"); if omitted, returns all styles.
* @param onlyIndexes - If true, returns style indices instead of full styles.
* @returns {string | number | Record<string, string> | Record<string, number> | undefined} - Style value, index, or object of styles.
* @example
* getStyle("A1"); // "background-color: red"
* getStyle(); // { "A1": "background-color: red", "B2": "font-weight: bold" }
*/
getStyle: (cellName?: string | null, onlyIndexes?: boolean) => string | number | Record<string, string> | Record<string, number> | undefined;
/** Get the style index from a cell or all cells */
getStyleIndexes: (cellName?: string | null) => number | Record<string, number> | undefined;
/** Find a style ID from a style string. Null when no styleId is found */
getStyleId: (styleString?: string) => number | null;
/** Get value by the cell name or object. The value can be the raw or processed value. */
getValue(cell: string, processed?: boolean): Array<Array<any>> | Array<Record<string, any>> | string;
getValue(cell: { x: number, y: number }, processed?: boolean): any;
/** Get value by the coordinates. The value can be the source or processed value, including not formatted proceed data. */
getValueFromCoords: (x: number, y: number, processed?: boolean, raw?: boolean) => any;
/** Get the width of one column by index or all column width as an array when index is null. */
getWidth: (column?: number) => Array<number> | number;
/** Go to the row number, [col number] */
goto: (row?: number | null, column?: number | null) => void;
/** Hold the header container */
headerContainer: HTMLElement;
/** Hide column */
hideColumn: (column: number|number[]) => void;
/** Hide the filters for column, columns or cell range. */
hideFilter: (colNumber?: number | string) => void;
/** Hide index column */
hideIndex: () => void;
/** Hide row */
hideRow: (row: number|number[]) => void;
/** Hide the search container */
hideSearch: () => void;
/**
* Add new column(s)
* @param column - number of columns or array with column information
* @param columnNumber - reference when the first argument is a number
* @param insertBefore - insertBefore when the first argument is a number
*/
insertColumn(column?: number, columnNumber?: number, insertBefore?: boolean) : false | undefined;
/** Add new columns in a batch */
insertColumn(columns: newColumn[]) : false | undefined;
/**
* Inserts one or more rows at a specified position.
* @intent add-rows, insert-row
* @param row - Number of rows to add or array of row data/options.
* @param rowNumber - Insert position (zero-based), optional if `row` is array.
* @param insertBefore - If true, inserts before `rowNumber`; if false, after. Defaults to false.
* @returns {false | undefined} - False if invalid, undefined on success.
* @example
* insertRow(1, 0, true); // Add 1 row before row 0
* insertRow([{ row: 0, data: ["a", "b"] }]); // Insert row with data
*/
insertRow(row?: number | newRow[], rowNumber?: number, insertBefore?: boolean) : false | undefined;
insertRow(rows: newRow[]) : false | undefined;
/** Check if cell is attached to the DOM */
isAttached: (x: number, y: number) => boolean;
/** The worksheet is editable */
isEditable: () => boolean;
/** Check if the cell is merged */
isMerged: (x: number, y: number) => Records | false;
/** Check if cell is readonly or not by cellName or Coordinates. isReadonly('A1') or isReadonly(x, y) */
isReadOnly(cellNameOrX: string, y?: undefined, ignoreLocked?: boolean): boolean | null;
isReadOnly(cellNameOrX: number, y: number, ignoreLocked?: boolean): boolean | null;
/** Check if the row is merged */
isRowMerged: (row: number) => Records | undefined;
/** Verify if this coordinates is within a selection or blank for the current selection */
isSelected: (x: number, y: number, selection?: RangeCoords) => boolean;
/** Navigation last */
last: (shiftKey?: boolean, ctrlKey?: boolean) => void;
/** Navigation left */
left: (shiftKey?: boolean, ctrlKey?: boolean, jump?: boolean) => void;
/** Change the data without events */
loadData: (data: any[], adjustDimension?: boolean) => void;
/** HTML element that contains the floating media */
media: HTMLDivElement;
/** Move one or more columns to another position */
moveColumn: (col: number, to: number, quantityOfColumns?: number) => false | undefined;
/** Move one or more rows to another position */
moveRow: (row: number, to: number, quantityOfRows?: number) => false | undefined;
/** Get the column name */
name: (col: number) => string | number;
/** Start the edition for one cell */
openEditor: (cell: HTMLElement, empty?: boolean, mouseEvent?: object) => false | undefined;
/** Open the filters */
openFilter: (column: number) => void;
/** Worksheet configuration */
options: Worksheet;
/** Sort one column by its position. ASC (0) or DESC (1) */
orderBy: (column: number, direction?: boolean, internalValueController?: number[], internalPreviousStateController?: any) => void;
/** Change page when using pagination */
page: (pageNumber: number | null, callBack?: Function) => false | undefined;
/** Move the scroll page down */
pageDown: () => void;
/** Current page number */
pageNumber: number;
/** Move the scroll page up */
pageUp: () => void;
/** Pagination DOM container */
pagination: HTMLElement;
/** Spreadsheet object */
parent: spreadsheetInstance;
/** Paste */
paste: (x: number, y: number, data: string | any[], selections?: boolean) => false | undefined;
/** Call the print extension when applicable */
print: () => void;
/** Get the quantity of pages when pagination is active */
quantityOfPages?: () => number | false;
/** Array container for all cell DOM elements */
records: Records[][];
/** Refresh the borders by the border name */
refreshBorders: (border?: string) => void;
/** Refresh footers */
refreshFooter: () => void;
/** Remove the merged cells by the cell name or a object with all cells to be removed. */
removeMerge: (cellName: string | Record<string, any>) => false | undefined;
/**
* Removes borders by alias or all borders.
* @intent remove-borders, clear-highlighting
* @param border - Border identifier to remove (optional, null for all).
* @param permanent - If true, removes permanently; if false, temporary.
* @returns {boolean | undefined} - True if successful, false if no border found.
*/
resetBorders: (border?: string, permanent?: boolean) => void;
/** Reset the filter of one or all columns */
resetFilters: (colNumber?: number, destroy?: boolean) => void;
/** Destroy the footers */
resetFooter: () => void;
/** Destroy freeze columns */
resetFreezeColumns: () => void;
/** Reset meta data of one or multiple cells. Null for all cells */
resetMeta: (cellName?: string[]|string) => false | undefined;
/** Reset nested headers */
resetNestedHeaders: () => void;
/** Reset the search */
resetSearch: () => void;
/** Reset the main selection */
resetSelection: () => boolean;
/** Get the style from one cell. Ex. resetStyle('A1') or resetStyle(['A1']) */
resetStyle: (cell?: string|string[]) => false | undefined;
/** DOM array of results */
results: Array<number> | null;
/** Navigation right */
right: (shiftKey?: boolean, ctrlKey?: boolean, jump?: boolean) => void;
/** Rotate the spreadsheet cell text. cell = A1, B1... etc */
rotate: (cell: string|string[], value:number) => void;
/** Array of row objects */
rows: RowInstance[] | Record<number, RowInstance>;
/** Persistence helper method. The callback is executed with a JSON from the server */
save: (url: string, data: object, token?: string, callback?: (result: object) => void) => void;
/** Search for something */
search: (str: string) => false | undefined;
/** Search HTML container */
searchContainer: HTMLElement;
/** Search HTML input */
searchInput: HTMLElement;
/** Select All */
selectAll: () => void;
/** Selected cells */
selectedCell: RangeCoords | null;
currentSelection: RangeCoords | null;
/** Internal record id sequence */
sequence: number;
/**
* Adds a colored border to a cell range with a unique identifier.
* @intent highlight-cells, create-border
* @param x1 - Starting column index (0 or positive).
* @param y1 - Starting row index (0 or positive).
* @param x2 - Ending column index (≥ x1).
* @param y2 - Ending row index (≥ y1).
* @param border - Unique border identifier.
* @param color - Hex color code (e.g., "#FF0000"), defaults to random if omitted.
* @example
* setBorder(0, 1, 3, 5, "highlight1", "#FF0000"); // Red border A2:D6
*/
setBorder: (x1: number, y1: number, x2: number, y2: number, border: string, color?: string) => void;
/** Set attributes for one cell */
setCells(cellName: Record<string, Cell>): false | undefined;
setCells(cellName: string, settings: Cell): false | undefined;
/** Set the column data from its number */
setColumnData: (col: number, data: any[], force?: boolean) => void;
/**
* Adds or updates comments for one or more cells.
* @intent add-comment, set-note
* @param cells - Cell name (e.g., "A1") or object mapping cells to comments.
* @param comments - Comment text or object (required if `cells` is string).
* @returns {false | undefined} - False if read-only, undefined on success.
* @example
* setComments("A1", "Check this"); // Comment on A1
* setComments({ "A1": "Note 1", "B2": { comments: "Note 2", user_id: 1 } }); // Batch comments
*/
setComments(cells: string, comments: string|Comment): false | undefined;
setComments(cells: Record<string, string|Comment>): false | undefined;
/** Set the cache for one or multiple cells */
setCache(cellName: Record<string, any>): false | undefined;
setCache(cellName: string, values?: any): false | undefined;
/** Change the worksheet settings */
setConfig(config: Worksheet | Spreadsheet, spreadsheetLevel?: boolean) : void;
/** Set the worksheet data */
setData: (data: any[]) => void;
/** Create or update names */
setDefinedNames: (names: DefinedNames | DefinedNames[]) => void;
/** Reset names by indexes */
resetDefinedNames: (names: DefinedNames[]) => void;
/** Set filter */
setFilter: (colNumber: number, keywords?: string[]) => void;
/** Set the footers */
setFooter: (data: any[][]) => void;
/** Set the footer value */
setFooterValue: (col: number, row: number, value: any) => void;
/** List of columns to freeze. Should be a number or an array of consecutive numbers. Example: [4,5,6] */
setFreezeColumns: (num?: number | number[] | null) => void;
/**
* Sets or resets a column header title.
* @intent set-column-title, rename-header
* @param colNumber - Column index (zero-based).
* @param title - New header title; if empty or null, resets to default (e.g., "A").
* @returns {false | undefined} - False if read-only, undefined on success.
* @example
* setHeader(0, "Name"); // Set column A to "Name"
* setHeader(1, ""); // Reset column B to "B"
*/
setHeader: (colNumber: number, title?: string) => false | undefined;
/** Set the height of one row by its position. currentHeight is for internal use only */
setHeight: (row: number|number[], height: number|number[], currentHeight?: number|number[]) => void;
/**
* Merges cell ranges based on a configuration or single cell specification.
* @intent merge-cells, combine-cells
* @param cellName - Cell name (e.g., "A1") or merge config (e.g., { "A1": [3, 2] }).
* @param colspan - Columns to span (required if `cellName` is string).
* @param rowspan - Rows to span (required if `cellName` is string).
* @returns {false | undefined} - False if invalid or overlapping, undefined on success.
* @example
* setMerge("A1", 3, 2); // Merge A1:C2
* setMerge({ "A1": [3, 2], "D4": [2, 4] }); // Merge A1:C2 and D4:E7
*/
setMerge(cellName: string, colspan: number, rowspan: number): false | undefined;
setMerge(cells: MergeConfig): false | undefined;
/** Get one or various meta information for one cell. */
setMeta: (cell: string | Record<string, any>, property?: string, value?: string) => false | undefined;
/** Set the nested headers */
setNestedHeaders: (config: Nested[][]) => void;
/** Deprecated. Alias for parent.setPlugins */
setPlugins: (plugins: Record<string, Plugin>) => void;
/** Add a new configuration settings for a column or cell */
setProperty(columnNumber: number, rowNumber: number, cellSettings?: Cell): boolean;
setProperty(columnNumber: number, columnSettings: Column): boolean;
setProperty(changes: ({ x: number, value: Column } | { x: number, y: number, value: Cell })[]): boolean;
setProperty(changes: Record<string, Cell>): boolean;
/** Add new properties to the existing column or cell settings */
updateProperty(columnNumber: number, rowNumber: number, cellSettings?: Cell, ignoreDOM?: boolean): void;
updateProperty(columnNumber: ({ x: number, value: Column } | { x: number, y: number, value: Cell })[], rowNumber?: undefined, cellSettings?: undefined, ignoreDOM?: boolean): void;
/** Set or reset the cell as readonly */
setReadOnly: (cellName: string|HTMLElement, state: boolean) => void;
/** Set the data from one row */
setRowData: (row: number, data: any[], force?: boolean) => void;
/**
* Assigns custom IDs to one or more rows for tracking or syncing.
* @intent update-row-ids, set-row-identifiers
* @param row - Row index or object mapping indices to IDs (e.g., { 0: 1000 }).
* @param newId - New ID for a single row (required if `row` is a number).
* @example
* setRowId(0, 1000); // Set row 0 to ID 1000
* setRowId({ 0: 1000, 1: 1001 }); // Batch update
*/
setRowId(row: Record<number, number>): void;
setRowId(row: number, newId: number): void;
/**
* Applies CSS styles to one or more cells.
* @intent format-cells, set-style
* @param cell - Cell name (e.g., "A1"), array of cells, or style object (e.g., { "A1": "color: red" }).
* @param property - CSS property (e.g., "background-color"), required if `cell` is not an object.
* @param value - CSS value (e.g., "red"), optional if `cell` is an object.
* @param forceOverwrite - If true, applies even to locked cells. Defaults to false.
* @returns {false | undefined} - False if invalid, undefined on success.
* @example
* setStyle("A1", "background-color", "red"); // Red background for A1
* setStyle({ "A1": "color: blue", "B2": "font-weight: bold" }); // Batch styling
*/
setStyle(cell: string | string[] | { x: number, y: number }[], property: string, value?: string, forceOverwrite?: boolean): false | undefined;
setStyle(cell: Record<string, string>, property?: undefined, value?: undefined, forceOverwrite?: boolean): false | undefined;
/**
* Writes a value to a cell or range, optionally forcing over read-only cells.
* @intent set-cell-value, write-data
* @param cell - Cell identifier (e.g., "A1") or array of coordinate-value objects (e.g., [{ x: 0, y: 0, value: "test" }]).
* @param value - Value to set (required if `cell` is a string).
* @param forceOverwrite - If true, writes even to read-only cells. Defaults to false.
* @param origin - Source of change (e.g., "user", "script"). Optional.
* @returns {false | undefined} - False if operation fails (e.g., invalid cell), undefined on success.
* @example
* setValue("A1", "Hello"); // Set A1 to "Hello"
* setValue([{ x: 0, y: 0, value: "Test" }, { x: 1, y: 1, value: 42 }]); // Batch update
*/
setValue: (cell: SetValueFirstArgument, value?: any, forceOverwrite?: boolean, origin?: string) => false | undefined;
/**
* Set a cell value
*
* @param x
* @param y
* @param value value
* @param force value over readonly cells
*/
setValueFromCoords: (x: number, y: number, value: any, force?: boolean) => void;
/** Set viewport width and height */
setViewport: (width?: number, height?: number) => void;
/** Set the width of one column by its position */
setWidth: (col: number | number[], width: number | number[], oldWidth?: number | number[]) => void;
/** Show column */
showColumn: (column: number|number[]) => void;
/** Show filter controls for one column, all columns or a cell range */
showFilter: (columnOrCellRange?: number | string | null) => void;
/** Show index column */
showIndex: () => void;
/** Show row */
showRow: (row: number|number[]) => void;
/** Hide the search container */
showSearch: () => void;
/** DOM Worksheet table */
table: HTMLElement;
/** DOM Worksheet table thead */
thead: HTMLElement;
/** DOM Worksheet table tbody */
tbody: HTMLElement;
/** DOM Worksheet table tfoot */
tfoot: HTMLElement;
/** Navigation up */
up: (shiftKey?: boolean, ctrlKey?: boolean, jump?: boolean) => void;
/**
* Internal method: Internal method: Set a cell value
*
* @param x
* @param y
* @param value value
* @param force value over readonly cells
*/
updateCell: (x: number, y: number, value: any, force?: boolean) => void;
/** Internal method: update cells in a batch */
updateCells: (o: Record<string, any>[]) => void;
/** Update the selection based on coordinates */
updateSelectionFromCoords: (x1: number, y1: number, x2?: number, y2?: number, origin?: boolean, type?: string, color?: string) => void;
/** Getter/setter the value by coordinates */
value?: (x: number | string, y: number, value?: any, removeProperty?: boolean) => any;
/** Current page or which page the row number is */
whichPage?: (row?: number) => number | false | null;
/** Get all group of rows */
getRowGroup: () => Record<number, { group: number, state: boolean }>;
/** Create a new group of rows */
setRowGroup: (row: number, numOfItems?: number, state?: boolean, ignoreHistory?: boolean) => void;
/** Open a new group of rows */
openRowGroup: (row: number) => void;
/** Close a new group of rows */
closeRowGroup: (row: number) => void;
/** Reset a group of rows */
resetRowGroup: (row: number) => void;
/** Get all group of columns */
getColumnGroup: () => Record<number, { group: number, state: boolean }>;
/** Create a new group of columns */
setColumnGroup: (column: number, numOfItems?: number, state?: boolean, ignoreHistory?: boolean) => void;
/** Open a new group of columns */
openColumnGroup: (column: number) => void;
/** Close a new group of columns */
closeColumnGroup: (column: number) => void;
/** Reset a group of columns */
resetColumnGroup: (column: number) => void;
/** Aliases for jspreadsheet.helpers. Tools to handle spreadsheet data */
helpers: Helpers;
/** Internal persistence handler */
persistence: Function;
/** Deprecated. Alias for parent.undo */
undo: () => void;
/** Deprecated. Alias for parent.redo */
redo: () => void;
/** Visible columns on the viewport */
visibleRows?: number[];
/** Visible columns on the viewport */
visibleCols?: number[];
/** Viewport current width */
width?: number;
/** Viewport current width */
height?: number;
/** Get the row object or get the rows configuration when pass null. */
getRow: (row?: number) => Row[] | RowInstance;
/** Internal nested headers DOM container */
nested?: object;
/** List of rows to freeze. Should be a number or an array of consecutive numbers. Example: [4,5,6] */
setFreezeRows: (numberOfRows?: number | number[] | null) => void;
/** Reset the freeze rows */
resetFreezeRows: () => void;
/** Reset the properties of a cell */
resetProperty: (x: number, y: number) => boolean;
/** Internal method */
setFormula: () => void;
/** Update nested cell properties */
setNestedCell(x: number, y: number, properties: Nested): false | undefined;
setNestedCell(
changes: {
x: number,
y: number,
properties: Nested
}[]
): false | undefined;
/** Get a validation object. */
getValidations: (validationIndex?: number) => Validation | Validation[] | undefined;
/** Insert or update existing validations by index. */
setValidations: (validations: Validations | Validations[]) => false | undefined;
/** Reset validations by validation indexes. Undefined will remove all validations */
resetValidations: (validationIndex?: number | number[]) => false | undefined;
/** Load all validations rules from a cell based on its coordinates. */
loadValidations(xOrCell: Records, y?: undefined, includeIndexes?: boolean): Validation[] | { index: number, rules: Validation }[] | undefined;
loadValidations(xOrCell: number, y: number, includeIndexes?: boolean): Validation[] | { index: number, rules: Validation }[] | undefined;
/** This method returns true if a cell fails to meet all the defined validation criteria. If invoked without arguments, this method will scan the entire worksheet and return true if it detects validation errors. */
hasErrors(): boolean;
hasErrors(col: string): boolean;
hasErrors(col: number, row: number): boolean;
/** Resize columns to match the visible content */
autoWidth: (columns: number[]) => void;
/** Show the column headers */
showHeaders: () => void;
/** Hide the column headers */
hideHeaders: () => void;
/** Refresh the search on the viewport */
updateSearch: () => void;
/** Get the worksheet index by instance or worksheetId */
getWorksheet(worksheetIdent: worksheetInstance): number | false;
getWorksheet(worksheetIdent: string, instance?: boolean): worksheetInstance | number | false;
/** Open a worksheet */
openWorksheet: (position?: number, force?: boolean) => void;
/** Create a new worksheet */
createWorksheet: (worksheetOptions: Worksheet, position?: number) => false | worksheetInstance;
/** Delete an existing worksheet by its position */
deleteWorksheet: (position?: number) => false | undefined;
/** Rename an existing worksheet by its position */
renameWorksheet: (position: number | undefined, title: string) => false | undefined;
/** Move the position of a worksheet. ignoreDomUpdates: true will block updates to the DOM */
moveWorksheet: (from: number, to: number, ignoreDomUpdates?: boolean) => false | undefined;
/** Get the active worksheet when applicable */
getWorksheetActive: () => number;
/** Get the worksheet name */
getWorksheetName: (position?: number) => string | undefined;
/** Get the worksheet instance by its name */
getWorksheetInstanceByName: GetWorksheetInstanceByNameFunction;
/** Set a worksheet state visibility */
setWorksheetState: (worksheetIndex: number, state: boolean) => void;
/** Parse the toolbar definitions with defaults */
getToolbar: (toolbar?: Toolbar | ToolbarItem[] | Function) => object;
/** Set the toolbar */
setToolbar: (toolbar: Toolbar | ToolbarItem[] | Function) => void;
/** Show the toolbar */
showToolbar: () => void;
/** Hide the toolbar */
hideToolbar: () => void;
/** Refresh the toolbar based on the current worksheet */
refreshToolbar: (worksheet?: worksheetInstance) => void;
/**
* Adds or updates media elements (charts, images, shapes) in the worksheet.
* @intent add-charts, insert-images, create-shapes
* @param items - Array of media objects to add or update (e.g., charts, images).
* @returns {false | undefined} - False if invalid, undefined on success.
* @example
* setMedia([{ id: "random-guid", type: "chart", top: 50, options: { type: "bar", range: "A1:B10" } }]);
* setMedia([{ id: "random-guid", type: "image", src: "logo.png", top: 10, left: 10 }]);
*/
setMedia: (items: Media[]) => false | undefined;
/** Get a media element position or object by guid. */
getMedia: (guid: string, position?: boolean) => number | Media | null;
/**
* Deletes media elements by their GUIDs.
* @intent delete-media, remove-chart
* @param items - Array of GUIDs or objects with id to delete.
* @example
* deleteMedia(["chart1", { id: "img1" }]);
*/
deleteMedia: (items: DeleteMediaItem[]) => false | undefined;
/** Add a global formula to the tracking system. Use from formula pro. Only use if necessary. */
setTracking: () => void;
/** Set a worksheet zoom value > 0 and <= 1. */
setZoom: (value: number) => void;
/** Get the current zoom value. Default 1 */
getZoom: () => number;
/** Get the coordinates as a number from a range string. Adjust helps to define the height dynamically when you have A:A ranges for example. Works in the same way for 1:1 ranges. Default: true */
getCoordsFromRange: (range: string, adjust?: boolean) => [number | null, number | null, number | null, number | null];
/** Edition handler */
edition: HTMLElement;
/** Get the cell object by its coords */
getCellObject: (x: number, y: number) => Records;
}
interface International {
/** User locale **/
locale: string;
/** General number format */
NumberFormat?: Intl.NumberFormat;
}
interface parseOptions {
/** Load the XLSX from a remote URL. Bear in mind any potential CORS restrictions using this property. */
url?: string;
/** Define the decimal and a thousand separator based on a locale. */
locale?: string;
/** Try to import embed cell style as HTML */
parseHTML?: boolean;
/** Enable or disable the loading spin. Default: true */
loadingSpin?: boolean;
/** load from a local file. This property is used along input type='file' */
file?: object;
/** When the file is loaded. */
onload?: (config: jspreadsheet.Spreadsheet) => void;
/** Method to be called when something is wrong. */
onerror?: (error: object) => void;
}
}
export default jspreadsheet;