Univer 2026: при импорте и экспорте выбрать unitId или Snapshot?

После импорта XLSX редактор показывает таблицу, но повторный экспорт не работает или документ не появляется у коллег.

Если документ должен храниться на сервере и участвовать в совместном редактировании, выбирайте путь с unitId; для автономной обработки и преобразования файла — Snapshot. В обоих случаях заранее проверьте настройку сервера конвертации и полный цикл экспорта.

Материал предназначен для разработчиков интерфейсов, backend-инженеров и продуктовых команд, которые встраивают Univer Sheets в SaaS. Особенно полезен он тем, кто строит автономную обработку файлов и хочет понять границы потока Snapshot.

Сначала определите, где и как будет жить документ

Выбор зависит не от того, какой способ импорта выглядит проще, а от жизненного цикла рабочей книги после загрузки. Нужно ответить на два вопроса: должна ли она сохраняться как серверный документ и должны ли несколько пользователей работать с ней в одном совместном пространстве?

Для документа, который после загрузки остаётся частью SaaS, предпочтителен путь с unitId. Идентификатор связывает загруженную книгу с дальнейшей работой в приложении: документ можно загрузить в редактор в соответствующем контексте и включить в поток совместной работы. Описание импорта и экспорта Univer разграничивает этот вариант и работу с данными Snapshot. Отдельно нужно реализовать хранение документа и проверить его доступность через серверную часть; само наличие unitId не означает, что эти задачи выполнены автоматически.

Если приложение получает файл, выполняет операцию, формирует результат и не должно создавать совместный документ, выбирайте Snapshot. В документации этот путь описан как импорт с получением данных рабочей книги и экспорт на их основе. Для него не требуется включать совместное редактирование, но зависимость от сервера преобразования файлов остаётся. Это различие важно: «без совместного редактора» не означает «без backend».

Нужно ли выбирать unitId для импорта XLSX? Выбирайте этот путь, если загруженная книга должна стать серверным документом, доступным в рабочем процессе SaaS, в том числе для совместного редактирования. Если XLSX только преобразуется в другой формат или обрабатывается локально без постоянного документа, Snapshot обычно соответствует задаче лучше. Перед реализацией сверьте поддерживаемый формат и интерфейс конкретной версии SDK с официальным описанием обмена файлами Univer.

Условие проекта	Рекомендуемый путь	Что проверить до запуска
Книгу нужно сохранять на сервере и повторно открывать как документ SaaS	unitId	Создание серверной записи, права доступа, повторная загрузка и экспорт
Несколько пользователей должны работать с одним документом	unitId вместе с настройкой сервера для совместной работы	Подключение модулей совместной работы, идентификация пользователей и восстановление документа
Нужно обработать файл без создания совместного документа	Snapshot	Состав данных Snapshot, сохранение результата и передача данных в экспорт
Требуется только преобразовать поддерживаемый файл	Snapshot, если приложению не нужен серверный документ	Наличие конвертера, поддержка формата и содержимое выходного файла
Нужен CSV-обмен	Выбор зависит от требуемых данных и поддерживаемого API	Потерю сведений о листах и форматировании; CSV не следует считать полной копией книги

Важно: unitId — часть потока работы с документом, а не готовая настройка постоянного хранения. Проверьте, где сохраняется содержимое, как авторизуется доступ и что произойдёт после перезапуска приложения.

Для совместного SaaS настройте поток с unitId

В этом сценарии импорт — только входная точка. Чтобы документ оказался в рабочем процессе, приложение должно связать результат загрузки с серверным хранением, а редактор — получить соответствующие данные при открытии. Официальные материалы по серверной архитектуре Univer и модулям совместной работы описывают серверные компоненты, которые следует учитывать при такой интеграции.

Проверяйте всю цепочку, а не только ответ API при импорте:

• исходный файл принят и преобразован;
• для созданного документа получен и сохранён идентификатор;
• пользователь с нужными правами может открыть документ;
• второй участник получает тот же документ, а не отдельную локальную копию;
• изменения сохраняются и доступны после повторного открытия;
• сервер может снова подготовить файл для экспорта.

Требуется ли совместное редактирование для импорта Snapshot? Нет, Snapshot используют и в автономных сценариях, когда совместный документ создавать не требуется. Однако приложению всё ещё нужно обработать полученные данные и корректно сохранить или передать их на экспорт. Если со временем автономный обработчик превращается в редактор с постоянными документами и пользователями, пересмотрите архитектуру: сохранение Snapshot в собственном хранилище не становится автоматически серверной моделью документов Univer.

Для unitId отдельно определите модель доступа: кто может создавать документ, кто вправе читать и менять его, а также как приложение связывает внутреннюю учётную запись с доступом к рабочей книге. Эти правила относятся к вашей SaaS-архитектуре, а не выводятся из идентификатора. Если через редактор проходят конфиденциальные клиентские документы, включите проверку хранения и доступа в политику обработки данных; для предварительного разбора пригодится страница о конфиденциальности nuvcloud.

Для автономной обработки используйте Snapshot и отдельно проверяйте конвертер

Путь Snapshot подходит для фоновой обработки, разовой подготовки книги и преобразования между форматами, когда приложению не нужно создавать общий серверный документ. Он даёт приложению рабочие данные, с которыми можно продолжить обработку, а не готовую гарантию идентичности исходного и экспортированного файла. Именно поэтому результат нужно оценивать после экспорта, открывая файл в целевом сценарии.

Почему для экспорта XLSX нужен сервер конвертации? Потому что операции импорта и экспорта файлов зависят от соответствующей серверной инфраструктуры, а не только от компонента редактора в браузере. Официальное описание серверного расширения импорта и экспорта показывает роль серверной части в этом потоке; до разработки проверьте, что она установлена и соответствует используемому SDK. Если браузер успешно показывает книгу, это само по себе не подтверждает, что backend способен сформировать выходной файл.

Также различайте преобразование и хранение. Snapshot можно обработать в приложении, но SaaS всё равно должен решить, куда сохранять результат, как ограничивать доступ и как связывать его с пользователем или задачей. Для повторяемого процесса полезно хранить исходный файл отдельно от экспортированного результата и записывать сведения о версии приложения, выбранном формате и исходной операции. Это помогает локализовать расхождение: оно возникло при импорте, изменении данных или формировании файла.

Официальное руководство по сохранению данных в быстром старте Univer полезно сверять с собственной моделью сохранения. Не предполагайте, что состояние интерфейса автоматически является долговременной записью в вашей базе: отдельно определите момент сохранения, обработку ошибок и порядок восстановления после прерывания операции.

Для CSV и TSV ограничьте ожидания форматом

CSV и TSV удобны, когда системе нужно обменяться табличными значениями, но их нельзя считать эквивалентом полной книги XLSX. В официальной документации Univer для CSV отдельно описаны ограничения формата; при таком обмене нельзя без проверки рассчитывать на сохранение всей структуры и оформления рабочей книги. Ориентируйтесь на список возможностей импорта и экспорта, а не на то, что файл с табличными данными открылся в интерфейсе.

Перед выбором API выясните, какие входные и выходные форматы поддерживает именно текущая версия проекта. Не переносите автоматически вывод о CSV на TSV: наличие похожего текстового представления не доказывает, что конкретный конвертер принимает оба варианта или обрабатывает их одинаково. Проверяйте выбранный формат на фактическом вызове импорта и на сформированном файле экспорта.

Если для продукта важны листы, формулы, изображения, объединённые ячейки или оформление, задайте критерии отдельно для каждого свойства. Документация по API рабочих книг и листов описывает модель книги и её листов, а раздел о формулах Univer — отдельную функциональность формул. Наличие свойства в модели не следует трактовать как гарантию, что оно без изменений пройдёт через любой импортно-экспортный формат.

Проведите проверку на файлах целевого SaaS

Для рабочего теста нужны не искусственно упрощённые таблицы, а типовые файлы пользователей. До проверки зафиксируйте ожидаемое поведение каждого свойства, затем выполните операции в той же конфигурации SDK и сервера, которая используется в проекте. Не смешивайте результаты: вычисление формул, сохранение оформления и совместимость файла — разные критерии.

Проверку удобно провести по такому порядку:

• [ ] Зафиксируйте версии SDK и серверных компонентов, включённые модули, выбранный путь — unitId или Snapshot — и исходный формат.
• [ ] Подготовьте целевые файлы: книгу с несколькими листами, примерами формул и изображениями, а также обычные файлы, которые действительно поступают от пользователей.
• [ ] Выполните импорт каждым предполагаемым способом и сохраните сведения о результате: создан ли серверный документ или получены данные Snapshot, какие ошибки вернул процесс.
• [ ] Проверьте структуру книги: названия и количество листов, расположение значений и ожидаемые формулы. Для формул отдельно запишите, сохранилось ли выражение и совпадает ли отображаемый результат.
• [ ] Если сценарий предполагает совместную работу, откройте документ под разными тестовыми учётными записями и проверьте, что они обращаются к одному серверному документу и получают сохранённые изменения.
• [ ] Выполните экспорт с помощью настроенного backend, затем откройте полученный файл в целевом программном окружении и сравните его с исходником по заданным критериям.
• [ ] Запишите расхождения раздельно: структура листов, формулы и вычисления, изображения, форматирование, доступ к документу и возможность повторного открытия.

Как проверить сохранность нескольких листов и формул? Сравните исходный файл и результат экспорта по заранее выбранным признакам, а не по впечатлению от отображения в редакторе. Зафиксируйте, какие листы доступны, какие формулы остались выражениями и какие результаты расчёта ожидаются в вашем сценарии. Расчёт формулы может зависеть от поддерживаемой функциональности и состояния книги; поэтому его нельзя объявлять корректным только потому, что формула видна после импорта. Модель данных листов и документа сверяйте с описанием Sheets API, а формульные сценарии — с документацией о формулах.

Для работы с изображениями и сложным оформлением добавьте в тест комплект репрезентативных файлов, но не превращайте единичное успешное открытие в универсальное обещание совместимости. Запишите версию SDK, конфигурацию backend и конкретный входной файл: без этих сведений результат сложно повторить после обновления. Если после экспорта изменилось оформление, сначала выясните, относится ли эффект к ограничениям формата, неподдерживаемому элементу или ошибке сервера преобразования.

Сверьте выбор с потоком данных перед реализацией

Проверка перед разработкой	Поток unitId	Поток Snapshot
Нужен постоянный документ в SaaS	Да, предусмотрите серверное хранение и повторную загрузку	Не следует считать его серверной моделью документа без отдельной реализации
Нужна совместная работа	Подходит при настройке соответствующих серверных компонентов и доступа	Не требуется для самого автономного сценария
Нужно обработать книгу и получить файл	Требуется настроить и проверить backend конвертации	Также требуется проверить backend конвертации
Что является результатом импорта	Идентификатор для дальнейшей работы с документом в выбранной архитектуре	Данные рабочей книги для последующей обработки
Что нельзя считать подтверждённым без теста	Доступность, сохранность изменений и успешный экспорт	Полноту преобразования, совместимость формата и сохранение свойств книги

Финальный выбор закрепите в техническом задании вместе с поддерживаемыми входными форматами, моделью хранения и критериями приёмки. Так команда не перепутает «редактор открыл файл» с «SaaS сохраняет документ и выдаёт проверенный результат». После обновления SDK или сервера повторяйте тот же набор тестов: форматы и поведение следует сверять с актуальной документацией и фактической сборкой проекта.

Если разработка сейчас идёт только в Linux-контейнере или удалённой среде без macOS, у такого варианта есть практические ограничения: он не позволяет проверить браузерные сценарии именно на macOS, не выявляет зависимости от системного окружения и может потребовать отдельной настройки для тестирования клиентского поведения. При этом Mac не заменяет сервер Univer и не нужен команде, которая не тестирует платформенные различия. Если такая проверка требуется временно, аренда Mac у nuvcloud может дать отдельную тестовую среду без покупки постоянного устройства; перед выбором сверьте доступность и условия на странице тарифов nuvcloud. Для сверки самого потока интеграции также можно обратиться к справочным материалам nuvcloud.

Дополнительное чтение

• Приёмка интеграции Univer: проверка действий, сохранения и восстановления
• Как диагностировать ошибки JSON и сбои при передаче данных AI Agent
• Безопасная обработка файлов AI-агентами: изоляция, проверка изменений и откат