Plugins y extensiones Facade

Compón funciones y amplía contenido e interfaces mediante APIs públicas.

Univer construye productos y características de plugins y expone las operaciones de contenido a través de Facade APIs. Una aplicación elige el motor de contenido, las características y la interfaz de usuario que necesita, o empaqueta su propia lógica de negocio como plugin y proporciona métodos de tipo para la aplicación y herramientas de agente a llamar.

Componer las capacidades de contenido necesarias

Un Preset es una colección premontada de plugins destinados a un comienzo rápido. En modo Plugin, el host selecciona productos, características y configuración explícitamente. Ambos modos utilizan el mismo mecanismo de plugin.

CapaResponsabilidadComponentes habituales
Productos y modelos de contenidoGestionar Units, estructuras y operaciones básicas.Plugins de producto para Sheet, Doc, Slide, Relational Table, Canvases y PDF.
Plugins de funcionesAñadir capacidades de un ámbito concreto.Fórmulas, filtros, gráficos, comentarios y más.
Plugins de UI y renderizadoProporcionar presentación y puntos de interacción.Canvas, menús, barras de herramientas, atajos y componentes.
Extensiones FacadeExponer API públicas para las capacidades instaladas.Operaciones de libros, rangos, documentos y objetos, y eventos semánticos.

La lógica del producto separada de UI permite que las capacidades de contenido adecuadas se ejecuten en Node.js, en los trabajadores o en el navegador. Un host sin cabeza registra sólo los plugins de contenido que necesita, mientras que los menús, DOM y API de interacción todavía requieren su entorno de interfaz de usuario.

Dependencias, ciclo de vida y propiedad de recursos

Un plugin declara sus dependencias directas con @DependentOn(...), y el tiempo de ejecución los resuelve y determina el orden de construcción. Cuando falta un plugin de dependencia, el tiempo de funcionamiento lo registra con la configuración predeterminada. Cuando una dependencia requiere configuración personalizada, regístrese y configure primero. Este mecanismo no instala paquetes, y no importa estilos, locales, entradas de Facade o Trabajadores.

Dentro de un plugin, la inyección de dependencia (DI) conecta los servicios, controladores y modelos a través de identificadores de servicio público. Las implementaciones de la plataforma pueden ser reemplazadas en configuraciones soportadas o límites de inyección, por lo que la lógica empresarial no necesita construir y gestionar cada dependencia en sí misma.

Ciclo de vidaTrabajo adecuado
onStarting()Registrar dependencias, comandos y controladores; no acceder a Units o DOM aún inexistentes.
onReady()Inicia la lógica que depende del modelo una vez que el contenido correspondiente esté listo.
onRendered()Inicializar extensiones que requieran renderizador, Canvas o DOM.
onSteady()El trabajo de aplazamiento que la renderización inicial no requiere.

El propietario administra registros de comandos, suscripciones de eventos, atajos y módulos de renderización. Cuando un registro devuelve un desechable, llame a disposeWithMe() para que se publique junto con el plugin o controlador. mergeMenu() actualmente devuelve void y por lo tanto no es un desposable.

Distintas entradas, un mecanismo de cambios de contenido

Una barra de herramientas, un atajo y una API de negocio pueden invocar el mismo comando de negocio. Un host de agente puede reutilizar ese punto de entrada después de que se instalan las capacidades requeridas. El sistema de comandos separa la intención de negocio, los cambios persistentes y la interacción transitoria.

TipoResponsabilidadEjemplo
COMMANDValidar destinos y organizar pasos de negocio, Mutations u Operations.Escribir un informe de ventas o eliminar una fila.
MUTATIONCambie el modelo de contenido a través de parámetros explícitos y serializables para que el cambio pueda ser reproducido y manejado por la colaboración.Actualizar celdas o insertar una fila.
OPERATIONModificar el estado de interacción temporal.Cambiar selección, desplazamiento o panel.
100%

Por ejemplo, FRange.setValues() invoca SetRangeValuesCommand, que produce un SetRangeValuesMutation y prepara los datos de deshacer. Todos los cambios de contenido siguen el mismo camino de ejecución, por lo que diferentes puntos de entrada reutilizan la validación existente, los interceptores y el manejo del cambio. Deshacer, la colaboración y la historia en el diagrama todavía dependen de sus respectivos mecanismos; registrar una Mutación por sí solo no los proporciona.

Exponer las capacidades del plugin como API Facade

Facade ofrece interfaces públicas orientadas a objetos de contenido y oculta las búsquedas de servicio interno y el montaje del parámetro de comando. Una extensión puede componer los métodos existentes de Facade o invocar el propio comando de negocio del plugin.

La siguiente extensión añade generateSalesReport() a FUniver; el comando de negocio que invoca se implementa en la siguiente sección. El archivo tiene tres partes: el método de tiempo de ejecución, el registro de plazos de ejecución, y los tipos TypeScript.

sales-report.facade.ts

TypeScript
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() instala el método en tiempo de ejecución, y el aumento de módulos sólo suministra tipos. Los consumidores deben ejecutar el archivo de extensión a través de una importación de efecto secundario; exportar la clase o registrar un plugin no ejecuta una entrada de Facade separada. Un paquete publicado puede exponer un subpath /facade dedicado y preservar ese efecto secundario de registro a través de package.json#sideEffects.

Este patrón se aplica solamente a las clases Facade que apoyan explícitamente extend(). El hecho de que una clase Facade sea exportada no significa que pueda servir como meta de mezcla. Los nombres de los métodos deben indicar su significado de negocio claramente y no debe collide con los métodos existentes u otras extensiones.

Ejemplo: el mismo informe de ventas para aplicaciones y Agents

Este plugin de negocio mínimo escribe datos de ventas en inglés, fórmulas sumarias y estilos de encabezado en A1:D5 de la hoja especificada y reemplaza ese rango. El ID de libro de trabajo y el ID de hoja de trabajo se transmiten explícitamente por el llamante en lugar de tomar de la selección actual o enfoque.

El comando primero comprueba el objetivo y las dimensiones del rango, luego invoca el SetRangeValuesCommand existente para que se reutiliza su lógica de cambio de contenido y deshacer/redo. El plugin registra el comando en onStarting() y posee su desechable. Los datos se fijan y solo sirven como ilustración; una aplicación debe reemplazarlo con entrada de negocio validada.

Ejemplo de salida. Los colores de presentación, el formato de números, y las dimensiones de fila y columna fueron ajustados para legibilidad.

sales-report.plugin.ts

TypeScript
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));  }}

Configure los productos y capacidades de fórmula con el Guía de instalación de hoja de cálculo, a continuación, registre el plugin de negocio, importa su extensión Facade, y llamelo. En este ejemplo, univer es una instancia con esa configuración ya completa. Para la configuración Node.js , vea headless Univer.

TypeScript
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()); // 719000

Un resultado de comando exitoso indica que el contenido ha completado. Espere a que los resultados de cálculo se apliquen antes de leer los valores de fórmula. En este ejemplo, D5 es 719000.

Un botón de aplicación puede llamar a generateSalesReport(target) desde su controlador de clics. Un manejador de herramientas Agent puede llamar el mismo método después de que su host Headless instale el mismo plugin y la extensión Facade. La acción de negocio y el objetivo siguen siendo el mismo; la UI proporciona el punto de entrada y la retroalimentación. Instalar un plugin personalizado no expone automáticamente el método como una herramienta de Agente.

Límites de implementación y lecturas adicionales

  • Este ejemplo reutiliza SetRangeValuesCommand. Una nueva mutación requiere operaciones inversas y la correspondiente integración de la colaboración. Un nuevo recurso persistente también requiere serialización, así que no escriba directamente al modelo subyacente.
  • La ejecución, el cálculo y la presentación son pasos separados, y múltiples llamadas Facade no forman una transacción atómica automática. Este ejemplo realiza un solo rango de escritura; un host colaborativo todavía presenta y confirma cambios bajo el contrato Runtime.
  • Configurar plugins de acuerdo con el entorno en el que se ejecutan. Instalar plugins de contenido y plugins de interfaz de usuario por separado, mantener los paquetes de Univer de la misma versión, y utilizar recursos locales para la copia de la interfaz de usuario. Los puntos de entrada del agente todavía requieren autorización y validación del parámetro propiedad de la aplicación.

Más información: Arquitectura de Univer · Configuración Facade · Referencia Facade · Personalización de UI · Agents y automatización

Volver al resumen de funciones

¿Cómo es esta guía?

© 2026 DreamNum Co., Ltd.