插件與 Facade 擴充

按需組合功能,以公開 API 擴充內容操作與業務介面。

Univer 透過外掛組合產品與功能,並透過 Facade 將內容操作開放給應用。應用可以選擇所需的內容引擎、功能和介面,也可以把業務邏輯封裝為外掛,為應用和 Agent 工具提供帶型別的方法。

按需組合內容能力

Preset 是預先組合好的外掛集合,用於快速接入。Plugin 模式下,產品、功能和配置均由宿主顯式選擇。兩種方式使用同一套外掛機制。

層次職責典型組成
產品與內容模型管理 Unit、內容結構與基本操作。Sheet、Doc、Slide、Relational Table、Canvases、PDF 的產品插件。
功能插件增加特定領域能力。公式、篩選、圖表、評論等。
UI 與渲染插件提供視覺呈現與互動入口。Canvas 渲染、選單、工具列、快捷鍵與元件。
Facade 擴充為已安裝能力提供公開呼叫介面。活頁簿、範圍、文件和物件操作,以及語意事件。

產品邏輯與 UI 分離,適合的內容能力可以在 Node.js、Worker 或瀏覽器中執行。Headless 宿主只註冊所需的內容外掛;選單、DOM 和互動相關 API 仍然需要對應的 UI 環境。

依賴、生命週期與資源歸屬

外掛透過 @DependentOn(...) 宣告直接依賴,執行時負責解析依賴並確定構造順序。依賴外掛缺失時,執行時會以預設配置註冊該外掛。某個依賴需要自定義配置時,應先註冊並配置該依賴。這一機制不負責安裝包,也不會引入樣式、語言資源、Facade 入口或 Worker。

外掛內部使用依賴注入(DI),透過公開的服務識別符號連線 Service、Controller 和模型。平臺相關實現可在支援的配置或注入邊界處替換,業務邏輯不必自行建立和管理所有依賴。

生命週期適合執行的工作
onStarting()註冊依賴、命令與控制器;不要讀取尚未建立的 Unit 或 DOM。
onReady()在對應內容就緒後,初始化依賴模型的邏輯。
onRendered()初始化需要渲染器、Canvas 或 DOM 的擴充。
onSteady()把首屏渲染不需要的工作延後執行。

命令註冊、事件訂閱、快捷鍵和渲染模組等資源由擁有者管理。註冊呼叫返回 disposable 時,應使用 disposeWithMe(),使資源隨外掛或控制器一起釋放。mergeMenu() 當前返回 void,不能視為 disposable。

不同入口,共用內容變更機制

工具欄、快捷鍵和業務 API 可以呼叫同一個業務命令。Agent 宿主在安裝所需能力後,也可以複用這一入口。命令系統將業務意圖、持久化變更和臨時互動分開處理。

類型職責範例
COMMAND校驗目標、組織業務步驟,並編排 Mutation 或 Operation。寫入銷售報告、刪除資料列。
MUTATION透過明確、可序列化的參數修改內容模型,使變更可以重放並由協同流程處理。修改儲存格內容、插入資料列。
OPERATION修改暫時互動狀態。調整選取範圍、捲動位置或面板。
100%

以 FRange.setValues() 為例,它呼叫 SetRangeValuesCommand,該命令生成 SetRangeValuesMutation,並準備撤銷所需的資料。所有內容變更都遵循同一條執行路徑,不同入口複用已有的校驗、攔截和變更處理邏輯。圖中的撤銷、協同和歷史記錄仍然依賴各自的機制;僅註冊一個 Mutation 不會自動獲得這些能力。

將插件能力擴充為 Facade API

Facade 提供面向內容物件的公開介面,並隱藏內部的服務查詢和命令參數組裝。擴充套件可以組合現有的 Facade 方法,也可以呼叫外掛自身的業務命令。

下面的擴充套件為 FUniver 新增 generateSalesReport(),它呼叫的業務命令在下一節實現。該檔案由三部分組成:執行時方法、執行時註冊和 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() 在執行時安裝該方法,模組增強只補充型別。接入方必須透過 side-effect import 執行擴充套件檔案;僅匯出類或註冊外掛不會執行獨立的 Facade 入口。釋出為包時,可以暴露獨立的 /facade 子路徑,並透過 package.json 的 sideEffects 保留這一註冊副作用。

這種方式僅適用於明確支援 extend() 的 Facade 類。匯出一個 Facade 類並不意味著它可以用作 mixin。方法名應明確表達業務含義,並避免與已有方法或其他擴充套件重名。

案例:讓應用與 Agent 產生同一份銷售報告

這個最小業務外掛將英文銷售資料、彙總公式和表頭樣式寫入指定 Sheet 的 A1:D5,並覆蓋該區域。工作簿 ID 和工作表 ID 由呼叫方顯式傳入,不依賴當前選區或焦點。

命令先校驗目標和區域尺寸,再呼叫現有的 SetRangeValuesCommand,以複用其內容變更和撤銷/重做邏輯。外掛在 onStarting() 中註冊命令,並持有其 disposable。資料為固定值,僅用於演示;實際應用應替換為校驗過的業務輸入。

範例輸出。為便於閱讀,底色、數字格式和行列尺寸經過調整。

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

先按 Sheet 接入指南配置產品和公式能力,再註冊業務外掛、匯入 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 擴充套件後,也可以呼叫同一方法。業務動作和目標保持不變,UI 僅提供入口和反饋。安裝自定義外掛不會自動將其暴露為 Agent 工具。工具註冊和 Unit 授權仍由應用負責。

實作邊界與延伸閱讀

  • 本例複用 SetRangeValuesCommand。新增 Mutation 時,需要設計反向操作和相應的協同整合。新增持久化資源還需要處理序列化,因此不要直接寫入底層模型。
  • 執行、計算和提交是三個獨立步驟,多次 Facade 呼叫不會自動構成原子事務。本例執行一次範圍寫入;協同宿主仍需按照 Runtime 的約定提交併確認變更。
  • 按執行環境組合外掛。內容外掛和 UI 外掛分別安裝,相關的 Univer 包保持同一釋出版本,介面文案使用語言資源。Agent 入口仍然需要應用負責授權和參數校驗。

延伸閱讀:Univer 架構 · Facade 接入 · Facade API 參考 · UI 自訂 · Agent 與自動化

返回功能總覽

你覺得這篇文檔如何?

© 2026 DreamNum Co., Ltd.