Import and export

The APIs below need a conversion backend. Follow file exchange integration to connect uploads, conversion, task queries, and downloads, then configure the browser plugins. Snapshot APIs also need that backend, but do not require a collaborative document.

Supported formats

The table describes the browser APIs on this page. Office file conversion requires a backend that supports the same document type and format.

Import	Export
`.xls`, `.xlsx`, `.csv`, `.tsv`	`.xlsx`, `.csv`, `.tsv`

CSV and TSV export one worksheet. They do not preserve workbook formatting or multiple sheets. Pass ExchangeFormat.CSV or ExchangeFormat.TSV and the sheetId to the export API; XLSX is the default. The browser API does not accept .xlsm, even when the conversion backend supports it.

Facade API

Importing

Plugin mode note

Only plugin mode requires manually importing the Facade package. Preset mode already includes the corresponding Facade package, so no extra import is needed.

TypeScript

import '@univerjs-pro/exchange-client/facade'import '@univerjs-pro/sheets-exchange-client/facade'

Importing `.xlsx`

Import `.xlsx` file and get `unitId`

Caution

This method requires collaboration: it creates a server document and returns a unitId. Use snapshot import if collaboration is not enabled.

When collaborative editing is enabled, each document has a unique unitId. Using univerAPI.importSheetToUnitIdAsync with the file parameter will return the unitId, which can be used to access the document. The file parameter can be a File object or a remote file URL.

TypeScript

import '@univerjs-pro/collaboration-client/facade'const unitId = await univerAPI.importSheetToUnitIdAsync(file)if (unitId) {  await univerAPI.getCollaboration().loadSheetAsync(unitId)}

Import `.xlsx` file and get `IWorkbookData`

Snapshot import does not require collaboration. Use unitId import for collaborative documents.

Using univerAPI.importSheetToSnapshotAsync to import a .xlsx file will return the document data in the IWorkbookData format.

TypeScript

// Accept a File objectconst snapshot = await univerAPI.importSheetToSnapshotAsync(file)// Or accept a remote file URL// const snapshot = await univerAPI.importSheetToSnapshotAsync('https://example.com/filename.xlsx');// Create a new workbook via snapshotif (snapshot) univerAPI.createWorkbook(snapshot)

Exporting `.xlsx`

Export `.xlsx` file using `unitId`

Caution

unitId export requires collaboration. If collaboration is not enabled, use snapshot export.

When collaborative editing is enabled, each document has a unique unitId. Using univerAPI.exportSheetByUnitIdAsync with the unitId parameter will return a File object.

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const unitId = fWorkbook.getId()const file = await univerAPI.exportSheetByUnitIdAsync(unitId)// Download the file through the Facade APIif (file) univerAPI.downloadFile(file, 'univer', 'xlsx')

Export `.xlsx` file using `IWorkbookData`

Snapshot export does not require collaboration and is suitable for local workflows.

Using univerAPI.exportSheetBySnapshotAsync with the IWorkbookData will return a File object.

TypeScript

const fWorkbook = univerAPI.getActiveWorkbook()const snapshot = fWorkbook.save()const file = await univerAPI.exportSheetBySnapshotAsync(snapshot)// Download the file through the Facade APIif (file) univerAPI.downloadFile(file, 'univer', 'xlsx')

How is this guide?