插件與 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 | 修改暫時互動狀態。 | 調整選取範圍、捲動位置或面板。 |
以 FRange.setValues() 為例,它呼叫 SetRangeValuesCommand,該命令生成 SetRangeValuesMutation,並準備撤銷所需的資料。所有內容變更都遵循同一條執行路徑,不同入口複用已有的校驗、攔截和變更處理邏輯。圖中的撤銷、協同和歷史記錄仍然依賴各自的機制;僅註冊一個 Mutation 不會自動獲得這些能力。
將插件能力擴充為 Facade API
Facade 提供面向內容物件的公開介面,並隱藏內部的服務查詢和命令參數組裝。擴充套件可以組合現有的 Facade 方法,也可以呼叫外掛自身的業務命令。
下面的擴充套件為 FUniver 新增 generateSalesReport(),它呼叫的業務命令在下一節實現。該檔案由三部分組成:執行時方法、執行時註冊和 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() 在執行時安裝該方法,模組增強只補充型別。接入方必須透過 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
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。
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 與自動化
你覺得這篇文檔如何?