插件与 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 与自动化
你觉得这篇文档如何?