# Import and export

- Human documentation: [https://docs.univer.ai/guides/sheets/features/import-export](https://docs.univer.ai/guides/sheets/features/import-export)

- Agent Markdown: [https://docs.univer.ai/guides/sheets/features/import-export.md](https://docs.univer.ai/guides/sheets/features/import-export.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [sheets/features/import-export.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/import-export.mdx)

---

The APIs below need a conversion backend. Follow [file exchange integration](https://docs.univer.ai/server/import-export.md) 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.

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/en-US",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/exchange-client",
      "facade": "@univerjs-pro/exchange-client/facade",
      "locale": "@univerjs-pro/exchange-client/locale/en-US",
      "style": "@univerjs-pro/exchange-client/lib/index.css"
    },
    {
      "client": "@univerjs-pro/sheets-exchange-client",
      "facade": "@univerjs-pro/sheets-exchange-client/facade",
      "locale": "@univerjs-pro/sheets-exchange-client/locale/en-US"
    }
  ],
  "license": true,
  "limitations": "CSV/TSV export one worksheet without workbook formatting. XLSM is not accepted by these browser APIs.",
  "headless": false,
  "server": true
}
```

## 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

> [!INFO: 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`

> [!WARNING: 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`

> [!NOTE]
> 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 object
const 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 snapshot
if (snapshot) univerAPI.createWorkbook(snapshot)
```

### Exporting `.xlsx`

#### Export `.xlsx` file using `unitId`

> [!WARNING: 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 API
if (file) univerAPI.downloadFile(file, 'univer', 'xlsx')
```

#### Export `.xlsx` file using `IWorkbookData`

> [!NOTE]
> 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 API
if (file) univerAPI.downloadFile(file, 'univer', 'xlsx')
```