插件与 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.