Plugins et extensions Facade
Composez les fonctionnalités et étendez contenu et interfaces avec les API publiques.
Univer construit des produits et des fonctionnalités à partir de plugins et expose les opérations de contenu à travers les API Facade. Une application choisit le moteur de contenu, les fonctionnalités et l'interface utilisateur dont elle a besoin, ou emballe sa propre logique d'affaires comme un plugin et fournit des méthodes dactylographiées pour l'application et les outils Agent à appeler.
Composer les capacités de contenu nécessaires
Un Preset est une collection pré-assemblée de plugins destinés à un démarrage rapide. En mode Plugin, l'hôte sélectionne les produits, les fonctionnalités et la configuration explicitement. Les deux modes utilisent le même mécanisme plugin.
| Couche | Responsabilité | Éléments habituels |
|---|---|---|
| Produits et modèles de contenu | Gérer les Units, structures et opérations fondamentales. | Plugins produit de Sheet, Doc, Slide, Relational Table, Canvases et PDF. |
| Plugins fonctionnels | Ajouter des capacités propres à un domaine. | Formules, filtres, graphiques, commentaires, etc. |
| Plugins d’interface et de rendu | Fournir l’affichage et les points d’interaction. | Canvas, menus, barres d’outils, raccourcis et composants. |
| Extensions Facade | Exposer des API publiques pour les capacités installées. | Opérations sur classeurs, plages, documents et objets, ainsi que des événements sémantiques. |
La séparation de la logique de produit de l'interface utilisateur permet de réaliser des fonctionnalités de contenu appropriées dans Node.js, dans Workers ou dans le navigateur. Un hôte Headless enregistre seulement les plugins de contenu dont il a besoin, tandis que les menus, DOM et les API d'interactions nécessitent toujours leur environnement d'interface utilisateur.
Dépendances, cycle de vie et propriété des ressources
Un plugin déclare ses dépendances directes avec @DependentOn(...), et l'exécution les résout et détermine l'ordre de construction. Lorsqu'un plugin de dépendance est manquant, l'exécution l'enregistre avec la configuration par défaut. Lorsqu'une dépendance nécessite une configuration personnalisée, enregistrez-la et configurez-la d'abord. Ce mécanisme n'installe pas de paquets, et il n'importe pas les styles, les localisations, les entrées Facade ou les travailleurs.
À l'intérieur d'un plugin, l'injection de dépendance (DI) connecte les services, les contrôleurs et les modèles par des identifiants de service public. Les implémentations de plate-forme peuvent être remplacées aux limites de configuration ou d'injection supportées, de sorte que la logique d'entreprise n'a pas besoin de construire et de gérer chaque dépendance elle-même.
| Cycle de vie | Travail approprié |
|---|---|
onStarting() | Enregistrer dépendances, commandes et contrôleurs ; ne pas lire des Units ou du DOM encore inexistants. |
onReady() | Initialiser la logique qui dépend du modèle une fois le contenu correspondant prêt. |
onRendered() | Initialiser les extensions ayant besoin du moteur de rendu, de Canvas ou du DOM. |
onSteady() | Reportez le travail que le rendu initial n'exige pas. |
Le propriétaire gère les enregistrements de commandes, les abonnements d'événements, les raccourcis et les modules de rendu. Lorsqu'un enregistrement retourne un jetable, appelez disposeWithMe() afin qu'il soit libéré avec le plugin ou le contrôleur. mergeMenu() retourne actuellement void et n'est donc pas jetable.
Des entrées différentes, un même mécanisme de modification
Une barre d'outils, un raccourci et une API d'affaires peuvent invoquer la même commande d'affaires. Un hôte Agent peut réutiliser ce point d'entrée après l'installation des capacités requises. Le système de commande sépare l'intention d'entreprise, les changements persistants et les interactions transitoires.
| Type | Responsabilité | Exemple |
|---|---|---|
COMMAND | Valider les cibles et orchestrer étapes métier, Mutations ou Operations. | Écrire un rapport de ventes ou supprimer une ligne. |
MUTATION | Changer le modèle de contenu par des paramètres explicites et sérialisables afin que le changement puisse être rejoué et géré par la collaboration. | Modifier des cellules ou insérer une ligne. |
OPERATION | Modifier l’état d’interaction temporaire. | Changer sélection, défilement ou panneau. |
Par exemple, FRange.setValues() invoque SetRangeValuesCommand, qui produit un SetRangeValuesMutation et prépare les données de désactivation. Tous les changements de contenu suivent le même chemin d'exécution, de sorte que différents points d'entrée réutilisent la validation existante, les intercepteurs et la manipulation des changements. L'annulation, la collaboration et l'historique dans le diagramme dépendent toujours de leurs mécanismes respectifs; l'enregistrement d'une Mutation seule ne les fournit pas.
Exposer les capacités d’un plugin par Facade
Facade fournit des interfaces publiques orientées vers les objets de contenu et cache les recherche de service interne et l'assemblage de paramètres de commande. Une extension peut composer des méthodes Facade existantes ou invoquer la propre commande d'affaires du plugin.
L'extension suivante ajoute generateSalesReport() à FUniver ; la commande d'affaires qu'elle invoque est implémentée dans la section suivante. Le fichier comporte trois parties : la méthode d'exécution, l'enregistrement d'exécution et les types TypeScript.
sales-report.facade.ts
import { FUniver } from '@univerjs/core/facade';import type { ISalesReportParams } from './sales-report.plugin';import { GenerateSalesReportCommand } from './sales-report.plugin';export interface IFUniverSalesReport { generateSalesReport(params: ISalesReportParams): Promise<boolean>;}export class FUniverSalesReport extends FUniver implements IFUniverSalesReport { override generateSalesReport(params: ISalesReportParams): Promise<boolean> { return this._commandService.executeCommand(GenerateSalesReportCommand.id, params); }}FUniver.extend(FUniverSalesReport);declare module '@univerjs/core/facade' { interface FUniver extends IFUniverSalesReport {}}FUniver.extend() installe la méthode à l'exécution, et l'augmentation de module ne fournit que des types. Les consommateurs doivent exécuter le fichier d'extension à travers une importation d'effets secondaires; l'exportation de la classe ou l'enregistrement d'un plugin n'exécute pas une entrée Facade séparée. Un paquet publié peut exposer un sous-path /facade dédié et préserver cet effet secondaire d'enregistrement via package.json#sideEffects.
Ce modèle ne s'applique qu'aux classes Facade qui prennent explicitement en charge extend(). Le fait qu'une classe Facade soit exportée ne signifie pas qu'elle peut servir de cible de mixin. Les noms de méthode doivent indiquer clairement leur sens commercial et ne pas entrer en conflit avec les méthodes existantes ou d'autres extensions.
Exemple : un même rapport de ventes pour l’application et les Agents
Ce plugin d'affaires minimal écrit des données de vente en anglais, des formules sommaires et des styles d'en-tête dans A1:D5 de la feuille spécifiée et remplace cette plage. L'ID du cahier de travail et l'ID de la feuille de travail sont passés explicitement par l'appelant plutôt que pris de la sélection ou de la mise au point actuelle.
La commande vérifie d'abord la cible et les dimensions de la plage, puis invoque la SetRangeValuesCommand existante afin que sa logique de changement de contenu et de désactivation/redo soit réutilisée. Le plugin enregistre la commande dans onStarting() et possède sa joignable. Les données sont fixes et ne servent qu'à illustrer; une application doit la remplacer par une entrée professionnelle validée.
Exemple de sortie. Les couleurs de présentation, le formatage des nombres, et les dimensions de ligne et de colonne ont été ajustés pour la lisibilité.
sales-report.plugin.ts
import type { ICellData, ICommand, Workbook } from '@univerjs/core';import { CommandType, DependentOn, ICommandService, Inject, Injector, IUniverInstanceService, Plugin, UniverInstanceType,} from '@univerjs/core';import { SetRangeValuesCommand, UniverSheetsPlugin } from '@univerjs/sheets';export interface ISalesReportParams { unitId: string; subUnitId: string;}export const GenerateSalesReportCommand: ICommand<ISalesReportParams> = { id: 'sales-report.command.generate', type: CommandType.COMMAND, handler: (accessor, params) => { if (!params) return false; const sheet = accessor.get(IUniverInstanceService) .getUnit<Workbook>(params.unitId, UniverInstanceType.UNIVER_SHEET) ?.getSheetBySheetId(params.subUnitId); if (!sheet || sheet.getRowCount() < 5 || sheet.getColumnCount() < 4) return false; const value: ICellData[][] = [ ['Region', 'Q1', 'Q2', 'H1 Total'].map((v) => ({ v, t: 1, s: { bg: { rgb: '#17324D' }, cl: { rgb: '#FFFFFF' }, bl: 1 }, })), [{ v: 'East', t: 1 }, { v: 128000, t: 2 }, { v: 142000, t: 2 }, { f: '=SUM(B2:C2)' }], [{ v: 'West', t: 1 }, { v: 96000, t: 2 }, { v: 118000, t: 2 }, { f: '=SUM(B3:C3)' }], [{ v: 'North', t: 1 }, { v: 110000, t: 2 }, { v: 125000, t: 2 }, { f: '=SUM(B4:C4)' }], [{ v: 'Total', t: 1 }, { f: '=SUM(B2:B4)' }, { f: '=SUM(C2:C4)' }, { f: '=SUM(D2:D4)' }], ]; return accessor.get(ICommandService).executeCommand(SetRangeValuesCommand.id, { ...params, range: { startRow: 0, endRow: 4, startColumn: 0, endColumn: 3 }, value, }); },};@DependentOn(UniverSheetsPlugin)export class SalesReportPlugin extends Plugin { static override pluginName = 'SALES_REPORT_PLUGIN'; static override type = UniverInstanceType.UNIVER_SHEET; constructor( _config: undefined, @Inject(Injector) protected override readonly _injector: Injector, @ICommandService private readonly _commands: ICommandService, ) { super(); } override onStarting(): void { this.disposeWithMe(this._commands.registerCommand(GenerateSalesReportCommand)); }}Configurez les capacités des produits et de la formule avec le Guide d'installation de la feuille, puis enregistrez le plugin d'affaires, importez son extension Facade, et appelez-le. Dans cet exemple, univer est une instance avec cette configuration déjà terminée. Pour la configuration Node.js voir headless Univer.
import { FUniver } from '@univerjs/core/facade';import '@univerjs/sheets/facade';import '@univerjs/engine-formula/facade';import { SalesReportPlugin } from './sales-report.plugin';import './sales-report.facade';univer.registerPlugin(SalesReportPlugin);const univerAPI = FUniver.newAPI(univer);const workbook = univerAPI.createWorkbook({ name: 'Quarterly Sales' });const worksheet = workbook.getActiveSheet();const target = { unitId: workbook.getId(), subUnitId: worksheet.getSheetId() };const generated = await univerAPI.generateSalesReport(target);if (!generated) throw new Error('Sales report could not be generated');await univerAPI.getFormula().onCalculationResultApplied();console.log(worksheet.getRange('D5').getValue()); // 719000Un résultat de commande réussi indique que l'écriture du contenu est terminée. Attendez que les résultats de calcul soient appliqués avant de lire les valeurs de la formule. Dans cet exemple, D5 est 719000.
Un bouton d'application peut appeler generateSalesReport(target) à partir de son gestionnaire de clics. Un gestionnaire d'outil Agent peut appeler la même méthode après que son hôte Headless installe le même plugin et l'extension Facade. L'action commerciale et la cible restent les mêmes; l'interface utilisateur fournit le point d'entrée et la rétroaction. L'installation d'un plugin personnalisé n'expose pas automatiquement la méthode en tant qu'outil Agent. L'enregistrement d'outil et l'autorisation d'unité restent la responsabilité de l'application.
Limites d’implémentation et ressources complémentaires
- Cet exemple réutilise
SetRangeValuesCommand. Une nouvelle mutation nécessite des opérations inverses et l'intégration de la collaboration correspondante. Une nouvelle ressource persistante nécessite également une sérialisation, donc ne pas écrire directement au modèle sous-jacent. - L'exécution, le calcul et la soumission sont des étapes distinctes, et plusieurs appels Facade ne forment pas une transaction atomique automatique. Cet exemple effectue une écriture à une seule plage; un hôte collaboratif soumet et confirme encore les changements dans le contrat Runtime.
- Installez les plugins de contenu et les plugins UI séparément, gardez les paquets de formation de version Univer sur la même version, et utilisez les ressources locales pour la copie de l'interface utilisateur. Les points d'entrée d'agent nécessitent toujours l'autorisation et la validation des paramètres appartenant à l'application.
En savoir plus : Architecture Univer · Configuration Facade · Référence Facade · Personnalisation UI · Agents et automatisation
Que pensez-vous de ce guide ?