Blocs intégrés

Les blocs intégrés placent un produit Univer dans un autre : budgets et tâches dans un document de projet, tableur calculable sur une diapositive, ou plans et notes sur un canevas. Le contenu enfant conserve son modèle de données et son éditeur natif ; son activation adapte le focus et les menus.

Principe : Unit hôte et Unit enfant

L’Unit hôte conserve la position, la taille, la référence à l’enfant et la vue initiale. L’Unit enfant conserve les cellules, paragraphes ou enregistrements réels. Embed résout la référence, charge l’enfant et installe son éditeur dans l’hôte. Une Unit peut être un classeur, un document, une présentation, une table relationnelle ou un canevas.

La relation et le contenu sont enregistrés séparément. Modifier une cellule intégrée met à jour la Sheet enfant ; déplacer ou redimensionner le bloc met à jour son ancrage dans l’hôte.

Emplacements pris en charge

Cinq exemples d’hôtes

Ces exemples en anglais ont été créés avec l’API Facade puis capturés dans le navigateur. Chaque cas utilise des Units enfants indépendantes. Les contenus et chiffres sont fictifs.

Sheet : calculs et note de décision

Le tableau de bord récapitule les dépenses à gauche et intègre un Doc complet à droite. L’onglet Launch tracker ouvre une Relational Table. Ce modèle convient aux devis, analyses opérationnelles et classeurs financiers avec hypothèses et explications. Il rappelle l’insertion d’un document dans Excel.

Doc : une page projet avec budget et tâches

Le corps réunit une Sheet budgétaire et une Relational Table, pour examiner les données et gérer les tâches dans leur contexte. L’organisation ressemble aux bases de données intégrées de Notion ; ici, le budget conserve le moteur de formules de Sheet, les tâches les champs et vues de Relational Table.

Slide : les données sources pendant la revue

Une Sheet budgétaire et une Relational Table de tâches partagent une diapositive avec un indicateur calculé. Comme avec l’intégration d’Excel dans PowerPoint, on peut revenir de la conclusion au modèle modifiable. Le budget affiché a été mis à jour à $62,100.

Relational Table : la note au sein de la base

Le Doc Launch brief apparaît dans la liste à côté de la table de tâches. Alternez entre données structurées et explications dans un CRM ou une base de projet. Il s’agit d’une entrée de liste, sans création automatique d’un document par enregistrement.

Canvases : un espace de planification partagé

Le canevas rassemble une Sheet budgétaire, un Doc de proposition et un récapitulatif calculé. Il convient aux espaces projet, revues et recherches qui nécessitent les données sources et leur contexte pendant la discussion.

Comment les formules restent liées

L’intégration assure l’affichage et l’édition ; les références assurent le calcul. Insérer un bloc ne crée pas de formule de synthèse. Avec les références entre Units, les cellules de Sheet et les Shapes à formule de Doc, Slide et Canvases peuvent lire des plages Sheet ou des champs Relational Table. Les champs de formule Relational Table peuvent aussi référencer Sheet. Lorsque les données et notifications sont disponibles, les modifications pertinentes déclenchent un recalcul.

Les noms lisibles doivent être associés aux ID stables des Units. Utilisez getFormula().buildReference() pour créer la référence et sa correspondance externe dans l’hôte. Pour une table Relational Table, utilisez table.getFormulaName() au lieu de concaténer nom affiché ou ID. Les Shapes calculées utilisent shape.setFormula({ formula, externalReferences }) ; lisez le résultat après le calcul. Voir Formula Facade, Shape Facade et formules Relational Table.

Création et intégration

Enregistrez les produits hôte et enfant et leurs interfaces dans la même instance Univer, puis Embed et Embed UI. Cet exemple insère une Sheet existante dans un Doc ; hostDocument et budgetWorkbook désignent leurs Facades.

import '@univerjs-pro/embed/facade'const block = univerAPI.createEmbed({  host: {    unitId: hostDocument.getId(),    surface: univerAPI.Enum.FEmbedHostSurface.DocBlock,  },  content: {    unitType: univerAPI.Enum.UniverInstanceType.UNIVER_SHEET,    ref: `#unit=${encodeURIComponent(budgetWorkbook.getId())}&type=sheet`,  },})const embeddedWorkbook = await block.loadAsync()

createEmbed() crée la relation et l’ancrage ; loadAsync() charge l’enfant et renvoie sa Facade. displayTarget choisit la feuille, la page Slide ou la vue Relational Table initiale. Le guide d’intégration décrit plugins, styles, langues et chargeurs ; Embed Facade couvre les autres emplacements et méthodes.

Persistance, collaboration et périmètre

• Enregistrement séparé : le Snapshot hôte conserve références, position et réglages d’affichage ; il n’empaquette pas automatiquement le contenu enfant à jour. Supprimer un bloc ne supprime pas le document enfant.
• Chargement collaboratif : Server SDK fournit les snapshots et services collaboratifs de l’enfant. Avec @univerjs-pro/collaboration-embed, le navigateur charge l’Unit enfant et rejoint sa session. Parent et enfant conservent leurs propres modifications et versions.
• Accès et droits : l’application résout les références, charge les données et autorise les accès. Accéder à l’hôte ne donne pas automatiquement le droit de modifier l’enfant.
• Périmètre actuel : les types distincts Sheet, Doc, Slide, Relational Table et Canvases sont pris en charge. PDF, intégration du même type et imbrication supplémentaire sont exclus. Dans un même environnement Univer, une Unit enfant ne peut appartenir qu’à une seule intégration active.

Utilisez la liaison bidirectionnelle pour piloter les champs, indicateurs et graphiques propres à votre application depuis un tableur. Utilisez Embed Block pour conserver l’éditeur du produit enfant.

Retour aux fonctionnalités