SpreadJS supports the opening and saving to several popular file formats including Excel .xlsx/.xlsm, .csv, .ssjson (older SpreadJS format) and the new faster .sjs SpreadJS file formats. The new .sjs format significantly improves the load time and memory usage when working with very large Excel files while greatly reducing the file size when resaved as compared to previous SpreadJS versions.
Learn more about opening password protected Excel files.
In order to use the SpreadJS File Format
feature, you need to add the related js file link into the document's head section below the Spread link. For example:
<head>
...
<script src='.../spreadjs/gc.spread.sheets.all.x.x.x.min.js' type='text/javascript'></script>
<script src='.../spreadjs/plugins/gc.spread.sheets.io.x.x.x.min.js' type='text/javascript'></script>
</head>
SpreadJS supports opening and saving sjs file formats. It also supports importing and exporting xlsx, ssjson, and csv file formats.
For example:
// open the sjs file to spread.
spread.open(file, function () {
// success callback to do something
}, function (e) {
console.log(e); // error callback
});
// save spread to sjs file.
spread.save(function (blob) {
// save blob to a file
saveAs(blob, fileName);
}, function (e) {
console.log(e);
});
// import the xlsx, ssjson, csv file to spread.
spread.import(file, function () {
// success callback to do something
}, function (e) {
console.log(e); // error callback
}, {
fileType: GC.Spread.Sheets.FileType.excel
});
// export spread to xlsx, ssjson, csv file.
spread.export(function (blob) {
// save blob to a file
saveAs(blob, fileName);
}, function (e) {
console.log(e);
}, {
fileType: GC.Spread.Sheets.FileType.excel
});
export class Workbook {
///* function GC.Spread.Sheets.@Workbook.save(successCallBack?: Function, errorCallBack?: Function, saveOptions?: GC.Spread.Sheets.SaveOptions): void
/**
* Saves the spreadJS state to a sjs file.
* @param {function} successCallBack - The success callback when save spreadJS state complete, accept Blob as argument.
* @param {function} errorCallBack - The error callback when save spreadJS state got error.
* @param {GC.Spread.Sheets.SaveOptions} saveOptions - The save options.
* @example
* spread.save(function (blob) {
* // save blob to a file
* saveAs(blob, fileName);
* }, function (e) {
* console.log(e);
* }, { includeUnusedNames: false });
*/
Workbook.prototype.save = function (this: Workbook, successCallBack?: (content: Blob) => {}, errorCallBack?, saveOptions?: SaveOptions): void;
///* function GC.Spread.Sheets.@Workbook.open(file: File, successCallback?: Function, errorCallback?: Function, openOptions?: GC.Spread.Sheets.OpenOptions)
/**
* Loads the object state from the sjs zipped file.
* @param {Blob} file - The zipped spreadsheet data file.
* @param {function} successCallBack - The success callback when import file complete, accept json as argument.
* @param {function} errorCallBack - The error callback when import file got error.
* @param {GC.Spread.Sheets.OpenOptions} [openOptions] - The deserialization options.
* @example
* //This example uses the open method.
* //Get file blob.
* var file = document.getElementById("importFileName").files[0];
* // import
* spread.open(file, function () {
* // success callback to do something
* }, function (e) {
* console.log(e); // error callback
* });
*/
Workbook.prototype.open = function (file: Blob, successCallback?, errorCallback?, openOptions?: OpenOptions): void;
///* function GC.Spread.Sheets.@Workbook.export(successCallBack?: Function, errorCallBack?: Function, exportOptions?: GC.Spread.Sheets.ExportOptions): void
/**
* Exports the object state to excel or ssjson file or csv file.
* @param {function} [successCallBack] The success callback when export object state complete, accept Blob as argument.
* @param {function} [errorCallBack] The error callback when export object state got error.
* @param {GC.Spread.Sheets.ExportOptions} [exportOptions] - The export options.
* @example
* spread.export(function (blob) {
* // save blob to a file
* saveAs(blob, fileName);
* }, function (e) {
* console.log(e);
* }, {
* fileType: GC.Spread.Sheets.FileType.excel,
* includeBindingSource: true
* });
*/
Workbook.prototype.export = function (successCallBack?: (content: Blob) => {}, errorCallBack?, exportOptions?: ExportOptions);
///* function GC.Spread.Sheets.@Workbook.import(file: File, successCallback?: Function, errorCallback?: Function, importOptions?: GC.Spread.Sheets.ImportOptions)
/**
* Imports the object state from the excel or ssJson or csv file.
* @param {File} file - The ssJson or csv or Excel file for import.
* @param {function} [successCallBack] - The success callback when import file complete, accept json as argument. ???
* @param {function} [errorCallBack] - The error callback when import file got error.
* @param {GC.Spread.Sheets.ImportOptions} [importOptions] - The import options.
* @example
* //This example uses the import method.
* //Get file blob.
* var file = document.getElementById("importFileName").files[0];
* // import
* spread.import(file, function () {
* // success callback to do something
* }, function (e) {
* console.log(e); // error callback
* }, {
* fileType: GC.Spread.Sheets.FileType.excel
* });
*/
Workbook.prototype.import = function (file: File, successCallback?, errorCallback?, importOptions?: ImportOptions);
}
///* typedef GC.Spread.Sheets.SaveOptions
/**
* @typedef GC.Spread.Sheets.SaveOptions
* @property {boolean} [includeBindingSource] - Whether to include the binding source when do save, default false.
* @property {boolean} [includeStyles] - Whether to include the style when do save, default true.
* @property {boolean} [includeFormulas] - Whether to include the formula when do save, default true.
* @property {boolean} [saveAsView] - Whether to ignore the format string when do save, default false.
* @property {boolean} [includeAutoMergedCells] - Whether to include the automatically merged cells when do save, default false.
* @property {boolean} [includeCalcModelCache] - Whether to include the extra data of calculation. Can be faster when open the file with those data, default false.
* @property {boolean} [includeUnusedNames] - Whether to include the unused custom name when do save, default true.
* @property {boolean} [includeEmptyRegionCells] - Whether to include any empty cells(cells with no data or only style) outside the used data range, default true.
* @property {boolean} [saveR1C1Formula] - Whether to save the r1c1 formula in the file, only works in sjs file type, default false.
*/
///* typedef GC.Spread.Sheets.OpenOptions
/**
* @typedef GC.Spread.Sheets.OpenOptions
* @property {boolean} [includeStyles] - Whether to include the style when loading, default true.
* @property {boolean} [includeFormulas] - Whether to include the formula when loading, default true.
* @property {boolean} [fullRecalc] - Whether to calculate after loading the json data, false by default.
* @property {boolean} [dynamicReferences] - Whether to calculate functions with dynamic reference, default true.
* @property {boolean} [calcOnDemand] - Whether to calculate formulas only when they are demanded, default false.
* @property {boolean} [incrementalCalculation] - Whether to incremental calculate formulas without blocking UI, default false.
* @property {boolean} [includeUnusedStyles] - Whether to include the name style when converting excel xml to the json, default true.
* @property {GC.Spread.Sheets.OpenMode} [openMode] - The open mode of normal, lazy and incremental. By default is normal.
* @property {GC.Spread.Sheets.ProgressFunctionType} [progress] - The progress callback function for each open mode.
*/
///* enum GC.Spread.Sheets.OpenMode
/**
* The open mode for open sjs function.
* @enum {number}
*/
enum OpenMode {
/**
* normal open mode, without lazy and incremental. When opening file, UI and UI event could be refreshed and responsive at specific time points.
*/
normal = 0,
/**
* lazy open mode. When opening file, only the active sheet will be loaded directly. Other sheets will be loaded only when they are be used.
*/
lazy = 1,
/**
* incremental open mode. When opening file, UI and UI event could be refreshed and responsive directly.
*/
incremental = 2
}
///* typedef GC.Spread.Sheets.ProgressFunctionType
/**
* @typedef GC.Spread.Sheets.ProgressFunctionType
* @param {object} progressArgs - the progress arguments.
* @param {string} [progressArgs.sheetName] - the current loading sheet's name.
* @param {string} progressArgs.step - the current loading step.
* @param {number} progressArgs.progress - the current loading progress, from 0 - 1.
* @returns {void}
* @description The callback when of the incremental loading progress.
*/
export type ProgressFunctionType = (progressArgs: ProgressArgs) => void;
///* typedef GC.Spread.Sheets.ImportOptions
/**
* @typedef {GC.Spread.Sheets.FileOptions & (GC.Spread.Sheets.ImportCsvOptions | GC.Spread.Sheets.ImportSSJsonOptions | GC.Spread.Sheets.ImportXlsxOptions)} GC.Spread.Sheets.ImportOptions - The options for import function. */
/**
GC.Spread.Sheets.FileOptions & (GC.Spread.Sheets.ImportCsvOptions | GC.Spread.Sheets.ImportSSJsonOptions | GC.Spread.Sheets.ImportXlsxOptions)
*/
///* typedef GC.Spread.Sheets.FileOptions
/**
* @typedef GC.Spread.Sheets.FileOptions - The file options for export.
* @property {GC.Spread.Sheets.FileType} fileType - The file type.
*/
/**
{
fileType: GC.Spread.Sheets.FileType
}
*/
///* typedef GC.Spread.Sheets.ExportOptions
/**
* @typedef {GC.Spread.Sheets.FileOptions & (GC.Spread.Sheets.ExportCsvOptions | GC.Spread.Sheets.ExportSSJsonOptions | GC.Spread.Sheets.ExportXlsxOptions)} GC.Spread.Sheets.ExportOptions - The options for export function.
*/
/**
GC.Spread.Sheets.FileOptions & (GC.Spread.Sheets.ExportCsvOptions | GC.Spread.Sheets.ExportSSJsonOptions | GC.Spread.Sheets.ExportXlsxOptions)
*/
///* typedef GC.Spread.Sheets.FileOptions
/**
* @typedef GC.Spread.Sheets.FileOptions - The file options for export.
* @property {GC.Spread.Sheets.FileType} fileType - The file type.
*/
/**
{
fileType: GC.Spread.Sheets.FileType
}
*/
///* typedef GC.Spread.Sheets.ImportXlsxOptions
/**
* @typedef GC.Spread.Sheets.ImportXlsxOptions
* @property {boolean} [includeStyles] - Whether to include the style when loading, default true.
* @property {boolean} [includeFormulas] - Whether to include the formula when loading, default true.
* @property {boolean} [frozenColumnsAsRowHeaders] - Whether to treat the frozen columns as row headers when loading, default false.
* @property {boolean} [frozenRowsAsColumnHeaders] - Whether to treat the frozen rows as column headers when loading, default false.
* @property {boolean} [fullRecalc] - Whether to calculate after loading the json data, false by default.
* @property {boolean} [dynamicReferences] - Whether to calculate functions with dynamic reference, default true.
* @property {boolean} [calcOnDemand] - Whether to calculate formulas only when they are demanded, default false.
* @property {boolean} [incrementalCalculation] - Whether to incremental calculate formulas without blocking UI, default false.
* @property {boolean} [includeUnusedStyles] - Whether to include the name style when converting excel xml to the json, default true.
* @property {boolean} [convertSheetTableToDataTable] - Whether to convert the sheet tables to data manager tables, default false.
* @property {GC.Spread.Sheets.OpenMode} [openMode] - The open mode of normal, lazy and incremental. By default is lazy.
* @property {GC.Spread.Sheets.ProgressFunctionType} [progress] - The progress callback function for each open mode.
*/
/**
{
includeStyles?: boolean;
frozenColumnsAsRowHeaders?: boolean;
frozenRowsAsColumnHeaders?: boolean;
includeFormulas?: boolean;
fullRecalc?: boolean;
dynamicReferences?: boolean;
calcOnDemand?: boolean;
includeUnusedStyles?: boolean;
convertSheetTableToDataTable?: boolean;
incrementalCalculation?: boolean;
openMode?: GC.Spread.Sheets.OpenMode;
progress?: GC.Spread.Sheets.ProgressFunctionType
}
*/
///* typedef GC.Spread.Sheets.ExportXlsxOptions
/**
* @typedef GC.Spread.Sheets.ExportXlsxOptions
* @property {boolean} [includeBindingSource] - Whether to include the binding source when do save, default false.
* @property {boolean} [includeStyles] - Whether to include the style when do save, default true.
* @property {boolean} [includeFormulas] - Whether to include the formula when do save, default true.
* @property {boolean} [saveAsView] - Whether to ignore the format string when do save, default false.
* @property {boolean} [rowHeadersAsFrozenColumns] - Whether to treat the row headers as frozen columns when do save, default false.
* @property {boolean} [columnHeadersAsFrozenRows] - Whether to treat the column headers as frozen rows when do save, default false.
* @property {boolean} [includeAutoMergedCells] - Whether to include the automatically merged cells when do save, default false.
* @property {boolean} [includeUnusedNames] - Whether to include the unused custom name when do save, default true.
* @property {boolean} [includeEmptyRegionCells] - Whether to include any empty cells(cells with no data or only style) outside the used data range, default true.
*/
/**
{
includeBindingSource?: boolean;
includeStyles?: boolean;
includeFormulas?: boolean;
saveAsView?: boolean;
rowHeadersAsFrozenColumns?: boolean;
columnHeadersAsFrozenRows?: boolean;
includeUnusedNames?: boolean;
includeEmptyRegionCells?: boolean;
includeAutoMergedCells?: boolean;
}
*/
///* typedef GC.Spread.Sheets.ImportCsvOptions
/**
* @typedef GC.Spread.Sheets.ImportCsvOptions
* @property {string} [encoding] - The csv encoding type, the default encoding type is 'UTF-8'.
* @property {string} [rowDelimiter] - The row delimiter that is appended to the end of the row, the default row delimiter is '\r\n'.
* @property {string} [columnDelimiter] - The column delimiter that is appended to the end of the column, the default column delimiter is ','.
*/
/**
{
rowDelimiter?: string;
columnDelimiter?: string;
encoding?: string;
}
*/
///* typedef GC.Spread.Sheets.ExportCsvOptions
/**
* @typedef GC.Spread.Sheets.ExportCsvOptions
* @property {string} [encoding] - The csv encoding type, the default encoding type is 'UTF-8'.
* @property {string} [rowDelimiter] - The row delimiter that is appended to the end of the row, the default row delimiter is '\r\n'.
* @property {string} [columnDelimiter] - The column delimiter that is appended to the end of the column, the default column delimiter is ','.
* @property {object} [range] - The range info.
* @param {number} [range.sheetIndex] - The sheet index, the default sheet index is current active sheet index.
* @param {number} [range.row] - The start row, the default row index is 0.
* @param {number} [range.column] - The start column, the default column index is 0.
* @param {number} [range.rowCount] - The row count, the default row count is current active sheet row count.
* @param {number} [range.columnCount] - The column count, the default column count is current active sheet column count.
*/
/**
{
encoding?: string;
rowDelimiter?: string;
columnDelimiter?: string;
range?: {
sheetIndex: number;
row: number;
column: number;
rowCount: number;
columnCount: number;
}
}
*/
///* typedef GC.Spread.Sheets.ImportSSJsonOptions
/**
* @typedef GC.Spread.Sheets.ImportSSJsonOptions
* @property {boolean} [includeStyles] - Whether to include the style when converting json to the workbook, default true.
* @property {boolean} [includeFormulas] - Whether to include the formula when converting json to the workbook, default true.
* @property {boolean} [frozenColumnsAsRowHeaders] - Whether to treat the frozen columns as row headers when converting json to the workbook, default false.
* @property {boolean} [frozenRowsAsColumnHeaders] - Whether to treat the frozen rows as column headers when converting json to the workbook, default false.
* @property {boolean} [fullRecalc] - Whether to do full recalculation after loading the json data, default true.
* @property {boolean | object} [incrementalLoad] - Whether to use the incremental loading or the callbacks of incremental loading when converting json to the workbook, default false.
* @param {function} [incrementalLoad.loading] - The callback when of the incremental loading progress.
* @param {function} [incrementalLoad.loaded] - The callback when of the incremental loading finished.
*/
/**
{
includeStyles?: boolean;
incrementalLoad?: any;
frozenColumnsAsRowHeaders?: boolean;
frozenRowsAsColumnHeaders?: boolean;
includeFormulas?: boolean;
fullRecalc?: boolean;
}
*/
///* typedef GC.Spread.Sheets.ExportSSJsonOptions
/**
* @typedef GC.Spread.Sheets.ExportSSJsonOptions
* @property {boolean} [includeBindingSource] - Whether to include the binding source when converting the workbook to json, default false.
* @property {boolean} [includeStyles] - Whether to include the style when converting the workbook to json, default true.
* @property {boolean} [includeFormulas] - Whether to include the formula when converting the workbook to json, default true.
* @property {boolean} [saveAsView] - Whether to ignore the format string when converting the workbook to json, default false.
* @property {boolean} [rowHeadersAsFrozenColumns] - Whether to treat the row headers as frozen columns when converting the workbook to json, default false.
* @property {boolean} [columnHeadersAsFrozenRows] - Whether to treat the column headers as frozen rows when converting the workbook to json, default false.
* @property {boolean} [includeAutoMergedCells] - Whether to include the automatically merged cells when converting the workbook to json, default false.
*/
/**
{
includeBindingSource?: boolean;
includeStyles?: boolean;
includeFormulas?: boolean;
saveAsView?: boolean;
rowHeadersAsFrozenColumns?: boolean;
columnHeadersAsFrozenRows?: boolean;
includeAutoMergedCells?: boolean;
}
*/
Submit and view feedback for