Intégration de l’échange de fichiers

Pour ouvrir un fichier Excel dans Univer, convertissez-le en données lisibles par l’éditeur. À l’export, reconvertissez les données modifiées en Excel. Le module serveur @univerjs-pro/exchange-node assure la conversion ; le navigateur téléverse, ouvre les documents et télécharge les résultats.

Sans édition collaborative

Par exemple, l’utilisateur téléverse un fichier Excel, le modifie dans la page et télécharge le résultat en Excel.

1. Le navigateur téléverse le fichier ; le serveur le convertit en données Univer et les renvoie.
2. Le navigateur ouvre un classeur avec ces données pour l’édition.
3. À l’export, le navigateur envoie les données modifiées au serveur, qui génère le fichier Excel.

Aucun service collaboratif n’est nécessaire. L’« instantané » des API navigateur désigne ces données documentaires. Son import-export exige toujours une conversion serveur. Pour sauvegarder le travail et le reprendre plus tard, votre application doit aussi stocker ces données.

Consultez Import-export de fichiers Office pour installer et utiliser le module. Commencez également là pour un simple traitement de fichiers dans Node.js.

Avec édition collaborative

Par exemple, l’utilisateur importe un Excel, partage le document avec ses collègues, le modifie avec eux et l’exporte ensuite.

1. Le serveur convertit le fichier téléversé et enregistre le résultat comme document collaboratif.
2. Il renvoie un ID que le navigateur ouvre ; les autres utilisateurs rejoignent ce même ID.
3. À l’export, le serveur lit le dernier contenu et génère le fichier Excel à télécharger.

Le unitId des API navigateur correspond à cet ID. Terminez d’abord l’intégration collaborative, puis exécutez l’exemple Exchange. Étudiez ensemble son code navigateur, serveur et conversion.

Attendez la synchronisation des modifications avant d’exporter, sinon les changements récents peuvent manquer. Consultez la section Office Exchange côté serveur des modules d’extension pour lire et convertir les documents collaboratifs.

Connecter les boutons d’import-export

Une fois la conversion serveur fonctionnelle, connectez-la à la page :

• Menus Univer ou API Facade : enregistrez File Endpoint et Exchange Endpoint comme dans l’exemple Exchange, puis configurez les plugins navigateur.
• Vos propres boutons : appelez vos API applicatives. Après import, ouvrez les données ou l’ID renvoyés ; après export, téléchargez le fichier généré.

La configuration navigateur figure dans Sheets, Docs, Slides, Boards, Bases et PDFs. L’exemple collaboratif utilise Sheets. Pour les autres produits, consultez Import-export Office et les formats de votre version.

Vérifier l’intégration

Importez un vrai fichier métier, modifiez-le, puis exportez-le. Ouvrez le résultat dans une application Office et vérifiez changements, formules, images et disposition. En collaboration, vérifiez aussi l’ouverture par d’autres utilisateurs et la conservation après redémarrage serveur.

Avant déploiement, limitez les tailles et gérez échecs et délais de conversion. Téléversements, suivi des tâches et téléchargements nécessitent des contrôles d’accès ; consultez Identité et autorisation.

Échecs d’export et limites de licence

Un export peut échouer à l’envoi ou pendant le suivi de sa tâche. Une réponse HTTP réussie ne garantit pas le fichier : vérifiez error.code et l’état de la tâche. Le client Exchange transmet les erreurs serveur d’export via IExchangeService.requestState$ ; une UI personnalisée peut s’y abonner avant l’opération.

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)})

Comparez les valeurs nommées ErrorCode de @univerjs/protocol, pas le texte traduit. Conservez le message serveur pour le diagnostic. Une panne réseau, une réponse de tâche invalide ou un délai dépassé peut produire une erreur générique ; cela ne prouve pas un rejet de licence. Appelez subscription.unsubscribe() lors du retrait de l’éditeur.

Un backend ou proxy personnalisé doit conserver la réponse structurée et signaler les tâches échouées au lieu de les laisser en attente. Augmenter maxTimeoutTime prolonge uniquement le suivi, sans modifier quota ou couverture de licence.

Pièces jointes OLE

Sheets, Docs et Slides conservent les fichiers OLE importés séparément de leurs aperçus. Les utilisateurs peuvent télécharger les originaux disponibles et, avec les droits nécessaires, renommer une occurrence ou supprimer une pièce jointe. Les images et PDF sont prévisualisables. L’aperçu Office utilise la conversion JSON d’Exchange et un éditeur temporaire en lecture seule, sans créer de document enfant persistant. Il n’exécute ni application Office native ni macro.

Ajoutez ole à l’enregistrement existant de UniverDrawingPlugin avant Exchange. La route ci-dessous doit ouvrir l’interface documentaire de votre application ; utilisez si nécessaire le deuxième argument de getLink (type de document). Exchange fournit la conversion Office et la détection de collaboration. Les pièces jointes référencées par UUID nécessitent aussi ole.attachmentIo avec les callbacks autorisés upload(file, targetUnitId) et read(attachment, signal). L’aperçu Office exige le moteur de rendu correspondant ou des callbacks previewOffice / createOfficePreview personnalisés.

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

La conversion d’une pièce jointe Office en document en ligne nécessite un hôte collaboratif, le droit de modification, la conversion et getLink. Elle crée un document indépendant et enregistre son identité sur la pièce jointe pour les prochaines ouvertures. Modifier ce document ne remplace pas les octets originaux. Les pièces jointes manquantes, externes ou non prises en charge conservent leur état.

L’export utilise par défaut oleAttachmentSource: 'original'. Avec 'online', il incorpore les versions actuellement confirmées des documents convertis uniquement dans cet export, sans modifier les originaux stockés. Attendez la synchronisation et vérifiez côté serveur les droits sur les documents référencés. Passez l’option en deuxième argument des API Docs/Slides ou en quatrième pour Sheets ; les variantes snapshot gardent la même position. Voir l’API d’export.

Exchange transmet fileID et la Unit propriétaire, sourceUnitID, pour les pièces jointes persistées. Le backend doit vérifier leur relation et les droits du demandeur avant la conversion par référence. Le suivi peut renvoyer progress.stage : reading, converting, creating ou done. Pour une interface personnalisée, consultez les API d’import et de progression.