Web SDK

Installation et utilisation de base

Ce chapitre présente l’installation et l’utilisation de base d’Univer Boards. Boards est distribué en tant que produit Univer Office SDK et fonctionne actuellement en mode plugin.

Si vous ne connaissez pas encore les concepts fondamentaux d’Univer, consultez d’abord le guide de démarrage rapide.

Univer propose deux modes d’intégration : le mode prédéfini et le mode plugin. Le mode prédéfini simplifie la configuration grâce à des ensembles de plugins préconfigurés. Pour une personnalisation ou des extensions approfondies, nous recommandons le mode plugin, qui permet de combiner et de configurer les plugins individuellement.

Configuration en mode plugin

Univer fournit Boards sous la forme d’un ensemble de plugins. Dans un éditeur web, on enregistre généralement l’environnement d’exécution commun d’Univer, le plugin de licence et les dépendances liées aux documents et au dessin, puis les plugins du modèle et de l’interface de Boards.

Utilisation d’un gestionnaire de packages

Utilisez un outil de compilation compatible avec les modules ES et le champ exports de package.json.

Installation

Univer utilise React pour son interface et RxJS pour les flux de données ; il peut aussi être intégré à Vue ou Angular. Vérifiez que les peer dependencies1 react, react-dom et rxjs sont installées. La commande Yarn ci-dessous les inclut explicitement.

Conservez la même version pour tous les packages @univerjs/* et @univerjs-pro/*.

Shell
pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/drawing-ui @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/ink-ui @univerjs-pro/shape-editor-ui @univerjs-pro/boards @univerjs-pro/boards-ui

Utilisation

Créez le conteneur avant d’initialiser Univer et définissez une hauteur explicite :

HTML
<div id="app" style="height: 600px"></div>

Importez les entrées facade utilisées ci-dessous avant d’appeler FUniver.newAPI(univer). Importez les CSS dans cet ordre : @univerjs/design, @univerjs/ui, puis ceux du produit.

Attention

  • Enregistrez UniverLicensePlugin avant les plugins de Boards.
  • Importez les fichiers CSS communs de l’interface avant ceux propres au produit.
  • Enregistrez les plugins d’éléments facultatifs avant d’ouvrir des instantanés contenant ces types d’éléments.
  • UniverBoardsUIPlugin charge automatiquement UniverProFormulaEnginePlugin pour les formes. Si la même instance Univer enregistre aussi UniverFormulaEnginePlugin, installez @univerjs-pro/engine-formula et remplacez l'import et l'enregistrement de ce moteur par UniverProFormulaEnginePlugin dans le code d'initialisation. N'enregistrez pas les deux moteurs de formules.

  1. Importez les styles, les packs de paramètres régionaux et les plugins requis :

    TypeScript
    import { UniverBoardsPlugin } from '@univerjs-pro/boards'import { UniverBoardsUIPlugin } from '@univerjs-pro/boards-ui'import BoardsUIEnUS from '@univerjs-pro/boards-ui/locale/en-US'import { UniverInkUIPlugin } from '@univerjs-pro/ink-ui'import InkUIEnUS from '@univerjs-pro/ink-ui/locale/en-US'import { UniverLicensePlugin } from '@univerjs-pro/license'import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'import DesignEnUS from '@univerjs/design/locale/en-US'import { UniverDocsPlugin } from '@univerjs/docs'import { UniverDocsUIPlugin } from '@univerjs/docs-ui'import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US'import { UniverDrawingPlugin } from '@univerjs/drawing'import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui'import DrawingUIEnUS from '@univerjs/drawing-ui/locale/en-US'import { UniverRenderEnginePlugin } from '@univerjs/engine-render'import { UniverUIPlugin } from '@univerjs/ui'import UIEnUS from '@univerjs/ui/locale/en-US'import '@univerjs/design/lib/index.css'import '@univerjs/ui/lib/index.css'import '@univerjs/docs-ui/lib/index.css'import '@univerjs/drawing-ui/lib/index.css'import '@univerjs-pro/ink-ui/lib/index.css'import '@univerjs-pro/boards-ui/lib/index.css'

  2. Si vous souhaitez utiliser l’API Facade2, importez son point d’entrée :

    TypeScript
    import { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/boards/facade'

  3. Créez une instance d’Univer, enregistrez les plugins, puis créez une unité Board :

    TypeScript
    const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      DocsUIEnUS,      DrawingUIEnUS,      InkUIEnUS,      BoardsUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverDrawingUIPlugin)univer.registerPlugin(UniverInkUIPlugin)univer.registerPlugin(UniverLicensePlugin, {  license: process.env.CLIENT_LICENSE_TEXT,})univer.registerPlugin(UniverBoardsPlugin)univer.registerPlugin(UniverBoardsUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_BOARD, {})const univerAPI = FUniver.newAPI(univer)

Méthodes univer.registerPlugin et univer.registerPlugins

La méthode univer.registerPlugin sert à enregistrer un plugin dans l’instance Univer. Vous pouvez l’appeler après avoir créé l’instance Univer afin d’y enregistrer des plugins.

Vous pouvez enregistrer un plugin avec la méthode univer.registerPlugin(Plugin, options), où Plugin désigne le plugin à enregistrer et options les paramètres de configuration facultatifs, qui peuvent varier d’un plugin à l’autre.

Vous pouvez également utiliser univer.registerPlugins pour passer un tableau et enregistrer plusieurs plugins en une seule fois. Cette possibilité est utile lorsque vous devez centraliser la gestion des plugins.

TypeScript
univer.registerPlugins([  UniverRenderEnginePlugin,  [UniverUIPlugin, { container: 'app' }],  UniverDocsPlugin,  UniverDocsUIPlugin,  UniverDrawingPlugin,  UniverDrawingUIPlugin,  UniverInkUIPlugin,  [UniverLicensePlugin, {    license: process.env.CLIENT_LICENSE_TEXT,  }],  UniverBoardsPlugin,  UniverBoardsUIPlugin,])

L’objet univerAPI renvoyé par FUniver.newAPI(univer) est l’API Facade d’Univer. Utilisez-le pour créer des Boards et manipuler leurs éléments.

Prise en charge mobile

Ces exemples nécessitent des paquets SDK exportant les plugins mobiles ci-dessous. Gardez toutes les dépendances @univerjs/* et @univerjs-pro/* à la même version.

1.0.0-rc.0 n’exporte pas UniverBoardsMobileUIPlugin. Utilisez une version compilée incluant cette entrée mobile avant de suivre cet exemple.

Utilisez les plugins UI mobiles pour les commandes tactiles de Univer Boards.3 Choisissez le mode avant de créer l’éditeur.

Dans l’exemple en mode plugin ci-dessus, remplacez les imports et inscriptions UI suivants avant createUnit(). Ne les ajoutez pas à un éditeur de bureau déjà initialisé. Conservez les modèles, moteurs, traductions, CSS et imports Facade. Les classes sont des exports nommés du même point d’entrée du paquet.

TypeScript
import { UniverBoardsMobileUIPlugin } from '@univerjs-pro/boards-ui'import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'import { UniverDrawingMobileUIPlugin } from '@univerjs/drawing-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsMobileUIPlugin)univer.registerPlugin(UniverDrawingMobileUIPlugin)univer.registerPlugin(UniverBoardsMobileUIPlugin)

Correspondance des plugins

Enregistrez uniquement les fonctionnalités utilisées, avec leurs modèles et dépendances. Un export UI mobile ne garantit pas des commandes identiques sur les deux interfaces. Les fonctionnalités Pro exigent toujours la licence correspondante. Pour les fonctionnalités nécessitant un backend, intégrez les modules correspondants du Univer Server SDK à votre application.

PaquetInscription de bureauInscription mobile
@univerjs/uiUniverUIPluginUniverMobileUIPlugin
@univerjs/docs-uiUniverDocsUIPluginUniverDocsMobileUIPlugin
@univerjs/drawing-uiUniverDrawingUIPluginUniverDrawingMobileUIPlugin
@univerjs-pro/boards-uiUniverBoardsUIPluginUniverBoardsMobileUIPlugin
@univerjs/thread-comment-uiUniverThreadCommentUIPluginUniverThreadCommentMobileUIPlugin
@univerjs-pro/shape-editor-uiUniverShapeEditorUIPluginUniverShapeEditorMobileUIPlugin
@univerjs-pro/chart-uiUniverChartUIPluginUniverChartMobileUIPlugin
@univerjs-pro/exchange-clientUniverExchangeClientPluginUniverExchangeClientMobileUIPlugin
@univerjs-pro/boards-chart-uiUniverBoardsChartUIPluginUniverBoardsChartMobileUIPlugin
@univerjs-pro/boards-mind-uiUniverBoardsMindUIPluginUniverBoardsMindMobileUIPlugin
@univerjs-pro/boards-resources-uiUniverBoardsResourcesUIPluginUniverBoardsResourcesMobileUIPlugin
@univerjs-pro/boards-table-uiUniverBoardsTableUIPluginUniverBoardsTableMobileUIPlugin
@univerjs-pro/boards-thread-comment-uiUniverBoardsThreadCommentUIPluginUniverBoardsThreadCommentMobileUIPlugin

Conteneur et interactions tactiles

Définissez une hauteur explicite et le viewport de la page. 100dvh suit la hauteur dynamique du viewport. Vérifiez le défilement, le zoom par pincement, la sélection de texte, le presse-papiers et le clavier virtuel sur les navigateurs mobiles ciblés. Réduire la largeur ne sélectionne pas les plugins mobiles.

UniverMobileUIPlugin utilise disableAutoFocus: true par défaut pour éviter que l’éditeur ne prenne automatiquement le focus à l’initialisation.

HTML
<meta name="viewport" content="width=device-width, initial-scale=1" /><div id="app" style="height: 100dvh"></div>

Packages de fonctionnalités facultatives

Ajoutez les packages de fonctionnalités lorsque l’éditeur de Board doit prendre en charge les types d’éléments correspondants :

Shell
pnpm add @univerjs-pro/boards-table @univerjs-pro/boards-table-uipnpm add @univerjs-pro/boards-mind @univerjs-pro/boards-mind-ui

Pour des exemples d’enregistrement de fonctionnalités, consultez les pages Tableau, Cartes mentales et Importation et exportation.

Autres versions

Outre les versions stables, Univer propose des canaux alpha / beta et nightly. Ces versions vous donnent un accès anticipé aux fonctionnalités les plus récentes qui n’ont pas encore été publiées officiellement. Gardez toutefois à l’esprit que davantage de fonctionnalités implique aussi davantage de risques. Ces versions peuvent contenir des bugs, des fonctionnalités incomplètes ou instables. Évitez autant que possible de les utiliser dans des environnements de production.

Version alpha / beta

Lorsque l’équipe de développement d’Univer termine une nouvelle fonctionnalité ou une modification importante, elle peut la publier en avant-première sur le canal alpha ou beta. Vous pouvez installer la version alpha / beta d’un package Univer à l’aide de la commande suivante :

Shell
pnpm add @univerjs-pro/boards@alpha # Alpha version
pnpm add @univerjs-pro/boards@beta # Beta version

Si vous rencontrez un problème ou souhaitez faire part de vos commentaires lors de l’utilisation des versions alpha / beta, signalez-les à l’équipe de développement d’Univer via les issues GitHub.

Vos retours sur ces versions préliminaires sont les bienvenus.

Étapes suivantes

Footnotes

  1. Les peerDependencies sont des dépendances que l’application hôte doit fournir dans une version compatible. Elles permettent de partager des bibliothèques comme React avec Univer. ↩

  2. Facade est l’API applicative des plugins enregistrés. Importer une entrée Facade ajoute des méthodes API, mais n’enregistre pas le plugin fonctionnel lui-même. ↩

  3. Un plugin UI mobile sélectionne les commandes tactiles et les services mobiles à l’initialisation. Il ne détecte pas automatiquement l’appareil et ne change pas le mode d’une instance lors du redimensionnement. Pour changer de mode, conservez l’état du document, détruisez l’ancienne instance et initialisez les plugins choisis. ↩

Que pensez-vous de ce guide ?

© 2026 DreamNum Co., Ltd.