Intégration de documents
Intégrez d’autres types de documents Univer dans Sheets, Docs, Slides, Boards et Bases en conservant leurs fonctions d’édition.
L'intégration permet d'éditer un document Univer à l'intérieur d'un autre. Un tableur peut être placé dans un document, des diapositives sur une carte ou une base dans un onglet de cahier de travail. Le document hôte contient l'intégration, et le document d'enfant est le contenu qu'il renvoie. Chaque document conserve son propre modèle de données.
Emplacements disponibles
| Hôte | Emplacement | Enfants pris en charge |
|---|---|---|
| Sheets | Objet flottant dans une feuille, onglet du classeur | Docs, Slides, Boards, Bases |
| Docs | Bloc dans le corps du document | Sheets, Slides, Boards, Bases |
| Slides | Objet flottant sur une page, liste des pages | Sheets, Docs, Boards, Bases |
| Boards | Objet flottant sur le canevas | Sheets, Docs, Slides, Bases |
| Bases | Liste des tables | Sheets, Docs, Slides, Boards |
Les objets flottants et les blocs de corps affichent l'enfant à l'intérieur de l'hôte, et l'édition utilise les capacités du produit enfant. Les onglets et les entrées de liste transforment l'enfant en une page vers laquelle il peut être commuté; lorsque cette page est activée, la zone de menu est transférée à l'enfant.
Les capacités intégrées ne prennent pas en charge le PDF, n'intègrent pas le même type de produit, ou n'intègre pas un autre document à l'intérieur d'un enfant intégré.
Enregistrer les plugins
Les deux produits et leur interface utilisateur doivent d'abord fonctionner dans la même instance Univer. Embed ne remplace pas leurs plugins de base : intégrer Docs dans Sheets nécessite à la fois Sheets et Docs. Conserver les versions de dépendance alignées et configurer UniverLicensePlugin comme décrit dans Configuration de la licence .
pnpm add @univerjs-pro/embed @univerjs-pro/embed-uinpm install @univerjs-pro/embed @univerjs-pro/embed-uiyarn add @univerjs-pro/embed @univerjs-pro/embed-uibun add @univerjs-pro/embed @univerjs-pro/embed-uiAjoutez ces importations à l'application existante et enregistrez les plugins avant de créer des documents. univer est l'instance Univer existante.
import { UniverEmbedPlugin } from '@univerjs-pro/embed'import { UniverEmbedUIPlugin } from '@univerjs-pro/embed-ui'import '@univerjs-pro/embed/facade'import '@univerjs-pro/embed-ui/lib/index.css'univer.registerPlugin(UniverEmbedPlugin)univer.registerPlugin(UniverEmbedUIPlugin)Fusionner l'exportation par défaut de @univerjs-pro/embed-ui/locale/en-US dans la configuration locales existante. D'autres langues utilisent leur propre paquet local; voir Internationalisation.
@univerjs-pro/embed fournit la relation d'intégration, la résolution de référence, et le Facade API. @univerjs-pro/embed-ui fournit les conteneurs, la mise au point et les menus. @univerjs-pro/embed-unit-ui fournit un visionneur autonome pour un document référencé et n'est pas nécessaire pour l'intégration de base.
Intégrer un document dans un tableur
La fonction suivante prend un cahier de travail et un document qui sont déjà chargés dans la même instance Univer et insère un document flottant dans la feuille de travail active. Utilisez l'ID réel de l'enfant dans ref; type=doc doit correspondre à unitType.
import type { FUniver } from '@univerjs/core/facade'import type { FDocument } from '@univerjs/docs/facade'import type { FWorkbook } from '@univerjs/sheets/facade'import '@univerjs-pro/embed/facade'import '@univerjs/docs/facade'import '@univerjs/sheets/facade'async function embedDocument( univerAPI: FUniver, workbook: FWorkbook, document: FDocument,) { const embed = univerAPI.createEmbed<FDocument>({ host: { unitId: workbook.getId(), surface: univerAPI.Enum.FEmbedHostSurface.SheetFloating, context: { subUnitId: workbook.getActiveSheet().getSheetId() }, }, content: { unitType: univerAPI.Enum.UniverInstanceType.UNIVER_DOC, ref: `#unit=${encodeURIComponent(document.getId())}&type=doc`, }, }) await embed.loadAsync() return embed}createEmbed() crée la relation et définit sa position dans l'hôte. loadAsync() charge l'enfant et retourne sa Facade. Les appelants doivent await cette fonction et gérer les défaillances de chargement. Une référence locale exige que le document cible existe dans l'instance courante; un ID seul ne crée pas ou ne télécharge pas le document.
Choisir l’emplacement
Sélectionnez host.surface à partir de univerAPI.Enum.FEmbedHostSurface. host.context décrit l'endroit où le contenu est placé dans l'hôte.
| Emplacement | Membre de l’énumération | Paramètres |
|---|---|---|
| Objet flottant dans une feuille | SheetFloating | subUnitId sélectionne la feuille de travail; placement choisit le mode d'ancrage, par défaut en position |
| Onglet du classeur | SheetTab | sheetIndex, sheetName |
| Bloc du document | DocBlock | startIndex : décalage UTF-16 dans le dataStream du corps ; omettre de l'ajouter au corps modifiable |
| Objet flottant d’une diapositive | SlideFloating | subUnitId sélectionne la page ; left, top, width, height définissent la position et la taille |
| Liste des pages | SlidePage | pageIndex, pageName |
| Objet flottant d’un tableau blanc | BoardFloating | subUnitId sélectionne la page ; left, top, width, height définissent la position et la taille |
| Liste des tables | BaseTable | tableIndex, tableName |
Les indices d'insertion pour les listes sont basés sur zéro, et omettre un index appendices à la fin. Les limites flottantes utilisent les coordonnées du modèle de document plutôt que les coordonnées du port de vue du navigateur. Ne pas écrire défilement ou zoom offsets directement dans ces valeurs.
Choisir la vue initiale de l’enfant
displayTarget définit ce que l'enfant affiche en premier, quel que soit l'endroit où l'enfant se trouve dans l'hôte. Passez-le quand l'intégration est créée, ou changez-le plus tard avec embed.setDisplayTarget().
| Enfant | Paramètres de la vue initiale |
|---|---|
| Sheets | { subUnitId: 'sheet-id' } |
| Slides | { pageId: 'page-id' } |
| Bases | { tableId: 'table-id', viewId: 'view-id' } ; accepte aussi dashboardId |
Utilisez des ID stables plutôt que d'afficher des noms. Si la cible n'existe plus, l'enfant revient à sa première vue disponible. La navigation à l'intérieur de l'enfant n'écrase pas cette valeur par défaut. displayTarget.
Enregistrer et retirer une intégration
Un snapshot hôte doit conserver les données du plugin Embed dans resources et les positions d'intégration dans le corps, les dessins ou les listes de l'hôte. La relation stocke une référence à l'enfant et une vue par défaut; il ne fusionne pas automatiquement le contenu actuel de l'enfant dans l'instantané hôte. Les applications qui utilisent le stockage local doivent enregistrer les enfants séparément et s'assurer que leurs références peuvent être résolues après la restauration.
univerAPI.listEmbeds({ hostUnitId }) liste les embarquations d'un hôte, et univerAPI.getEmbed({ hostUnitId, embedId }) récupère une seule embarquation. embed.remove() supprime l'intégration de l'hôte; il ne supprime pas les données persistantes de l'enfant.
Charger des documents collaboratifs
Pour les documents du serveur, remplissez d'abord Intégration de la collaboration du navigateur, puis enregistrez le pont de collaboration :
pnpm add @univerjs-pro/collaboration-embednpm install @univerjs-pro/collaboration-embedyarn add @univerjs-pro/collaboration-embedbun add @univerjs-pro/collaboration-embedimport { UniverCollaborationEmbedPlugin } from '@univerjs-pro/collaboration-embed'univer.registerPlugin(UniverCollaborationEmbedPlugin)Ce plugin dépend de UniverCollaborationPlugin, UniverCollaborationClientPlugin et UniverEmbedPlugin. Il charge l'enfant à travers le service d'instantané de collaboration et rejoint ensuite la session de collaboration de cet enfant. Passez l'identifiant de document du serveur réel en #unit=...&type=...; l'accès reste régi par la configuration identité et autorisation existante.
Pour utiliser le stockage personnalisé au lieu du service de collaboration, configurez resourceRefUnitProviderRegistrations sur UniverEmbedPlugin afin que les références résolvent les instances de document.
D'autres options et méthodes sont documentées dans les API FEmbed, API FUniverser et Intégrer l'API du plugin.
Que pensez-vous de ce guide ?