Installation et utilisation de base

Univer adopte une conception basée sur des plugins afin d’offrir aux développeurs un framework flexible et extensible pour les applications de documents électroniques. Grâce à cette approche, Univer peut facilement intégrer différents modules fonctionnels pour répondre aux besoins de chaque utilisateur. Elle accroît 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 réalité un ensemble de plugins préconfigurés. Les deux modes offrent donc les mêmes fonctionnalités lorsqu’aucune extension complexe n’est nécessaire.

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 propose une série de fonctionnalités sous forme de plugins. Outre certains plugins essentiels au produit, vous pouvez ajouter les autres de manière sélective selon vos besoins. Nous prendrons ici l’application Univer Sheets la plus simple comme exemple pour expliquer comment combiner et installer manuellement des plugins.

Contrairement au mode prédéfini, le mode plugin n’inclut pas l’API Facade¹ par défaut. Dans les exemples de code suivants, les éléments liés à l’API Facade sont facultatifs et peuvent être supprimés selon vos besoins.

Utilisation d’un gestionnaire de packages

Installation

Nous utilisons React pour développer l’interface, ce qui n’empêche pas d’utiliser Univer avec Vue ou Angular, et Rxjs pour gérer les flux de données. Ces deux bibliothèques étant largement utilisées dans le développement front-end moderne, nous les traitons comme des peerDependencies². Toutefois, les outils de gestion de packages ne gèrent pas tous les peerDependencies de la même manière ; certains détails méritent donc votre attention.

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

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

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

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

Utilisation

1. Vous devez importer dans votre projet les fichiers de style et les packs linguistiques d’Univer, ainsi que certains plugins indispensables :

   TypeScript

   import { LocaleType, mergeLocales, Univer, UniverInstanceType } 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 { UniverSheetsPlugin } from '@univerjs/sheets'import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'import SheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US'import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'import SheetsNumfmtUIEnUS from '@univerjs/sheets-numfmt-ui/locale/en-US'import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'import SheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US'import SheetsEnUS from '@univerjs/sheets/locale/en-US'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/sheets-ui/lib/index.css'import '@univerjs/sheets-formula-ui/lib/index.css'import '@univerjs/sheets-numfmt-ui/lib/index.css'

   Développer le code

2. Si vous avez besoin de l’API Facade, vous pouvez importer ici les packages Facade correspondants. Cette étape est facultative, mais recommandée :

   TypeScript

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

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

   TypeScript

   const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      DocsUIEnUS,      SheetsEnUS,      SheetsUIEnUS,      SheetsFormulaUIEnUS,      SheetsNumfmtUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverFormulaEnginePlugin)univer.registerPlugin(UniverUIPlugin, {  container: 'app',})univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)univer.registerPlugin(UniverSheetsPlugin)univer.registerPlugin(UniverSheetsUIPlugin)univer.registerPlugin(UniverSheetsFormulaPlugin)univer.registerPlugin(UniverSheetsFormulaUIPlugin)univer.registerPlugin(UniverSheetsNumfmtPlugin)univer.registerPlugin(UniverSheetsNumfmtUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})const univerAPI = FUniver.newAPI(univer)

   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,  UniverSheetsPlugin,  UniverSheetsUIPlugin,  UniverSheetsFormulaPlugin,  UniverSheetsFormulaUIPlugin,  UniverSheetsNumfmtPlugin,  UniverSheetsNumfmtUIPlugin,])

Chargement différé des plugins

L’un des principaux avantages du mode plugin est de pouvoir contrôler plus finement 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.

// ...univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {  univer.registerPlugin(UniverWatermarkPlugin, {    textWatermarkSettings: {      content: 'Hello, Univer!',      fontSize: 36,    },  })})

Notre démo officielle utilise cette technique d’optimisation ; vous pouvez vous y référer.

Prise en charge mobile

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

La prise en charge mobile de Sheets reste expérimentale ; vérifiez les fonctionnalités nécessaires sur les appareils ciblés.

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 { UniverSheetsFormulaMobileUIPlugin } from '@univerjs/sheets-formula-ui'import { UniverSheetsNumfmtMobileUIPlugin } from '@univerjs/sheets-numfmt-ui'import { UniverSheetsMobileUIPlugin } from '@univerjs/sheets-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverSheetsMobileUIPlugin)univer.registerPlugin(UniverSheetsFormulaMobileUIPlugin)univer.registerPlugin(UniverSheetsNumfmtMobileUIPlugin)

Conservez UniverDocsUIPlugin dans Sheets. UniverSheetsMobileUIPlugin en dépend pour l’édition de texte dans les cellules. L’éditeur Docs indépendant utilise 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>

Importation depuis un CDN

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

Configuration en mode prédéfini

Nous allons présenter brièvement comment créer rapidement une application Univer Sheets en moins de vingt lignes de code.

Utilisation d’un gestionnaire de packages

Si votre projet utilise déjà des outils de développement front-end modernes, l’intégration d’Univer sera très simple. Pour créer des applications Univer, nous recommandons des outils de build offrant une bonne prise en charge des 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 packages de votre choix pour installer @univerjs/presets :

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

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

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

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

Utilisation

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

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

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

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

Méthode createUniver

La méthode createUniver accepte un objet de configuration contenant les paramètres d’Univer, tels que la langue, le thème et les plugins. Elle renvoie un objet qui contient l’instance 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 de paramètres régionaux dont la clé correspond à l’environnement linguistique et la valeur au pack linguistique.
• theme : objet de thème facultatif.
• presets : tableau contenant les préréglages à enregistrer, comme UniverSheetsCorePreset.
• plugins : tableau contenant les plugins supplémentaires à enregistrer.

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

Importation depuis un CDN

Si vous ne souhaitez pas utiliser de gestionnaire de packages ou voulez simplement essayer rapidement les fonctionnalités d’Univer, vous pouvez importer les ressources correspondantes depuis un CDN. Pour en savoir plus, consultez 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 comment manipuler les données.