Интеграция обмена файлами

Чтобы открыть Excel в Univer, сначала преобразуйте файл в данные редактора. При экспорте преобразуйте изменённые данные обратно в Excel. Серверный @univerjs-pro/exchange-node выполняет преобразование, а браузер загружает файлы, открывает документы и скачивает результаты.

Без совместного редактирования

Например, пользователь загружает Excel, редактирует его на странице и скачивает результат в Excel.

1. Браузер загружает файл, сервер преобразует его в данные Univer и возвращает их.
2. Браузер открывает таблицу с этими данными для редактирования.
3. При экспорте браузер отправляет изменённые данные серверу, который создаёт файл Excel.

Сервис совместного редактирования здесь не нужен. «Снимок» в браузерных API — это используемые здесь данные документа. Импорт и экспорт снимков всё равно требуют серверного преобразования. Для сохранения и дальнейшего продолжения работы приложение должно хранить эти данные.

Установка и применение модуля описаны в Импорте и экспорте Office. Оттуда же начните, если нужна только обработка файлов в Node.js.

С совместным редактированием

Например, пользователь импортирует Excel, делится документом с коллегами, редактирует его вместе с ними и затем экспортирует.

1. Сервер преобразует загруженный файл и сохраняет совместный документ.
2. Возвращает ID, который открывает браузер; другие пользователи входят по тому же ID.
3. При экспорте сервер читает актуальное содержимое и создаёт Excel для скачивания.

unitId браузерных API — этот ID. Сначала завершите интеграцию совместного редактирования, затем запустите пример Exchange. Изучайте его браузерный, серверный и преобразующий код вместе.

Перед экспортом дождитесь синхронизации, иначе файл может не содержать последних изменений. Чтение и преобразование совместных документов описано в серверном Office Exchange раздела Модули расширений.

Подключение кнопок импорта и экспорта

Когда преобразование на сервере работает, подключите его к странице:

• Меню Univer или API Facade: зарегистрируйте File Endpoint и Exchange Endpoint по примеру Exchange, затем настройте браузерные плагины.
• Собственные кнопки: вызывайте API приложения. После импорта откройте полученные данные или ID, после экспорта скачайте результат.

Настройки браузера см. в Sheets, Docs, Slides, Boards, Bases и PDFs. Совместный пример использует Sheets. Для остальных проверьте Импорт и экспорт Office и форматы своего выпуска.

Проверка интеграции

Импортируйте реальный файл, отредактируйте и экспортируйте. Откройте его в Office и проверьте изменения, формулы, изображения и макет. Для совместной работы также проверьте доступ других пользователей и сохранность после перезапуска сервера.

До развёртывания ограничьте размеры загрузок и обработайте ошибки и тайм-ауты. Загрузка, опрос задач и скачивание требуют проверки доступа; см. Идентификация и авторизация.

Ошибки экспорта и ограничения лицензии

Экспорт может завершиться ошибкой при отправке запроса или опросе задачи. Успешный HTTP-ответ ещё не означает готовность файла: проверяйте error.code и состояние задачи. Клиент Exchange передаёт серверные ошибки экспорта через IExchangeService.requestState$; собственный интерфейс может подписаться до начала операции.

import { IExchangeService } from '@univerjs-pro/exchange-client'import { ErrorCode } from '@univerjs/protocol'const exchange = univer.__getInjector().get(IExchangeService)const subscription = exchange.requestState$.subscribe(({ error }) => {  if (!error || error.code === ErrorCode.OK) return  console.error(error.code, error.message)})

Сравнивайте именованные значения ErrorCode из @univerjs/protocol, а не переведённые сообщения. Сохраняйте сообщение сервера для диагностики. Сетевые сбои, неверные ответы и тайм-ауты могут дать общую ошибку и не доказывают отказ лицензии. При удалении редактора вызовите subscription.unsubscribe().

Собственный сервер или прокси должен сохранять структурированный ответ об ошибке и отмечать задачу как неудачную, а не оставлять pending. Увеличение maxTimeoutTime только продлевает опрос и не меняет квоту или разрешения лицензии.

Вложения OLE

Sheets, Docs и Slides хранят импортированные файлы OLE отдельно от изображений предпросмотра. Доступные оригиналы можно скачать, а при наличии прав — переименовать отдельное вхождение или удалить вложение. Для изображений и PDF есть предпросмотр. Office-просмотр использует JSON-конвертацию Exchange и временный редактор только для чтения, не создавая постоянный дочерний документ. Нативные приложения Office и макросы не выполняются.

Добавьте ole в существующую регистрацию UniverDrawingPlugin перед Exchange. Маршрут ниже должен открывать интерфейс документов вашего приложения; при необходимости учитывайте второй аргумент getLink — тип документа. Exchange предоставляет конвертацию Office и определение совместного режима. Вложения по UUID также требуют ole.attachmentIo с авторизованными callbacks upload(file, targetUnitId) и read(attachment, signal). Для Office-просмотра нужен соответствующий рендерер либо собственный previewOffice / createOfficePreview.

import { UniverDrawingPlugin } from '@univerjs/drawing'univer.registerPlugin(UniverDrawingPlugin, {  ole: {    getLink: (unitId) => `/documents/${encodeURIComponent(unitId)}`,  },})

Преобразование вложения Office в онлайн-документ требует совместного хоста, права редактирования, конвертации и getLink. Создаётся независимый документ, его идентификатор сохраняется во вложении для повторного открытия. Правки онлайн-документа не перезаписывают исходные байты. Отсутствующие, внешние и неподдерживаемые вложения сохраняют свой статус.

Экспорт по умолчанию использует oleAttachmentSource: 'original'. Значение 'online' включает текущие подтверждённые версии преобразованных документов только в этот экспорт, не меняя сохранённые оригиналы. Дождитесь синхронизации и проверяйте доступ к связанным документам на сервере. Передавайте опцию вторым аргументом API Docs/Slides или четвёртым аргументом Sheets; варианты snapshot используют ту же позицию. См. API экспорта.

Для сохранённых вложений Exchange передаёт fileID и содержащую их Unit — sourceUnitID. До преобразования по ссылке сервер должен проверить эту связь и права пользователя. Опрос задачи может возвращать progress.stage: reading, converting, creating или done. Для собственного интерфейса см. API импорта и хода выполнения.