Univer 2026 : pour l’import-export, choisir unitId ou Snapshot ?

Pour l’import-export avec Univer, choisissez unitId si le document doit être conservé côté serveur et ouvert en collaboration ; choisissez Snapshot pour un traitement local ou hors ligne qui ne nécessite pas de document collaboratif. Dans les deux cas, vérifiez d’abord le serveur de conversion et validez l’export dans l’environnement de votre application.

Cet article s’adresse aux équipes qui construisent une application SaaS avec des classeurs, mais aussi aux personnes qui développent un outil de traitement hors ligne ou de conversion de fichiers.
Si le besoin porte uniquement sur l’édition collaborative en ligne, la décision centrale est de savoir où le document sera conservé et comment il sera chargé, pas de choisir un format de données par habitude.

Repérer le parcours qui correspond au document

Le choix n’oppose pas une méthode universellement supérieure à une méthode dépassée. Il oppose deux façons de faire circuler les données : un document identifié et conservé dans un environnement serveur, ou les données d’un classeur manipulées dans un flux qui n’a pas besoin de collaboration. La documentation officielle d’import et d’export d’Univer présente ces parcours et leur relation avec la conversion des fichiers.

Besoin principal	Parcours à examiner	Ce que cela implique	Vérification à prévoir
Conserver un document et le charger dans une expérience collaborative	unitId	Le document doit être accessible et persistant dans l’environnement serveur concerné.	Confirmer l’enregistrement, les droits d’accès et la réouverture du document.
Lire ou transformer les données d’un classeur sans collaboration	Snapshot	L’application travaille avec les données du classeur plutôt qu’avec un document collaboratif identifié.	Contrôler la conversion d’entrée et la génération du fichier de sortie.
Traiter des données tabulaires simples	API et format effectivement pris en charge	Un fichier tabulaire ne transporte pas nécessairement la structure d’un classeur complet.	Vérifier le nombre de feuilles, les formules et les éléments de présentation attendus.

Ce tableau sert à sélectionner une architecture à tester, pas à certifier la compatibilité de chaque fichier. Les formats annoncés et les comportements précis dépendent de la version d’Univer, des API utilisées et du serveur installé. La documentation de l’architecture serveur et celle des extensions serveur pour la collaboration et l’import-export sont donc à confronter au déploiement réel du projet.

Parcours unitId : conserver le document pour le retrouver

Le parcours unitId convient lorsque l’application doit importer un fichier, obtenir une référence de document, puis charger celui-ci dans un contexte où les utilisateurs peuvent le consulter ou le modifier. La référence ne constitue pas, à elle seule, une preuve que le document est durablement conservé ou accessible à tous les utilisateurs autorisés. Le service doit assurer le stockage et l’accès selon l’architecture retenue.

Après l’import, l’application doit transmettre ou utiliser le unitId selon le mécanisme de chargement prévu par l’intégration. L’équipe doit ensuite vérifier que le document est retrouvé après une nouvelle session, que les règles d’accès sont cohérentes et que les modifications attendues se retrouvent dans la version exportée. La documentation de démarrage rapide, qui décrit la sauvegarde des données, aide à distinguer l’état en mémoire de la sauvegarde réellement mise en place par le projet.

Ne traitez donc pas unitId comme un mode « sans configuration ». Il faut déterminer qui crée la référence, quel service conserve le document, comment les accès sont contrôlés et quel mécanisme est utilisé pour le réexporter. Pour une application SaaS, une rupture entre ces étapes peut produire un classeur qui s’affiche correctement dans une session, mais qui ne peut pas être repris par un autre utilisateur ou récupéré comme fichier.

Les questions de permissions doivent être testées dans le contexte de l’application : un document peut être persistant sans être accessible à un utilisateur donné, ou accessible dans l’éditeur sans que le processus d’export dispose des autorisations nécessaires. Ce sont des propriétés du déploiement et du flux applicatif à confirmer, et non des garanties à déduire du seul identifiant.

Parcours Snapshot : traiter les données hors ligne

Un Snapshot est à examiner lorsque le besoin consiste à charger les données du classeur, à les manipuler sans entrer dans un parcours de collaboration, puis à produire un fichier si l’application et le serveur de conversion le permettent. Cette approche est souvent plus directe pour un utilitaire de transformation ou un traitement ponctuel : le projet n’a pas à concevoir une expérience de document partagé s’il n’en a pas besoin.

La différence est importante pour la persistance. Les données présentes dans un Snapshot ne doivent pas être confondues avec un document automatiquement enregistré côté serveur. Le projet doit définir où ces données vivent pendant le traitement, quand elles sont modifiées et comment elles sont remises au composant chargé de générer le fichier. La documentation officielle distingue le chargement des données de classeur et la conversion des fichiers ; il faut donc tester ces deux opérations dans la version effectivement déployée.

Le parcours Snapshot ne signifie pas non plus « conversion sans serveur ». Si l’entrée est un fichier bureautique et que la sortie doit redevenir un fichier bureautique, l’application doit disposer du mécanisme de conversion correspondant. Avant de retenir ce parcours, confirmez que les API disponibles acceptent le format source visé et produisent le format de destination requis. En l’absence de collaboration, les besoins de stockage et de droits peuvent être plus simples, mais ils ne disparaissent pas : le traitement doit toujours protéger les fichiers et éviter de perdre les modifications avant l’export.

La documentation des API de feuilles, qui définit les notions de classeur et de feuille, permet aussi de préparer une vérification adaptée à la structure réellement manipulée. Elle ne remplace pas un essai avec les documents de l’application, en particulier lorsque ceux-ci contiennent des feuilles multiples ou des éléments de présentation spécifiques.

À retenir : si l’application ne nécessite pas de collaboration, ne créez pas un parcours unitId uniquement parce qu’un fichier doit être importé. Mais ne supposez pas non plus que Snapshot transforme à lui seul un fichier en classeur exportable : la conversion doit être disponible et testée.

Séparer le cas des fichiers CSV et TSV

Les formats tabulaires demandent une décision distincte. Un fichier CSV représente des valeurs organisées en lignes et en colonnes ; il ne constitue pas, à lui seul, une description complète d’un classeur avec plusieurs feuilles, formules, images et règles de présentation. Un TSV suit également une organisation tabulaire, mais il faut vérifier séparément qu’il est accepté par l’API et le processus de conversion employés. La documentation officielle d’import-export doit être consultée pour les formats réellement pris en charge par la version concernée.

Type de fichier	Ce qu’il faut vérifier avant de le retenir	Ce qu’il ne faut pas présumer
CSV	Délimiteur, encodage, feuille produite et traitement des valeurs.	La restitution d’un classeur complet avec plusieurs feuilles et mise en forme.
TSV	Acceptation explicite par l’API, séparateur et règles d’interprétation.	Une prise en charge identique à celle du CSV simplement parce que les deux formats sont tabulaires.
XLSX	Import, export, feuilles, formules et éléments visuels dans l’environnement cible.	Une restitution parfaite de tous les fichiers et de toutes leurs fonctionnalités.

Si le produit ne traite que des données tabulaires, il peut être pertinent de limiter explicitement le périmètre : quelles colonnes sont attendues, quelle feuille est produite, et quelles transformations sont admises. Si l’utilisateur attend un classeur complet, n’annoncez pas une conversion CSV comme un aller-retour équivalent. Pour le TSV, consignez le résultat observé sur la version déployée au lieu de déduire sa prise en charge de celle du CSV.

Vérifier les formules, les feuilles et les éléments visuels

Un fichier qui s’ouvre n’est pas nécessairement un fichier qui a été restitué conformément aux attentes. Les feuilles peuvent être présentes tandis que certains styles changent ; des formules peuvent subsister sans fournir le résultat attendu dans le contexte de calcul utilisé ; des images ou objets visuels peuvent nécessiter une validation distincte. La documentation officielle décrit des fonctionnalités de formule, mais l’équipe doit vérifier les fonctions pertinentes pour ses propres documents et son environnement, à partir de la documentation Univer sur les formules.

Il est préférable de séparer les constats plutôt que de noter le résultat global comme « compatible » ou « incompatible ». Pour chaque fichier représentatif, relevez les feuilles retrouvées, les formules présentes, les résultats affichés, les formats modifiés et les images correctement restituées. Si le résultat d’une formule change, vérifiez si la cause vient de la conversion, de la prise en charge de la formule ou du moment où le calcul est déclenché. Sans cette distinction, une anomalie de calcul peut être attribuée à tort à l’import, ou une différence de mise en forme peut passer inaperçue parce que les valeurs semblent correctes.

La structure du classeur mérite aussi une inspection après réexport. Les API de feuilles d’Univer distinguent le classeur et ses feuilles ; cette distinction offre une base pour comparer l’organisation avant et après le passage dans l’application. Pour les équipes qui souhaitent formaliser cette revue avant mise en service, le centre d’aide de nuvcloud est un point d’entrée pour les questions relatives à l’environnement de travail, sans remplacer les tests de compatibilité du projet.

Préparer un essai de bout en bout dans l’application

Un test utile reproduit le chemin réellement suivi par le fichier, pas seulement l’appel isolé à une fonction. Il faut partir d’un échantillon provenant des utilisateurs visés, l’importer avec le parcours envisagé, enregistrer ou modifier les données selon le fonctionnement du produit, puis exporter et comparer le résultat. Les étapes suivantes peuvent être cochées pendant la recette :

• [ ] Identifier le format d’entrée et le format de sortie requis, puis confirmer leur prise en charge dans la documentation de la version d’Univer et du serveur installés.
• [ ] Choisir des fichiers représentatifs de l’usage réel, comprenant plusieurs feuilles si le produit doit gérer des classeurs structurés, ainsi que des formules et des images lorsque ces éléments sont présents dans les documents utilisateurs.
• [ ] Pour le parcours unitId, importer le fichier, relever la référence produite et vérifier que le document peut être retrouvé après fermeture puis réouverture du contexte de travail.
• [ ] Pour le parcours Snapshot, confirmer que les données importées sont accessibles à l’application sans activer la collaboration, puis vérifier comment les modifications sont transmises au processus d’export.
• [ ] Contrôler les droits d’accès, les sauvegardes et la reprise du traitement lorsqu’un utilisateur n’a pas les permissions attendues ou que l’opération d’export échoue.
• [ ] Comparer le fichier exporté à l’original en consignant séparément les feuilles, les formules et leurs résultats, les formats, les images et la compatibilité avec les outils utilisés par les destinataires.
• [ ] Refaire l’essai avec les fichiers prioritaires du produit après une modification de configuration ou une mise à jour du SDK ou du serveur.

Cette recette doit distinguer les défauts bloquants des différences acceptables. Par exemple, l’absence d’une feuille nécessaire au métier ne peut pas être compensée par une présentation correcte des autres feuilles ; une différence de format peut en revanche être acceptable si le produit garantit uniquement les valeurs et la structure tabulaire. Les critères d’acceptation doivent donc être formulés avant le test, avec un résultat attendu pour chaque type de fichier.

Le contrôle doit aussi couvrir le cycle complet, y compris la remise du fichier à l’utilisateur. Une API peut produire un résultat dans le service tandis que l’application échoue ensuite à le rendre disponible ou à l’associer au bon document. Vérifiez le nom, le contenu et le destinataire du fichier dans le parcours réel, ainsi que le comportement de l’application lorsque la conversion ne peut pas aboutir. Ce sont des points de fiabilité du produit, pas des indicateurs de performance à extrapoler à partir d’un essai isolé.

Point de recette	Observation à consigner	Décision après l’essai
Persistance	Le document est-il retrouvé après une nouvelle ouverture dans le parcours unitId ?	Confirmer l’architecture de stockage et d’accès, ou revoir le parcours.
Structure	Les feuilles attendues sont-elles présentes et organisées comme prévu ?	Accepter, corriger ou limiter le périmètre annoncé.
Calcul	Les formules et leurs résultats répondent-ils aux besoins du document ?	Identifier si le problème concerne la formule, le calcul ou la conversion.
Présentation	Les formats et les images utiles sont-ils restitués ?	Définir les différences tolérées ou bloquantes.
Export	Le fichier produit est-il exploitable par les destinataires visés ?	Valider le format de sortie et le parcours de livraison.

Ne transformez pas les résultats d’un échantillon en garantie universelle de compatibilité. La conclusion de la recette doit préciser les types de fichiers effectivement testés, les versions utilisées et les limites acceptées. Après une mise à jour du SDK, du serveur ou des règles de conversion, refaites les contrôles correspondant aux documents les plus importants pour le produit.

FAQ sur l’import-export avec Univer

Quel parcours choisir pour importer un fichier XLSX ?
Utilisez unitId si le fichier devient un document conservé côté serveur et chargé dans un contexte collaboratif. Préférez Snapshot pour traiter les données du classeur sans créer ce document collaboratif. Dans les deux cas, vérifiez que les services de conversion disponibles acceptent le format requis et testez le fichier produit.

L’import d’un Snapshot impose-t-il la collaboration ?
Non. Snapshot convient à une manipulation des données du classeur qui ne passe pas par un document collaboratif identifié par unitId. Cela ne supprime toutefois pas la dépendance à la conversion pour lire ou générer certains fichiers. Le projet doit également définir où les données sont conservées pendant le traitement et comment elles sont transmises à l’export.

Pourquoi l’export XLSX dépend-il d’un serveur de conversion ?
Un classeur manipulé par l’application et un fichier XLSX sont deux représentations distinctes. Le parcours d’import-export documenté par Univer s’appuie sur les composants serveur prévus pour convertir les fichiers. Ni une référence unitId ni un Snapshot ne prouvent à eux seuls que la conversion est configurée : vérifiez les services actifs et testez l’export dans le déploiement réel.

Comment valider la conservation des feuilles et des formules ?
Effectuez un aller-retour avec des fichiers représentatifs des usages du produit, puis comparez séparément la structure des feuilles, les formules et leurs résultats, les formats et les images. Définissez les écarts acceptables avant la recette. Un fichier qui s’ouvre ne suffit pas à démontrer que toutes les fonctions attendues ont été conservées.

Choisir un environnement de test adapté

Le choix entre unitId et Snapshot règle le parcours du document, mais ne détermine pas à lui seul l’environnement où l’équipe développe et valide l’intégration. Une machine locale existante peut convenir si elle permet de reproduire l’application et de joindre les composants serveur nécessaires. Elle devient moins pratique lorsque plusieurs personnes doivent partager un environnement de test identique, lorsqu’il faut isoler des essais ou lorsque la capacité disponible varie avec les autres usages de la machine.

La location d’un Mac auprès de nuvcloud peut alors servir à disposer d’un environnement temporaire pour développer l’interface, reproduire un parcours utilisateur ou tester une configuration de travail. Elle ne remplace pas le serveur de conversion requis pour l’import-export, et elle n’est pas le bon choix si le besoin exige une charge durablement élevée ou des interfaces physiques particulières. Le bon arbitrage consiste à conserver le traitement serveur dans l’architecture prévue, tout en utilisant un Mac loué uniquement si cela simplifie les essais ou l’accès à une machine de développement dédiée. Pour situer cette option dans l’offre de nuvcloud, consultez la présentation de nuvcloud ; pour décider du parcours du classeur, revenez d’abord aux exigences de persistance, de collaboration et de conversion définies par le projet.

Pour aller plus loin

• Préparer la validation d’une intégration Univer avant sa mise en production