API générale

Dans Univer, l’API Facade disponible varie selon le type de document. Cette section présente l’API Facade générale qui s’applique à tous les types de documents.

Importation

import { FUniver } from '@univerjs/core/facade'const univerAPI = FUniver.newAPI(univer)

Concepts

Commandes

La plupart des opérations d’Univer sont enregistrées dans le système de commandes et déclenchées par son intermédiaire. Cette approche unifiée des opérations permet à Univer de mettre facilement en œuvre des fonctionnalités comme l’annulation, le rétablissement et la collaboration.

Commandes

La plupart des opérations d’Univer sont enregistrées dans le système de commandes et déclenchées par son intermédiaire. Cette approche unifiée des opérations permet à Univer de mettre facilement en œuvre des fonctionnalités comme l’annulation, le rétablissement et la collaboration.

Écoute des commandes

Univer permet d’écouter les commandes de deux façons : avant leur exécution et après leur exécution :

• Event.BeforeCommandExecute : exécute une logique personnalisée avant l’exécution de la commande.
• Event.CommandExecuted : exécute une logique personnalisée après l’exécution de la commande.

Écoute des commandes avant leur exécution

Avant l’exécution, transmettez Event.BeforeCommandExecute à FUniver.addEvent pour enregistrer un écouteur de prétraitement.

Lorsque la commande est exécutée, la logique contenue dans l’écouteur de prétraitement s’exécute.

const univerAPI = FUniver.newAPI(univer)univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, ({ id, type, params }) => {  // Custom logic executed before the command is executed})

Pour empêcher l’exécution d’une commande, définissez event.cancel sur true dans la fonction de rappel.

const univerAPI = FUniver.newAPI(univer)univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, (event) => {  event.cancel = true})

Écoute des commandes après leur exécution

Après l’exécution, transmettez Event.CommandExecuted à FUniver.addEvent pour enregistrer un écouteur de post-traitement.

Lorsque la commande est exécutée, la logique contenue dans l’écouteur de post-traitement s’exécute.

const univerAPI = FUniver.newAPI(univer)univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id, type, params }) => {  // Custom logic executed after the command is executed})

Arrêt de l’écoute

La méthode qui enregistre un écouteur de commande renvoie un objet IDisposable, que vous pouvez détruire en appelant IDisposable.dispose.

Il est recommandé de détruire les écouteurs qui ne sont plus utilisés afin d’améliorer la robustesse de votre programme.

const univerAPI = FUniver.newAPI(univer)// Register a listenerconst disposable = univerAPI.addEvent(univerAPI.Event.BeforeCommandExecute, () => {  // custom preprocessing logic before the command is executed})// Example: Destroy the listener after 1 secondsetTimeout(() => {  // Destroy the listener  disposable.dispose()}, 1000)

Exécution de commandes

Si vous connaissez déjà l’ID de la commande et les paramètres à transmettre, vous pouvez aussi exécuter la commande à l’aide de la méthode FUniver.executeCommand.

Par exemple, vous pouvez définir la valeur de la cellule A1 à l’aide de la commande sheet.command.set-range-values :

const univerAPI = FUniver.newAPI(univer)// Execute the commanduniverAPI.executeCommand('sheet.command.set-range-values', {  value: { v: 'Hello, Univer!' },  range: { startRow: 0, startColumn: 0, endRow: 0, endColumn: 0 },})

API des événements

Univer propose un système d’événements complet qui permet d’écouter les différentes modifications d’une feuille de calcul et d’y réagir. Les événements se répartissent en plusieurs grandes catégories, notamment les opérations du presse-papiers, les changements de sélection, les interactions avec les cellules et les modifications apportées aux feuilles.

Catégories d’événements

Liste complète des événements : /reference/facade/events

1. Événements du presse-papiers

   • BeforeClipboardChange : déclenché avant la modification du contenu du presse-papiers ; permet d’empêcher la modification en définissant params.cancel = true
   • BeforeClipboardPaste : déclenché avant le collage du contenu ; permet d’empêcher le collage en définissant params.cancel = true
   • ClipboardChanged : déclenché après la modification du contenu du presse-papiers ; fournit son nouveau contenu
   • ClipboardPasted : déclenché après le collage du contenu ; fournit le contenu collé

2. Événements de sélection

   • SelectionChanged : déclenché lorsque la sélection change ; fournit les informations sur la nouvelle plage sélectionnée
   • SelectionMoveStart : déclenché au début du déplacement de la sélection ; utile pour créer des effets de sélection personnalisés
   • SelectionMoveEnd : déclenché à la fin du déplacement de la sélection ; fournit la plage sélectionnée finale
   • SelectionMoving : déclenché pendant le déplacement de la sélection ; utile pour mettre à jour l’interface utilisateur en temps réel
   • DragOver : déclenché lors d’un glissement au-dessus des cellules
   • Drop : déclenché lorsque le contenu sélectionné est déposé

3. Événements de cellule

   • CellClicked : déclenché lorsqu’on clique sur une cellule ; fournit sa position et des informations sur son contenu
   • CellHover : déclenché lors du survol d’une cellule ; utile pour afficher des infobulles
   • CellPointerDown : déclenché lorsque le pointeur est enfoncé sur une cellule ; sert à lancer une opération de glissement ou de sélection
   • CellPointerUp : déclenché lorsque le pointeur est relâché sur une cellule ; sert à terminer une opération
   • CellPointerMove : déclenché lorsque le pointeur se déplace au-dessus des cellules

4. Événements de feuille

   • SheetValueChanged : déclenché lorsque les valeurs de la feuille changent ; fournit la plage modifiée et les nouvelles valeurs
   • SheetZoomChanged : déclenché lorsque le niveau de zoom change ; fournit le nouveau facteur de zoom
   • SheetSkeletonChanged : déclenché lorsque la structure de la feuille change, par exemple lors de l’insertion ou de la suppression de lignes ou de colonnes
   • BeforeSheetEditStart : déclenché avant le début de la modification d’une cellule ; permet de contrôler si la modification est autorisée
   • SheetEditStarted : déclenché au début de la modification d’une cellule ; utile pour personnaliser le comportement de l’éditeur
   • BeforeSheetEditEnd : déclenché avant la fin de la modification d’une cellule ; peut servir à valider le contenu
   • SheetEditEnded : déclenché à la fin de la modification d’une cellule ; fournit la valeur modifiée
   • SheetEditChanging : déclenché pendant la modification d’une cellule ; utile pour la validation ou la mise en forme en temps réel
   • Scroll : déclenché lors du défilement de la feuille ; fournit des informations sur la position de défilement
   • CrosshairHighlightColorChanged : déclenché lorsque la couleur de mise en évidence du réticule change
   • CrosshairHighlightEnabledChanged : déclenché lorsque la mise en évidence du réticule est activée ou désactivée

5. Événements d’en-tête

   • RowHeaderClick : déclenché lorsqu’on clique sur un en-tête de ligne
   • RowHeaderHover : déclenché lors du survol d’un en-tête de ligne
   • ColumnHeaderClick : déclenché lorsqu’on clique sur un en-tête de colonne
   • ColumnHeaderHover : déclenché lors du survol d’un en-tête de colonne

6. Événements de validation des données

   • BeforeSheetDataValidationAdd : déclenché avant l’ajout d’une règle de validation des données
   • SheetDataValidationChanged : déclenché lorsque les règles de validation des données changent
   • SheetDataValidatorStatusChanged : déclenché lorsque l’état de validation des données change

7. Événements de commentaire

   • BeforeCommentAdd : déclenché avant l’ajout d’un commentaire
   • CommentAdded : déclenché après l’ajout d’un commentaire
   • BeforeCommentUpdate : déclenché avant la mise à jour d’un commentaire
   • CommentUpdated : déclenché après la mise à jour d’un commentaire
   • BeforeCommentDeleted : déclenché avant la suppression d’un commentaire
   • CommentDeleted : déclenché après la suppression d’un commentaire

8. Événements de traitement des données

   • SheetBeforeRangeSort : déclenché avant le tri d’une plage
   • SheetRangeSorted : déclenché après le tri d’une plage
   • SheetBeforeRangeFilter : déclenché avant le filtrage d’une plage
   • SheetRangeFiltered : déclenché après le filtrage d’une plage
   • BeforePivotTableAdd : déclenché avant l’ajout d’un tableau croisé dynamique
   • PivotTableAdded : déclenché après l’ajout d’un tableau croisé dynamique

Utilisation des événements

Vous pouvez écouter les événements avec la méthode addEvent de univerAPI. Voici le modèle de base :

univerAPI.addEvent(univerAPI.Event.EventName, (params) => {  // Handle event parameters})

Exemple : écouter les clics sur les cellules

univerAPI.addEvent(univerAPI.Event.CellClicked, (params) => {  const { worksheet, workbook, row, column } = params  console.log(`Cell clicked at row ${row}, column ${column}`)})

Exemple : surveiller les opérations du presse-papiers

univerAPI.addEvent(univerAPI.Event.BeforeClipboardPaste, (params) => {  const { text, html } = params  // If you want to cancel the clipboard paste  params.cancel = true})

Exemple : suivre les changements de sélection

univerAPI.addEvent(univerAPI.Event.SelectionChanged, (params) => {  const { worksheet, workbook, selections } = params  console.log('Selection changed:', selections)})

Suppression des écouteurs d’événements

Les écouteurs d’événements renvoient un objet IDisposable qui permet de supprimer l’écouteur lorsqu’il n’est plus nécessaire :

const disposable = univerAPI.addEvent(univerAPI.Event.SheetValueChanged, (params) => {  // Handle value changes})// Later, when you want to remove the listener:disposable.dispose()

Bonnes pratiques

1. Supprimez toujours les écouteurs d’événements lorsqu’ils ne sont plus nécessaires afin d’éviter les fuites de mémoire
2. Utilisez l’événement adapté à votre cas d’usage : privilégiez les événements spécifiques aux événements généraux
3. Veillez à ce que les gestionnaires d’événements restent légers pour préserver les performances
4. Envisagez d’utiliser BeforeClipboardChange et les événements « avant » similaires lorsque vous devez empêcher le comportement par défaut

Annulation et rétablissement

Annuler

await univerAPI.undo()

Rétablir

await univerAPI.redo()

Presse-papiers système

Les méthodes FUniver.copy() et FUniver.paste() permettent de lire et d’écrire dans le presse-papiers système.

Exemple : copier-coller dans une plage de feuille

// Prevent failure due to loss of focus when executing copy and paste code in the console,// this example listens for the cell click event and executes the copy and paste code.univerAPI.addEvent(univerAPI.Event.CellClicked, async (params) => {  const fWorkbook = univerAPI.getActiveWorkbook()  const fWorksheet = fWorkbook.getActiveSheet()  // Copy the range A1:B2 to the clipboard  const fRange = fWorksheet.getRange('A1:B2')  fRange.activate().setValues([    [1, 2],    [3, 4],  ])  await univerAPI.copy()  // Paste the copied content to the range C1:D2  const fRange2 = fWorksheet.getRange('C1')  fRange2.activate()  await univerAPI.paste()  // Check the pasted content  console.log(fWorksheet.getRange('C1:D2').getValues()) // [[1, 2], [3, 4]]})

Vous pouvez également appeler les fonctionnalités du presse-papiers par l’intermédiaire du système de commandes :

import { CopyCommand, PasteCommand } from '@univerjs/ui'// CopyuniverAPI.executeCommand(CopyCommand.id)// PasteuniverAPI.executeCommand(PasteCommand.id)

Interface utilisateur

Pour étendre l’interface utilisateur d’Univer, consultez la documentation suivante :

• Extension du canevas

WebSocket

L’API Facade propose une méthode pratique, createSocket, qui permet de créer un WebSocket à partir d’une URL. Vous pouvez ensuite écouter les événements d’ouverture, de message, de fermeture et d’erreur, mais aussi envoyer activement des messages avec la méthode send et fermer la connexion avec la méthode close.

Avec l’installation par Presets, utilisez directement univerAPI.createSocket(url). Avec une installation à la carte, vous devez installer le paquet de dépendances @univerjs/network et enregistrer le plugin UniverNetworkPlugin.

// ... Omits other plugin importsimport { UniverNetworkPlugin } from '@univerjs/network'// ... Omits other facade importsimport '@univerjs/network/facade'// ... Omits other plugin registrationsuniver.registerPlugin(UniverNetworkPlugin)

Voici un exemple simple :

// Replace the URL with the address of your own WebSocket serviceconst ws = univerAPI.createSocket('ws://47.100.177.253:8449/ws')ws.open$.subscribe(() => {  console.log('websocket opened')  ws.send('hello')})ws.message$.subscribe((message) => {  console.log('websocket message', message)  const content = JSON.parse(message.data).content  if (!content.includes('command')) {    return  }  const commandInfo = JSON.parse(content)  const { command, options } = commandInfo  const { id, params } = command  // Upon receiving collaborative data, it is locally saved  univerAPI.executeCommand(id, params, options)})ws.close$.subscribe(() => {  console.log('websocket closed')})ws.error$.subscribe((error) => {  console.log('websocket error', error)})univerAPI.addEvent(univerAPI.Event.CommandExecuted, ({ id, type, params, options }) => {  // Only synchronize local mutations  if (    type !== univerAPI.Enum.CommandType.MUTATION ||    options?.fromCollab ||    options?.onlyLocal ||    id === 'doc.mutation.rich-text-editing'  ) {    return  }  const commandInfo = JSON.stringify({ command: { id, type, params }, options: { fromCollab: true } })  ws.send(commandInfo)})

Remarque : veillez à définir un unitID au démarrage d’Univer. Sans unitID, la collaboration ne fonctionnera pas.

Enregistrement d’une formule

Avec l’API Facade, vous pouvez enregistrer rapidement et facilement des formules personnalisées dans l’instance Univer actuelle.

Dans l’exemple suivant, utilisez registerFunction pour enregistrer en une seule fois dans le plugin de formule l’algorithme, le nom et la description nécessaires à une formule CUSTOMSUM. Une fois l’opération terminée, la formule peut être utilisée. Saisissez =CUSTOMSUM dans une cellule vide pour afficher la suggestion.

// Registered formulas support lambda functionsconst formulaEngine = univerAPI.getFormula()formulaEngine.registerFunction(  'CUSTOMSUM',  (...variants) => {    let sum = 0    const last = variants[variants.length - 1]    if (last.isLambda && last.isLambda()) {      variants.pop()      const variantsList = variants.map((variant) => (Array.isArray(variant) ? variant[0][0] : variant))      sum += last.executeCustom(...variantsList).getValue()    }    for (const variant of variants) {      sum += Number(variant) || 0    }    return sum  },  'Adds its arguments',)// Use the function in a cellconst fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const cellA1 = fWorksheet.getRange('A1')cellA1.setValue(1)const cellA2 = fWorksheet.getRange('A2')cellA2.setValue(2)const cellA3 = fWorksheet.getRange('A3')cellA3.setValue({ f: '=CUSTOMSUM(A1,A2,LAMBDA(x,y,x*y))' })// A3 will display: 5formulaEngine.calculationEnd((functionsExecutedState) => {  if (functionsExecutedState === 3) {    console.log(cellA3.getValue()) // 5  }})

Pour désenregistrer la formule, vous pouvez appeler la méthode dispose.

const functionDisposable = formulaEngine.registerFunction({  // calculate})// Unregister the functionfunctionDisposable.dispose()

Pour proposer un contenu et une description multilingues plus complets, vous pouvez également configurer les champs locales et description, comme dans l’exemple suivant.

formulaEngine.registerFunction(  'CUSTOMSUM',  (...variants) => {    let sum = 0    const last = variants[variants.length - 1]    if (last.isLambda && last.isLambda()) {      variants.pop()      const variantsList = variants.map((variant) => (Array.isArray(variant) ? variant[0][0] : variant))      sum += last.executeCustom(...variantsList).getValue()    }    for (const variant of variants) {      sum += Number(variant) || 0    }    return sum  },  {    description: {      functionName: 'CUSTOMSUM',      description: 'formulaCustom.CUSTOMSUM.description',      abstract: 'formulaCustom.CUSTOMSUM.abstract',      functionParameter: [        {          name: 'formulaCustom.CUSTOMSUM.functionParameter.number1.name',          detail: 'formulaCustom.CUSTOMSUM.functionParameter.number1.detail',          example: 'A1:A20',          require: 1,          repeat: 0,        },        {          name: 'formulaCustom.CUSTOMSUM.functionParameter.number2.name',          detail: 'formulaCustom.CUSTOMSUM.functionParameter.number2.detail',          example: 'B2:B10',          require: 0,          repeat: 1,        },      ],    },    locales: {      zhCN: {        formulaCustom: {          CUSTOMSUM: {            description: '将单个值、单元格引用或是区域相加，或者将三者的组合相加。',            abstract: '求参数的和',            functionParameter: {              number1: {                name: '数值1',                detail:                  '要相加的第一个数字。 该数字可以是 4 之类的数字，B6 之类的单元格引用或 B2:B8 之类的单元格范围。',              },              number2: {                name: '数值2',                detail: '这是要相加的第二个数字。 可以按照这种方式最多指定 255 个数字。',              },            },          },        },      },      enUS: {        formulaCustom: {          CUSTOMSUM: {            description: `You can add individual values, cell references or ranges or a mix of all three.`,            abstract: `Adds its arguments`,            functionParameter: {              number1: {                name: 'number1',                detail:                  'The first number you want to add. The number can be like 4, a cell reference like B6, or a cell range like B2:B8.',              },              number2: {                name: 'number2',                detail: 'This is the second number you want to add. You can specify up to 255 numbers in this way.',              },            },          },        },      },    },  },)

Remarque

• func définit l’algorithme précis et la correspondance de nom de la formule de calcul. Le paramètre d’entrée correspond au contenu saisi par l’utilisateur lorsqu’il emploie la formule ; il peut s’agir d’un nombre, d’une chaîne, d’une valeur booléenne ou d’un tableau.
• description définit la description de la formule personnalisée.
• Plusieurs langues peuvent être définies sous locales. Pour les règles de nommage, consultez LocaleType. Les traductions de plusieurs formules peuvent être ajoutées sous functionList. Pour une description détaillée des champs, consultez la section Ajouter des formules au moteur de formules.

API des énumérations

L’API Facade fournit des types d’énumération courants que vous pouvez utiliser pendant le développement. Par exemple :

console.log(univerAPI.Enum)console.log(univerAPI.Enum.UniverInstanceType.UNIVER_SHEET)console.log(univerAPI.Enum.LifecycleStages.Rendered)

API des méthodes utilitaires

L’API Facade fournit des méthodes utilitaires courantes que vous pouvez utiliser pendant le développement. Par exemple :

console.log(univerAPI.Util)console.log(univerAPI.Util.tools.chatAtABC(10))console.log(univerAPI.Util.tools.ABCatNum('K'))