Liaison bidirectionnelle
Reliez les applications HTML aux données, résultats de formules et mises à jour collaboratives avec Server SDK.
Fonctionnalité expérimentale
La liaison bidirectionnelle est encore expérimentale. Les prochaines versions incluront des changements incompatibles ; les API et les modalités d’intégration pourront évoluer.
Univer Server SDK connecte les pages ordinaires HTML, CSS et JavaScript à la feuille. Le tableur conserve les données et les formules, tandis que la page fournit des formulaires, des mesures, des graphiques et des interactions d'affaires. Un changement à une entrée de chaque côté met à jour l'autre côté. Le SDK permet à une application de transformer un modèle de tableur en calculateur de devis, un tableau de bord ou une application d'affaires interactive.
Exemple : une application liée à son tableur
L'exemple du Sommet du projet expose la croissance, le prix d'offre et le mélange de paiements en espèces comme des contrôles à gauche, avec le cahier de travail financier complet à droite. Un changement à une hypothèse met à jour les formules, cartes métriques et graphiques connexes.
La capture d'écran montre un modèle exécuté dans un navigateur local. L'édition partagée et la persistance utilisent l'intégration de collaboration décrite ci-dessous. Cliquez sur l'image pour l'afficher en pleine taille.
Une Sheet, plusieurs interfaces
La vue HTML communique avec son hôte à travers l'exécution de la page. Le moteur de reliure lit et écrit le contenu de la feuille dans sa propre instance headless Univer. Univer SDK gère les formules et la collaboration, et le calque de reliage livre des valeurs modifiées à la page.
Des pages encastrées se rafraîchissent également lorsqu'un utilisateur modifie directement le tableur ou qu'un autre utilisateur effectue un changement collaboratif. Une seule vue HTML peut accéder à plusieurs unités pour lesquelles elle est autorisée. L'hôte charge un moteur par unité, et chaque moteur maintient sa propre instance headless Univer.
Déclarer les liaisons en HTML
Une référence de données sur un élément maintient son texte ou son contrôle synchronisé automatiquement. Les références de cellules utilisent le formulaire unitId:sheetId:A1. Chaque ID est encodé séparément avec encodeURIComponent, et l'ID de la feuille de travail doit rester stable.
| Attribut | Usage |
|---|---|
data-univer-cell-text | Affiche une valeur de cellule comme le texte de l'élément. |
data-univer-cell-model | Synchronise une cellule et un contrôle de forme dans les deux sens. |
data-univer-cell-subscribe | Déclare un abonnement cellulaire pour le rendu personnalisé JavaScript. |
data-univer-range-subscribe | Déclare un abonnement rectangulaire pour les cartes, listes et autres consommateurs d'une matrice. |
Par exemple, le prix unitaire est en B2, la quantité est en B3 et B4 détient =B2*B3. Le fragment de gabarit suivant relie les deux entrées et le total à ces cellules :
<label> Prix unitaire <input type="number" min="0" step="0.01" data-univer-cell-model="book:sheet:B2" /></label><label> Quantité <input type="number" min="0" step="1" data-univer-cell-model="book:sheet:B3" /></label><p>Total: <span data-univer-cell-text="book:sheet:B4"></span></p>Remplacer book et sheet par des ID autorisés réels, puis charger le modèle via Renderer. Les formules sont définies dans la feuille, et la page ne lit que les résultats. Entrées de texte, entrées de nombre, entrées de plage, cases à cocher, zones de texte et commandes à sélection unique se lient selon leurs types de valeurs.
Étendre graphiques et interactions avec JavaScript
La page d'exécution initialise window.univerBinding avant que n'importe quel script de template ne soit exécuté. Déclarez la plage de graphiques avec data-univer-range-subscribe, puis appelez subscribeRangeById(elementId, callback) pour recevoir la matrice et mettre à jour le graphique. Les composants qui affichent une valeur unique utilisent subscribeCellById().
Utilisez getCellState() / getRangeState() pour lire une fois, setCellValue() et insertRowsWithValues() afin d'insérer des lignes et de les remplir en une seule opération. Un abonnement fournit l'état actuel d'abord et ensuite chaque changement de valeur réelle. Les modifications locales, les modifications collaboratives et les résultats de formules appliquées peuvent tous rafraîchir l'abonnement.
Les références lisent les coordonnées fixes et ne suivent donc pas l'enregistrement original lorsque des lignes ou des colonnes sont insérées ou supprimées. Une écriture scalaire remplace toute formule ou texte riche déjà présent dans la cellule, ainsi lier seulement les cellules qui détiennent l'entrée d'entreprise.
Connecter l’hôte et l’Agent
L'application fournit un conteneur, un modèle HTML et loadEngine. Le chargeur autorise l'accès à l'unité, configure la collaboration et retourne un moteur chargé. Le rentier possède la page isolée, la messagerie entre cette page et l'hôte, et le cycle de vie des moteurs qu'il livre. Ce point d'entrée accepte ces trois entrées :
import { renderHtmlView, type RenderHtmlViewOptions,} from '@univerjs-labs/html-view-renderer/render';export function createPreview( container: HTMLElement, html: string, loadEngine: RenderHtmlViewOptions['loadEngine'],) { return renderHtmlView({ container, html, loadEngine });}Un agent peut générer du HTML avec des déclarations contraignantes qui réutilisent les données de la feuille et les règles de calcul. Appelez view.inspect.open() pour inspecter la correspondance entre une unité, une feuille, une référence et un élément de page.
L'hôte détient les identifiants de collaboration, et le serveur impose l'accès. Gardez l'interface utilisateur de feuille et le moteur Headless dans des environnements JavaScript séparés, tels que des pages séparées ou des iframes.
Distinguer mise à jour locale et confirmation de sauvegarde
| Opération | Signification |
|---|---|
| Écriture de page terminée | L'opération locale a été exécutée, mais le serveur ne l'a peut-être pas encore reconnue. |
await view.flush() | Soumettre les valeurs provisoires des contrôles, attendre les écrits antérieurs et l'accusé de réception de la collaboration, puis permettre à l'édition de continuer. |
await view.prepareToLeave() | Laisser une fois que le save réussit, ou appeler view.resume() si la navigation est annulée. |
view.dispose() | Relâche les connexions, les moteurs et les abonnements. Il ne sauvegarde aucune donnée. |
Les abonnements rafraîchissent les valeurs à l'écran une fois les résultats de la formule appliquée. Si un save échoue, gardez la page ouverte et réessayez le save. L'écriture d'une page complétée ne signifie pas que les données ont été enregistrées.
Poursuivre l’intégration
- Dépôt et présentation du SDK
- API Binding Engine
- Attributs de liaison HTML
- Intégration de Renderer
- API JavaScript de page
Fonctions associées : exécution sans interface et calcul serveur · collaboration en temps réel · Agents et automatisation.
Que pensez-vous de ce guide ?