Univer 2026: Import und Export – unitId oder Snapshot?

September 29, 2026 · KI-Entwicklung · ca. 10 Min. Lesezeit

Dieser Leitfaden hilft Frontend- und Backend-Teams, für Univer zwischen einer serverseitig gespeicherten Zusammenarbeit über unitId und einer Snapshot-basierten Offline-Verarbeitung zu entscheiden. Sie erhalten eine Szenarioübersicht, einen umsetzbaren Prüfablauf und Testkriterien für Arbeitsblätter, Formeln, Bilder und Dateiformate.

Für Univer-Import und -Export gilt: Verwenden Sie unitId, wenn ein Dokument serverseitig gespeichert und gemeinsam bearbeitet werden soll; wählen Sie Snapshot für lokale oder Offline-Verarbeitung ohne kollaboratives Dokument. In beiden Fällen ist zuerst zu klären, ob das passende Server-Backend die Datei tatsächlich importieren und exportieren kann.

Dieser Beitrag richtet sich an Entwicklerinnen und Entwickler, die Univer Sheets in eine SaaS-Anwendung integrieren, sowie an technische Produktteams mit Dokumenten- und Dateiflows. Besonders relevant ist er für Teams, die eine Offline-Verarbeitung oder eine reine Formatkonvertierung planen und dabei den Snapshot-Weg prüfen.

Die Entscheidung am Dokumentfluss ausrichten

Die Wahl zwischen unitId und Snapshot ist keine allgemeine Rangliste, sondern hängt davon ab, was nach dem Import mit der Arbeitsmappe geschehen soll. Bei einer Zusammenarbeit wird ein Dokument serverseitig geführt und in einer kollaborativen Umgebung geladen. Beim Snapshot-Weg stehen dagegen Arbeitsmappendaten im Vordergrund, die lokal oder in einem Offline-Prozess verarbeitet werden können.

Die Univer-Dokumentation zu Import und Export beschreibt beide Wege und weist darauf hin, dass Dateioperationen ein Konvertierungs-Backend benötigen. Daraus folgt eine wichtige Umsetzungsregel: Eine funktionierende Tabellenoberfläche im Browser ist noch kein Nachweis für einen vollständigen Dateiimport oder -export. Backend, Datenmodell und Exportweg müssen als zusammenhängender Ablauf geprüft werden.

Einsatzszenario	Geeigneter Weg	Was dadurch organisiert wird	Vor dem Produktivbetrieb prüfen
SaaS-Dokument, das gespeichert und gemeinsam bearbeitet wird	unitId	Das Dokument wird im serverseitigen beziehungsweise kollaborativen Ablauf über seine Kennung geladen und verwaltet.	Speicherung, Zugriffsrechte, Abruf und erneuter Export
Lokaler oder Offline-Prozess ohne gemeinsame Dokumentbearbeitung	Snapshot	Die Arbeitsmappendaten können im Verarbeitungsfluss weitergegeben und zur Dateierzeugung verwendet werden.	Snapshot-Struktur, Konvertierungs-Backend und Dateiausgabe
Einfache Übernahme von CSV- oder TSV-Daten	Nach gewünschtem Zielablauf auswählen	Der Import dient der Datenübernahme, nicht automatisch einer vollständigen Arbeitsmappenmigration.	Arbeitsblattanzahl, Formatverlust und unterstützte API-Richtung

Behandeln Sie die Tabelle als Architekturentscheidung, nicht als Kompatibilitätsgarantie. Das konkrete Dateiverhalten hängt von der eingesetzten Univer-Version, der Serverkonfiguration und den Eigenschaften der Testdateien ab.

Den unitId-Weg für ein kollaboratives SaaS-Dokument aufbauen

Eine unitId ist für einen Dokumentfluss sinnvoll, in dem eine importierte Datei nicht nur kurzfristig im Browser geöffnet, sondern als serverseitig verwaltetes Dokument wiedergefunden werden soll. Nach dem Import muss die Anwendung die Kennung in ihrem eigenen Ablauf übernehmen und den passenden kollaborativen Ladevorgang starten. Die Schnellstart-Dokumentation zur Datenspeicherung und die Dokumentation der kollaborativen Module helfen dabei, Speichern und Zusammenarbeit als eigene Teile der Integration einzuordnen.

Das ist keine automatische Komplettlösung. Die Kennung ersetzt weder die serverseitige Persistenz noch die Rechteprüfung. Eine Anwendung muss bestimmen, welcher Nutzer oder welches Team das Dokument abrufen darf, wie die Zuordnung zwischen Anwendungsdatensatz und Dokumentkennung gespeichert wird und was nach einem erneuten Import geschieht. Wird die Zuordnung nicht zuverlässig gepflegt, können Dateien zwar erfolgreich importiert erscheinen, aber im späteren Ablauf nicht mehr dem richtigen Anwendungsobjekt zugeordnet werden.

Planen Sie den unitId-Weg deshalb als Prozesskette:

Eingabedatei annehmen. Legen Sie fest, welche Dateitypen Ihre Anwendung entgegennimmt, wie ungültige Dateien behandelt werden und ob vor dem Import eine Validierung stattfinden muss.
Import über das vorgesehene Backend ausführen. Kontrollieren Sie, dass die Serverkomponente für die Konvertierung erreichbar ist und die verwendete API die gewünschte Eingabe unterstützt.
Dokumentkennung übernehmen. Speichern Sie die zurückgegebene unitId mit der Anwendungsreferenz, statt sie nur im Zustand einer einzelnen Browseransicht zu halten.
Kollaborativ laden und Berechtigungen prüfen. Verifizieren Sie, dass berechtigte Nutzer das richtige Dokument öffnen und unberechtigte Konten keinen Zugriff erhalten.
Änderungen speichern und erneut exportieren. Prüfen Sie, ob Änderungen erhalten bleiben und ob die Exportfunktion eine Datei mit dem vorgesehenen Inhalt erzeugt.

Die Univer Sheets API für Arbeitsmappen und Arbeitsblätter ist hilfreich, wenn der Übergang zwischen Dokumentmodell und Anwendungslogik konkretisiert werden muss. Für die Serverseite sollte zusätzlich die offizielle Univer-Serverdokumentation herangezogen werden. Halten Sie die API- und Serverversionen in der Projektkonfiguration fest: Bei einer Aktualisierung muss der Datei- und Kollaborationsfluss erneut geprüft werden, statt nur den erfolgreichen Start der Oberfläche als Abnahme zu werten.

Snapshot für lokale und Offline-Verarbeitung einsetzen

Snapshot passt, wenn der Prozess eine Arbeitsmappe als Datenstruktur verarbeitet, ohne sie als gemeinsames serverseitiges Dokument mit unitId zu betreiben. Der Import liefert dabei Arbeitsmappendaten, mit denen die Anwendung weiterarbeiten kann. Beim Export wird auf Grundlage eines Snapshots eine Datei erzeugt. Damit lässt sich ein Ablauf umsetzen, der Dateien annimmt, Inhalte lokal oder in einem getrennten Verarbeitungsschritt bearbeitet und anschließend wieder ausgibt.

Für die Entscheidung ist wichtig, zwei Aussagen nicht gleichzusetzen: Snapshot braucht nicht zwingend einen kollaborativen Dokumentfluss; Dateiimport und Dateiexport benötigen aber weiterhin die vorgesehene Konvertierungsinfrastruktur. Die Import- und Exportanleitung beschreibt diese Trennung. Die Dokumentation der serverseitigen Import- und Exportarchitektur ist relevant, wenn die Verarbeitung im Serverbetrieb eingerichtet wird.

Ein typischer Fehler besteht darin, den Snapshot als vollständigen Ersatz für Backend-Konfiguration zu behandeln. Das führt oft zu einer falschen Fehlersuche: Das Snapshot-Objekt kann in der Anwendung verfügbar sein, während die Konvertierung oder die Dateiausgabe dennoch scheitert. Trennen Sie daher in Protokollen und Tests mindestens diese Ergebnisse: Wurde die Eingabedatei angenommen? Wurden Arbeitsmappendaten erzeugt? Wurde die gewünschte Ausgabedatei erstellt und anschließend wieder geöffnet?

Snapshot ist außerdem nicht automatisch die bessere Wahl für jede Anwendung ohne Echtzeit-Zusammenarbeit. Wird das Dokument später dauerhaft gespeichert, über mehrere Sitzungen weiterbearbeitet oder mit Nutzerrechten versehen, muss geklärt werden, ob der übrige Datenfluss diese Anforderungen tatsächlich abdeckt. Ein kurzfristiger Verarbeitungsweg und ein dauerhaft verwaltetes SaaS-Dokument sind unterschiedliche Produktanforderungen.

CSV und TSV als begrenzte Datenwege behandeln

CSV und TSV sind sinnvoll, wenn strukturierte Zellinhalte übernommen oder ausgegeben werden sollen. Sie sind jedoch nicht mit einem vollständigen Arbeitsmappenformat gleichzusetzen. Eine Textdatei bildet nicht automatisch mehrere Arbeitsblätter, Zellformatierungen, eingebettete Bilder und Formeln mit denselben Eigenschaften wie eine komplexe Arbeitsmappendatei ab. Die Formatbeschreibung in der offiziellen Import- und Exportdokumentation sollte für die tatsächlich eingesetzte Version maßgeblich sein.

Vor der Umsetzung ist außerdem zwischen API-Richtung und Formatnamen zu unterscheiden. Dass ein Format in einem Importweg auftaucht, belegt nicht ohne Prüfung, dass es auch für den Exportweg verfügbar ist. Dokumentieren Sie deshalb getrennt, welche Formate die Anwendung annimmt und welche sie ausgibt. Falls die Anwendung nur CSV oder TSV benötigt, testen Sie außerdem, wie Trennzeichen, leere Zellen, Textkodierung und mehrzeilige Inhalte in den konkreten Dateien behandelt werden.

Wichtig: Eine erfolgreiche CSV- oder TSV-Konvertierung ist kein Beleg für einen verlustfreien Rundlauf einer vollständigen Arbeitsmappe. Wenn Nutzer mehrere Arbeitsblätter, Formeln oder Bilder erwarten, muss genau diese Dateiart separat getestet werden.

Das ist auch eine Produktentscheidung: Eine schmale Datenübernahme kann als CSV-/TSV-Funktion sauber beschrieben werden. Wird sie dagegen als allgemeiner Tabellenimport vermarktet, erwarten Nutzer möglicherweise Eigenschaften, die in einem einfachen Textformat nicht enthalten sind. Benennen Sie die unterstützten Eingaben und die erwarteten Verluste in der Oberfläche und in der technischen Dokumentation präzise.

Den Dateirundlauf mit echten Arbeitsmappen abnehmen

Für die Abnahme sollte ein Test nicht bei „Datei lässt sich öffnen“ enden. Import, Bearbeitung, Speichern und erneuter Export können jeweils unterschiedliche Fehler verursachen. Verwenden Sie repräsentative Dateien aus dem späteren Nutzerkreis und halten Sie fest, mit welcher Univer-Version, welcher Serverkonfiguration und welchem API-Weg der Test durchgeführt wurde. Aussagen über Formeln oder Bildkompatibilität sind erst belastbar, wenn sie in dieser Zielumgebung geprüft wurden.

Prüfen Sie die Ergebnisse in getrennten Kategorien:

Arbeitsblätter: Stimmen Anzahl, Namen und Reihenfolge vor und nach dem Rundlauf überein?
Formeln: Bleibt der gespeicherte Ausdruck erhalten, und entspricht das angezeigte Ergebnis der Erwartung? Die Univer-Dokumentation zu Formeln beschreibt die Produktfunktion, ersetzt aber keine Prüfung der konkreten Dateibeispiele.
Bilder: Werden eingebettete Bilder an der erwarteten Stelle dargestellt, und sind sie nach dem erneuten Export noch vorhanden?
Formatierungen: Halten Sie Abweichungen bei Zahlenformaten, Farben, Rahmen, Zeilenhöhen und Spaltenbreiten einzeln fest.
Dateiöffnung: Öffnen Sie die exportierte Datei erneut in dem Werkzeug oder Zielprozess, den Ihre Nutzer tatsächlich verwenden sollen.

Prüfliste vor der Freigabe

[ ] Ist festgelegt, ob das Dokument dauerhaft gespeichert und gemeinsam bearbeitet wird oder nur lokal beziehungsweise offline verarbeitet wird?
[ ] Ist für jeden Dateityp dokumentiert, ob er importiert, exportiert oder in beiden Richtungen verwendet werden soll?
[ ] Ist das Konvertierungs-Backend für den gewählten Weg eingerichtet und aus der Anwendung erreichbar?
[ ] Wird die unitId zusammen mit dem richtigen Anwendungsdatensatz gespeichert, falls der kollaborative Weg verwendet wird?
[ ] Sind Dokumentzugriff und Berechtigungen im späteren Nutzerablauf geprüft?
[ ] Enthält der Test mindestens eine repräsentative Datei mit mehreren Arbeitsblättern, Formeln und Bildern, sofern diese Funktionen erwartet werden?
[ ] Werden Formelverhalten, Formatänderungen und Dateikompatibilität getrennt protokolliert?
[ ] Wurde die exportierte Datei erneut geöffnet, statt nur der Erfolg der Exportanforderung kontrolliert?
[ ] Sind Server- und SDK-Versionen sowie die Testergebnisse für spätere Aktualisierungen nachvollziehbar festgehalten?

Ändert sich eine Datei beim Rundlauf, sollte das Team zuerst den betroffenen Bereich isolieren, statt pauschal von „unterstützt“ oder „nicht unterstützt“ auszugehen. Eine Formelabweichung, ein verlorenes Bild und ein verändertes Zahlenformat sind unterschiedliche Befunde und können andere Produktentscheidungen erfordern. So entsteht eine belastbare Kompatibilitätsmatrix für die eigenen Eingabedateien, ohne nicht geprüfte Eigenschaften zu verallgemeinern.

Häufige Fragen zum Import- und Exportweg

Welche Methode eignet sich für XLSX-Dateien?

Das Zielformat allein entscheidet nicht zwischen unitId und Snapshot. Für eine Datei, die als dauerhaftes, gemeinsam bearbeitetes SaaS-Dokument gespeichert werden soll, prüfen Sie den unitId-Ablauf. Für das Einlesen und Weiterverarbeiten ohne kollaboratives Dokument ist Snapshot oft der passendere Pfad. In beiden Fällen muss das Server-Backend für die konkrete Konvertierung eingerichtet und der Export mit repräsentativen Dateien getestet sein.

Muss für Snapshot eine Zusammenarbeit aktiviert sein?

Nein. Snapshot ist für Arbeitsmappendaten in einem lokalen oder Offline-Ablauf geeignet und erfordert nicht allein deshalb ein kollaboratives Dokument mit unitId. Der Verzicht auf Zusammenarbeit hebt jedoch die Anforderungen an Dateiimport und Dateiexport nicht auf. Prüfen Sie daher, welche Serverkomponenten Ihre eingesetzte Univer-Version für die Konvertierung benötigt und ob der gewünschte Ablauf mit den vorhandenen APIs abgedeckt ist.

Weshalb reicht eine geladene Arbeitsmappe für den XLSX-Export nicht aus?

Das Laden einer Arbeitsmappe und das Erzeugen einer Datei sind getrennte Vorgänge. Die Dateikonvertierung wird über das dafür vorgesehene Backend organisiert; deshalb müssen Erreichbarkeit, Konfiguration und Berechtigungen stimmen. Wenn der Export scheitert, prüfen Sie zuerst den Serverweg und die Protokolle. Erst danach lässt sich sinnvoll eingrenzen, ob der Fehler in der Oberfläche, im Dokumentzustand oder in der Konvertierung liegt.

Wie werden mehrere Arbeitsblätter und Formeln zuverlässig geprüft?

Nutzen Sie reale oder repräsentative Dateien aus dem Zielbetrieb und vergleichen Sie vor dem Import und nach dem erneuten Export dieselben Merkmale. Erfassen Sie Arbeitsblätter, Formeltext, angezeigte Ergebnisse, Bilder und Formatierungen getrennt. Öffnen Sie die exportierte Datei zusätzlich im vorgesehenen Zielprozess. So wird sichtbar, ob eine Abweichung beim Import, während der Bearbeitung oder erst beim Export entsteht.

Wenn nach diesen Prüfungen klar ist, ob der SaaS-Ablauf dauerhaft kollaborativ oder nur für eine begrenzte Verarbeitung gedacht ist, kann das Team die Hosting- und Entwicklungsumgebung passend dazu wählen. Eine lokale Entwicklungsmaschine ist für reproduzierbare Tests und die Kontrolle physischer Schnittstellen sinnvoll; sie bindet bei gemeinsamem Zugriff jedoch an lokale Verfügbarkeit und Wartung. Eine beliebige allgemeine Serverumgebung kann wiederum zusätzliche Einrichtungs- und Zugriffsarbeit für Frontend-Tests verursachen. Für zeitlich begrenzte Entwicklungs- oder Abnahmephasen kann ein gemieteter Mac von nuvcloud eine Alternative sein, wenn ein macOS-Testsystem gebraucht wird; für dauerhaft intensive Last oder zwingend benötigte lokale Hardware ist Miete nicht automatisch die wirtschaftlichste Wahl. Den Bestellablauf für eine Mac-Miete bei nuvcloud können Sie prüfen, bevor Sie dafür einen befristeten Testaufbau planen.

Arbeitet ein verteiltes Team von einem bestimmten Standort aus, sollte die Verbindungs- und Zugriffssituation vor dem Einsatz separat bewertet werden. Die Informationen zur Bestellung eines nuvcloud-Mac in Japan können bei einer solchen Standortplanung helfen; sie ersetzen jedoch weder die Prüfung des Datenstandorts noch die Architekturentscheidung für Univer. Für den Dokumentfluss bleibt die zentrale Wahl unverändert: unitId für serverseitig verwaltete Zusammenarbeit, Snapshot für lokale oder Offline-Verarbeitung und in beiden Fällen ein verifizierter Konvertierungs- und Exportweg.

Weiterlesen

Univer-AI-Agent-Integrationen vor dem Go-live: Zustände, Änderungen und Wiederherstellung systematisch prüfen