Плагины и расширения Facade

Собирайте функции и расширяйте контент и интерфейс через публичные API.

Univer строит продукты и функции из плагинов и раскрывает операции с контентом через API Facade.Приложение выбирает движок контента, функции и пользовательский интерфейс, который ему нужен, или упаковывает свою собственную бизнес-логику в качестве плагина и предоставляет типизированные методы для приложения и инструментов Агента для вызова.

Сборка необходимых возможностей работы с контентом

Предустановка представляет собой предварительно собранную коллекцию плагинов, предназначенных для быстрого запуска. В режиме плагина хост явно выбирает продукты, функции и конфигурацию. Оба режима используют один и тот же механизм плагина.

УровеньОтветственностьТипичные компоненты
Продукты и модели контентаУправление Unit, структурами и базовыми операциями.Плагины Sheet, Doc, Slide, Relational Table, Canvases и PDF.
Функциональные плагиныВозможности определённой предметной области.Формулы, фильтры, диаграммы, комментарии и другое.
Плагины UI и рендерингаОтображение и точки взаимодействия.Canvas, меню, панели инструментов, сочетания клавиш и компоненты.
Расширения FacadeПубличные API установленных возможностей.Операции с книгами, диапазонами, документами и объектами, семантические события.

Отделение логики продукта от пользовательского интерфейса позволяет соответствующим возможностям контента работать в Node.js, в Workers или в браузере.Хозяин без головы регистрирует только необходимые ему плагины контента, в то время как меню, DOM и API взаимодействия по-прежнему требуют своей среды пользовательского интерфейсов.

Зависимости, жизненный цикл и владение ресурсами

Плагин объявляет о своих прямых зависимостях с @DependentOn(...), а время выполнения разрешает их и определяет порядок построения. Когда плагин зависимости отсутствует, время выполнения регистрирует его с конфигурацией по умолчанию. Когда зависимость требует пользовательской конфигурации, регистрируйте и настраивайте ее сначала. Этот механизм не устанавливает пакеты, и он не импортирует стили, локализации, записи Facade или Рабочие.

Внутри плагина инъекция зависимостей (DI) соединяет службы, контроллеры и модели через идентификаторы государственных услуг. Реализации платформы могут быть заменены на поддерживаемых конфигурациях или границах инъекций, поэтому бизнес-логике не нужно создавать и управлять каждой зависимостью самостоятельно.

ЭтапПодходящая работа
onStarting()Регистрация зависимостей, команд и контроллеров; нельзя обращаться к ещё не созданным Unit или DOM.
onReady()Инициализируйте логику, которая зависит от модели, как только соответствующий контент будет готов.
onRendered()Инициализация расширений, которым нужны рендерер, Canvas или DOM.
onSteady()Отсрочка работы, которая не требует первоначального рендеринга.

Владелец управляет регистрацией команд, подписками на события, ярлыками и модулями рендеринга. Когда регистрация возвращает одноразовый, позвоните disposeWithMe(), чтобы он был выпущен вместе с плагином или контроллером. mergeMenu() в настоящее время возвращает void и поэтому не является одноразовым.

Разные точки входа, единый механизм изменения контента

Панель инструментов, ярлык и бизнес-интерфейс API могут вызывать одну и ту же бизнес-командную команду. Хост-агент может повторно использовать эту точку входа после установки требуемых возможностей. Система команд отделяет бизнес-намерение, постоянные изменения и временное взаимодействие.

ТипОтветственностьПример
COMMANDПроверка цели и организация бизнес-шагов, Mutation или Operation.Создание отчёта о продажах, удаление строки.
MUTATIONИзмените модель контента с помощью явных, сериализуемых параметров, чтобы изменения могли воспроизводиться и обрабатываться совместно.Изменение ячеек, вставка строки.
OPERATIONИзменение временного состояния взаимодействия.Выделение, прокрутка, состояние панели.
100%

Например, FRange.setValues() вызывает SetRangeValuesCommand, который производит SetRangeValuesMutation и подготавливает данные отмены. Все изменения содержимого следуют по одному и тому же пути выполнения, поэтому разные точки входа повторно используют существующие проверки, перехватчики и обработку изменений. Отмена, сотрудничество и история на диаграмме по-прежнему зависят от их соответствующих механизмов; регистрация одной только Мутации не обеспечивает их.

Публикация возможностей плагина через Facade API

Facade предоставляет общедоступные интерфейсы, ориентированные на объекты контента, и скрывает внутренние поиски служб и сборку параметров команд.Расширение может составлять существующие методы Facade или вызывать собственную бизнес-командную команду плагина.

Следующее расширение добавляет generateSalesReport() в FUniver; бизнес-команды, которые он вызывает, реализованы в следующем разделе.Файл имеет три части: метод выполнения, регистрация во время выполнения и типы 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() устанавливает метод во время выполнения, а добавление модулей только поставляет типы. Потребители должны выполнять файл расширения через импорт побочных эффектов; экспорт класса или регистрация плагина не выполняет отдельную запись Facade. Опубликованный пакет может раскрыть выделенный субпат /facade и сохранить этот побочный эффект регистрации через package.json#sideEffects.

Эта модель применима только к классам Фасада, которые явно поддерживают extend(). Тот факт, что класс Фасада экспортируется, не означает, что он может служить мишенью для смешивания. Названия методов должны четко указывать их бизнес-смысл и не должны сталкиваться с существующими методами или другими расширениями.

Пример: один отчёт о продажах для приложения и Agent

Этот минимальный бизнес-плагин записывает данные о продажах на английском языке, формулы резюме и стили заголовков в A1:D5 указанного листа и заменяет этот диапазон. Идентификатор книги и идентификатор рабочего листа передаются явно абонентом, а не взяты из текущего выбора или фокуса.

Команда сначала проверяет цель и размеры диапазона, затем вызывает существующий SetRangeValuesCommand так, что его логика изменения контента и отмены / повторения повторно используется. Плагин регистрирует команду в onStarting() и владеет ее одноразовой. Данные фиксируются и служат только иллюстрацией; приложение должно заменить его проверенным бизнес-вводом.

Цвета представления, форматирование чисел, размеры строк и столбцов были скорректированы с учетом читаемости.

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

Настройка продуктов и возможностей формулы с помощью Руководство по установке листов, затем регистрация бизнес-плагина, импорт его расширения Facade и вызов его. В этом примере univer является экземпляром с этой конфигурацией, которая уже завершена. Для конфигурации Node.js см. 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

Успешный результат команды указывает на то, что запись содержимого завершена. Ждите, пока результаты вычисления будут применены до считывания значений формул. В этом примере D5 является 719000.

Кнопка приложения может вызывать generateSalesReport(target) из своего обработчика кликов. Обработчик инструмента Agent может вызывать тот же метод после того, как его хост Headless устанавливает тот же плагин и расширение Facade. Деловое действие и цель остаются теми же; пользовательский интерфейс обеспечивает точку входа и обратную связь. Установка пользовательского плагина не автоматически раскрывает метод в качестве инструмента Agent. Регистрация инструмента и авторизация блока остаются ответственностью приложения.

Границы реализации и дополнительные материалы

  • В этом примере повторно используется SetRangeValuesCommand. Новая Мутация требует обратных операций и соответствующей интеграции совместной работы. Новый постоянный ресурс также требует сериализации, поэтому не записывайте непосредственно в базовую модель.
  • Выполнение, вычисление и представление являются отдельными шагами, а множественные вызовы Facade не образуют автоматическую атомную транзакцию.Этот пример выполняет запись одного диапазона; коллаборативный хост по-прежнему отправляет и подтверждает изменения в соответствии с контрактом Runtime.
  • Составляйте плагины в соответствии с средой, в которой они работают. Устанавливайте плагины контента и плагины пользовательского интерфейса отдельно, сохраняйте пакеты выпуска Univer в одной и той же версии и используйте локальные ресурсы для копирования пользовательского интерфейсов. Точки входа агента по-прежнему требуют авторизации и проверки параметров, принадлежащих приложению.

Подробнее: Архитектура Univer · Подключение Facade · Справочник Facade · Настройка UI · Agent и автоматизация

Вернуться к обзору функций

Насколько полезно это руководство?

© 2026 DreamNum Co., Ltd.