Installation et utilisation de base

Univer repose sur une architecture à base de plugins afin de fournir aux développeurs un framework flexible et extensible pour les applications de documents électroniques. Cette architecture permet à Univer d’intégrer facilement différents modules fonctionnels afin de répondre aux besoins de chaque utilisateur. Elle augmente toutefois la complexité de l’application, en particulier pour les développeurs qui découvrent Univer.

C’est pourquoi Univer propose deux méthodes pour faciliter une intégration et une prise en main rapides : le mode plugin et le mode prédéfini. Un préréglage est en fait un ensemble de plugins préconfigurés. En l’absence d’extensions complexes, les deux modes offrent donc les mêmes fonctionnalités.

Voici les différences entre le mode prédéfini et le mode plugin :

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 un ensemble de fonctionnalités sous forme de plugins. Outre certains plugins principaux indispensables au produit, vous pouvez ajouter les autres plugins de façon sélective selon vos besoins. Nous prendrons ici l’application Univer Docs la plus simple pour illustrer l’installation et l’association manuelles de plugins.

Contrairement au mode prédéfini, le mode plugin n’inclut pas l’API Facade¹ par défaut. Les exemples ci-dessous l’utilisent : importez donc les packages de façade correspondants avant de créer l’instance de l’API.

Utilisation d’un gestionnaire de packages

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 dependencies² 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/*.

pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui react react-dom rxjs

bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

Utilisation

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

<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.

1. Vous devez importer dans votre projet les fichiers de style d’Univer, les packs de langue et quelques plugins nécessaires :

   TypeScript

   import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { FUniver } from '@univerjs/core/facade'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 { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'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'

2. Importez les packages de façade utilisés dans l’exemple :

   TypeScript

   import '@univerjs/engine-formula/facade'import '@univerjs/ui/facade'import '@univerjs/docs/facade'import '@univerjs/docs-ui/facade'

3. Créez ensuite une instance d’Univer et enregistrez ces plugins :

   TypeScript

   const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      DocsUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverFormulaEnginePlugin)univer.registerPlugin(UniverUIPlugin, {  container: 'app',})univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})

   Développer le code

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.

univer.registerPlugins([  UniverRenderEnginePlugin,  UniverFormulaEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,])

Chargement différé des plugins

L’un des principaux avantages du mode plugin est qu’il permet de contrôler plus précisément le moment où les plugins sont chargés. Une approche courante consiste à ne charger que les plugins indispensables lors de l’initialisation de l’application, puis à différer le chargement de certains plugins jusqu’à la fin du premier rendu.

// ...const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {  univer.registerPlugin(UniverWatermarkPlugin, {    textWatermarkSettings: {      content: 'Hello, Univer!',      fontSize: 36,    },  })})

Importer depuis un CDN

Si vous ne souhaitez pas utiliser de gestionnaire de paquets ou voulez simplement essayer rapidement les fonctionnalités d’Univer, vous pouvez importer les ressources correspondantes via un CDN. Pour en savoir plus, consultez la page Utiliser Univer via un CDN.

Prise en charge mobile

Utilisez les plugins UI mobiles pour les commandes tactiles de Univer Docs.³ 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.

import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsMobileUIPlugin)

Actuellement, UniverSheetsCorePreset et UniverDocsCorePreset enregistrent des UI de bureau et ne proposent pas d’option mobile: true. Assemblez explicitement les plugins mobiles. Les ajouter après un preset de bureau ne remplace pas son UI.

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.

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.

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

Configurer Web SDK en mode prédéfini

Cette section présente brièvement comment créer rapidement une application Univer Docs en moins de vingt lignes de code.

Utiliser un gestionnaire de paquets

Si votre projet utilise déjà des outils de développement front-end modernes, l’intégration d’Univer est très simple. Pour créer des applications Univer, nous vous recommandons d’utiliser des outils de build qui prennent bien en charge les modules ES, comme Vite, esbuild ou Webpack 5. Si vous utilisez d’autres outils de build, tels que Webpack 4, une configuration supplémentaire peut être nécessaire.

Installation

Utilisez le gestionnaire de paquets de votre choix pour installer @univerjs/presets :

pnpm add @univerjs/presets @univerjs/preset-docs-core

npm install @univerjs/presets @univerjs/preset-docs-core

yarn add @univerjs/presets @univerjs/preset-docs-core

bun add @univerjs/presets @univerjs/preset-docs-core

Utilisation

Le code suivant permet de démarrer une application Univer Docs :

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

import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'import UniverPresetDocsCoreEnUS from '@univerjs/preset-docs-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-docs-core/lib/index.css'const { univer, univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetDocsCoreEnUS,    ),  },  presets: [    UniverDocsCorePreset({      container: 'app',    }),  ],})univerAPI.createDocument({})

L’objet univerAPI renvoyé ici est appelé API Facade d’Univer. Il permet d’utiliser de nombreuses fonctionnalités fournies par Univer.

Méthode createUniver

La méthode createUniver accepte un objet de configuration qui contient les paramètres d’Univer, tels que la langue, le thème et les plugins. Elle renvoie un objet contenant l’instance d’Univer et l’instance de l’API Facade d’Univer.

Voici quelques propriétés de l’objet de configuration :

• locale : environnement linguistique, qui peut être une valeur de l’énumération LocaleType.
• locales : objet des paramètres régionaux, dont les clés sont les environnements linguistiques et les valeurs les objets de packs de langue.
• theme : objet de thème facultatif.
• presets : tableau des préréglages à enregistrer, comme UniverDocsCorePreset.
• plugins : tableau des plugins supplémentaires à enregistrer.

Lorsque vous utilisez un plugin qui n’est inclus dans aucun package de préréglage, ou que vous implémentez votre propre plugin, vous pouvez l’enregistrer avec la propriété plugins. Vous pouvez également choisir d’enregistrer des plugins à l’aide de la méthode univer.registerPlugin après avoir obtenu l’instance d’Univer.

Importer depuis un CDN

Si vous ne souhaitez pas utiliser de gestionnaire de paquets ou voulez simplement essayer rapidement les fonctionnalités d’Univer, vous pouvez importer les ressources correspondantes via un CDN. Pour en savoir plus, consultez la page Utiliser Univer via un CDN.

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 :

pnpm add @univerjs/<package-name>@alpha # Alpha version
pnpm add @univerjs/<package-name>@beta # Beta version

npm install @univerjs/<package-name>@alpha # Alpha version
npm install @univerjs/<package-name>@beta # Beta version

yarn add @univerjs/<package-name>@alpha # Alpha version
yarn add @univerjs/<package-name>@beta # Beta version

bun add @univerjs/<package-name>@alpha # Alpha version
bun add @univerjs/<package-name>@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

• Concepts de base - Découvrez les concepts de base d’Univer.
• Fonctionnalités - Découvrez les fonctionnalités d’Univer et apprenez à manipuler les données.