Loading and Saving

Loading and Saving State

Most models implement the JSONSerializable interface which enables a common API for loading and saving state as JSON.

Model with public constructors also have an json property in the constructor options that matches the type of the toJSON().

Save to JSON

const asJSON:IWorkbook.JSON = workbook.toJSON();
// save asJSON to local storage or db

Read from JSON

const json:IWorkbook.JSON = { /* Json loaded from db, local storage, or other location */ };
const workbook:IWorkbook = new Workbook({ json });

Create workbook model from initial data

A common use case is to just display a Workbook with initial data.
The Workbook constructor also takes a 2D array of Scalars.

const workbook:IWorkbook = new Workbook();
workbook.getSelectedSheet().getRange('A1:C3').setValues([
  [1,2,3],
  [4,5,6],
  [7,8,9]
]);

Import and Exporting

Using SDK

Import and exporting file formats other than the native SheetXL JSON type is done using using @sheetxl/io module.

The formats, including native JSON, currently supported are:

• SheetXL JSON (native)
• CSV
• Excel
• Parquet (in beta)

@sheetxl/io/WorkbookIO

/**
 * Read from local file system using available IO handlers.
 * The input can be either a File, a Promise<File>, or a string.
 * If a string is provided, if should be either an extension or a mimetype
 * that will be passed to the accept attribute of an
 * input: {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept}.
 *
 * @param options The options ReadWorkbookOptions for loading the workbook.
 * @returns A promise that resolves to an ImportResults object.
 *
 */
import { WorkbookIO } from '@sheetxl/io';

WorkbookIO.read(
  options: ReadWorkbookOptions
): Promise<ImportResults>;

// Import from a file
const result1 = await WorkbookIO.read({
  source: myFile,
  name: 'My Spreadsheet'
});

// Import from base64 (explicit disambiguation)
const result2 = await WorkbookIO.read({
  source: { base64: 'iVBORw0KGgo...' },
  format: 'xlsx'
});

// Import from URL
const result3 = await WorkbookIO.read({
  source: 'https://www.sheetxl.com/docs/examples/financial-calculators.xlsx'
});

// Import from array buffer
const result4 = await WorkbookIO.read({
  source: myArrayBuffer,
  format: 'csv',
  name: 'data.csv'
});

/**
 * Exports to the local file system attempting to use the fileName provided. This will
 * use the exportType to determine the export handler to use.
 *
 * @returns A Promise indicating success or failure.
 */
WorkbookIO.writeFile(
  fileName: string | null,
  workbook: IWorkbook,
  exportType?: ExportType
): Promise<boolean>;

tip

The full source documentation is available at IWorkbookIO API

Using Studio

If using the Studio React component this capabilities is wrapped in the workbook prop.

Studio Import/Export

import { IWorkbook } from '@sheetxl/sdk';
import { Studio } from '@sheetxl/mui-studio';

// Instead of loading we can load from source URL
// We need to wrap in a memo to ensure we don't rerender
const workbookSource = useMemo(() => {
  return {
    // Lots of options available
    source: 'https://www.sheetxl.com/docs/examples/financial-calculators.xlsx',
    // Not required but if the viewer is meant to be readonly
    readonly: true
  }
}, []);

<Studio
  workbook={workbookSource}
  {/* Listen for when the results have be loaded */}
  onWorkbookChange={(workbook: IWorkbook | null) => {
    console.log('workbook changed', workbook);
  }}
/>

Studio Example

The following code sandbox shows a React application loading a read only viewer:

CodeSandbox-Studio-IO

note

If another format is needed or something is missing please let me know.