# Импорт и экспорт

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

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

- Requested language: `ru-RU`

- Content language: `ru-RU`

- Documentation version: `1.2.0`

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

---

#### Package metadata

```json
{
  "preset": [],
  "plugins": [
    {
      "client": "@univerjs-pro/exchange-client",
      "facade": "@univerjs-pro/exchange-client/facade"
    },
    {
      "client": "@univerjs-pro/bases-exchange-client",
      "facade": "@univerjs-pro/bases-exchange-client/facade"
    }
  ],
  "license": true,
  "server": true
}
```

Bases импортирует **XLSX, XLS, CSV и TSV** и экспортирует **XLSX, CSV и TSV**. Например, можно импортировать список клиентов из Excel, добавить поля и представления, затем экспортировать данные таблицы.

Этим API нужен сервер преобразования. Начните с [интеграции обмена файлами](https://docs.univer.ai/ru-RU/server/import-export.md) и убедитесь, что сервер поддерживает документы Bases и нужные форматы.

## Поддерживаемые форматы

Таблица описывает браузерные API этой страницы. Для преобразования файлов Office нужен сервер с поддержкой того же типа документа и формата.

| Импорт                          | Экспорт                 |
| ------------------------------- | ----------------------- |
| `.xls`, `.xlsx`, `.csv`, `.tsv` | `.xlsx`, `.csv`, `.tsv` |

CSV и TSV экспортируют одну таблицу, выбранную через `tableId`. Эти текстовые форматы не сохраняют представления, права и другие ресурсы Base. Для полной резервной копии приложения используйте снимок Base.

## Установка и регистрация

Добавьте пакеты в [инициализированный редактор Bases](https://docs.univer.ai/ru-RU/guides/bases/getting-started/installation.md):

#### npm

```bash
npm install @univerjs-pro/exchange-client @univerjs-pro/bases-exchange-client
```

#### pnpm

```bash
pnpm add @univerjs-pro/exchange-client @univerjs-pro/bases-exchange-client
```

#### yarn

```bash
yarn add @univerjs-pro/exchange-client @univerjs-pro/bases-exchange-client
```

#### bun

```bash
bun add @univerjs-pro/exchange-client @univerjs-pro/bases-exchange-client
```

```ts
import { UniverBasesExchangeClientPlugin } from '@univerjs-pro/bases-exchange-client'
import { UniverExchangeClientPlugin } from '@univerjs-pro/exchange-client'

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

univer.registerPlugin(UniverExchangeClientPlugin, exchangeConfig)
univer.registerPlugin(UniverBasesExchangeClientPlugin)
```

`exchangeConfig` содержит настройки загрузки, преобразования, опроса задач и скачивания файлов; подготовьте их по [руководству интеграции](https://docs.univer.ai/ru-RU/server/import-export.md).

## Импорт для редактирования на странице

`file` может быть выбранным пользователем объектом `File` или URL удалённого файла. Возвращаемый снимок содержит данные Base, которые может загрузить редактор:

```ts
const snapshot = await univerAPI.importBaseToSnapshotAsync(file)
if (snapshot) {
  univerAPI.createBase(snapshot)
}
```

Импорт снимка не требует совместного редактирования, но требует серверного преобразования. Чтобы пользователь мог вернуться к работе, сохраняйте `base.save()` согласно разделу [Сохранение и восстановление снимков](https://docs.univer.ai/ru-RU/guides/bases/model/base-snapshot.md).

## Экспорт файла

Экспортируйте текущую Base в Excel:

```ts
import { ExchangeFormat } from '@univerjs-pro/exchange-client'

const base = univerAPI.getActiveBase()
if (!base) throw new Error('Open a Base first')

const file = await univerAPI.exportBaseBySnapshotAsync(base.save(), ExchangeFormat.XLSX)
if (file) {
  univerAPI.downloadFile(file, 'database', ExchangeFormat.XLSX)
}
```

CSV и TSV представляют одну таблицу. При экспорте Base с несколькими таблицами явно передайте `tableId`:

```ts
const table = base.getTables()[0]
if (!table) throw new Error('Create a table first')

const file = await univerAPI.exportBaseBySnapshotAsync(
  base.save(),
  ExchangeFormat.CSV,
  table.getId(),
)
if (file) {
  univerAPI.downloadFile(file, table.getName(), ExchangeFormat.CSV)
}
```

Для TSV замените `ExchangeFormat.CSV` на `ExchangeFormat.TSV`. Экспорт файлов служит для обмена данными таблиц. Для полной резервной копии сохраните снимок Base: CSV не сохраняет представления, права и другие ресурсы.

## Импорт совместного документа

Подключите [совместное редактирование Bases](https://docs.univer.ai/ru-RU/guides/bases/features/collaboration.md), выполните импорт и загрузите документ по ID, возвращённому сервером:

```ts
import '@univerjs-pro/collaboration-client/facade'

const unitId = await univerAPI.importBaseToUnitIdAsync(file)
if (unitId) {
  await univerAPI.getCollaboration().loadBaseAsync(unitId)
}
```

Для экспорта серверного документа используйте `exportBaseByUnitIdAsync(unitId, format, tableId?)`. Перед экспортом дождитесь синхронизации ожидающих изменений из браузера.

## Структура и формулы Excel

Настройте плагин обмена Bases для изменения поведения преобразования. Ниже приведены значения по умолчанию; используйте эту регистрацию вместо предыдущей:

```ts
import {
  ExchangeBaseExportMode,
  ExchangeBaseFormulaPolicy,
  ExchangeBaseImportMode,
} from '@univerjs-pro/exchange-client'

univer.registerPlugin(UniverBasesExchangeClientPlugin, {
  importSourceMode: ExchangeBaseImportMode.AUTO,
  importFormulaPolicy: ExchangeBaseFormulaPolicy.CONVERT_THEN_VALUES,
  exportStructureMode: ExchangeBaseExportMode.TABLES,
  exportFormulaPolicy: ExchangeBaseFormulaPolicy.FAIL,
})
```

* Источник импорта: `AUTO` автоматически выбирает таблицы Excel и видимые листы; `TABLES` импортирует только таблицы Excel; `SHEETS` — видимые листы; `HYBRID` — таблицы Excel и видимые листы без таблиц Excel.
* Структура экспорта: `TABLES` создаёт нативные таблицы Excel для непустых таблиц Base, оставляя пустые обычными диапазонами. `RANGES` экспортирует всё в обычные диапазоны листа.
* Формулы: импорт пытается преобразовать формулу и использует кешированный результат для неподдерживаемых формул. Экспорт по умолчанию требует успешного преобразования. `VALUES` использует только кешированные результаты, а `TEXT` сохраняет исходные формулы как текст. При экспорте `CONVERT_THEN_VALUES` также завершается ошибкой, если формулу нельзя преобразовать.

Проверяйте преобразование полей и формул на реальных файлах приложения. Методы могут вернуть `undefined` или выбросить ошибку запроса либо преобразования; обработайте оба случая в интерфейсе.

## Удаление встроенных меню и UI-взаимодействий для импорта и экспорта

Univer больше не включает встроенные меню и UI-взаимодействия для импорта и экспорта. Базовые сервисы и Facade API остаются доступными.

Если вашему приложению нужны прежние меню и UI-взаимодействия для импорта и экспорта, используйте [пример миграции встроенных меню и UI-взаимодействий для импорта и экспорта](https://office.univer.ai/showcase/bases/custom-import-export), чтобы реализовать их с помощью собственного плагина. Полный исходный код примера доступен для просмотра онлайн и скачивания.