univer-pro-integrate

Univer Pro 集成

将 Univer Pro 嵌入现有 Web 应用的指南。Univer Pro 在开源 Univer 的基础上扩展了企业级功能，包括协作、导入/导出、打印、数据透视表、图表、迷你图形状和许可证管理。

兼容性：本技能适用于 Univer Pro v0.20.x。核心概念在各个次要版本间保持稳定，但具体方法签名可能会有变化。请检查用户安装的 @univerjs-pro/* 版本，并优先采用其项目中已有的 API 模式。

先决条件：Univer Pro 需要开源 Univer 核心。应用 Pro 功能前，请参阅 univer-integrate 技能，了解基础集成模式（初始化、Facade API、插件架构）。

快速开始

1. 安装 Pro 依赖

npm install @univerjs-pro/license @univerjs-pro/engine-formula @univerjs-pro/sheets-pivot @univerjs-pro/sheets-pivot-ui @univerjs-pro/sheets-chart @univerjs-pro/sheets-chart-ui @univerjs-pro/sheets-sparkline @univerjs-pro/sheets-sparkline-ui @univerjs-pro/sheets-shape @univerjs-pro/sheets-shape-ui @univerjs-pro/sheets-print @univerjs-pro/exchange-client @univerjs-pro/sheets-exchange-client

用于协作：

npm install @univerjs-pro/collaboration @univerjs-pro/collaboration-client @univerjs-pro/collaboration-client-ui

2. 注册核心 Pro 插件

import { LocaleType, Univer, UniverInstanceType } from '@univerjs/core';
import { FUniver } from '@univerjs/core/facade';
import { UniverRenderEnginePlugin } from '@univerjs/engine-render';
import { UniverUIPlugin } from '@univerjs/ui';
import { UniverSheetsPlugin } from '@univerjs/sheets';
import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui';
import { UniverRPCMainThreadPlugin } from '@univerjs/rpc';
import { defaultTheme } from '@univerjs/themes';

// Pro plugins
import { UniverLicensePlugin } from '@univerjs-pro/license';
import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula';
import { UniverSheetsPivotTablePlugin } from '@univerjs-pro/sheets-pivot';
import { UniverSheetsPivotTableUIPlugin } from '@univerjs-pro/sheets-pivot-ui';
import { UniverSheetsChartPlugin } from '@univerjs-pro/sheets-chart';
import { UniverSheetsChartUIPlugin } from '@univerjs-pro/sheets-chart-ui';
import { UniverSheetSparklinePlugin } from '@univerjs-pro/sheets-sparkline';
import { UniverSheetSparklineUIPlugin } from '@univerjs-pro/sheets-sparkline-ui';
import { UniverSheetsShapePlugin } from '@univerjs-pro/sheets-shape';
import { UniverSheetsShapeUIPlugin } from '@univerjs-pro/sheets-shape-ui';
import { UniverSheetsPrintPlugin } from '@univerjs-pro/sheets-print';
import { UniverExchangeClientPlugin } from '@univerjs-pro/exchange-client';
import { UniverSheetsExchangeClientPlugin } from '@univerjs-pro/sheets-exchange-client';

// Facade side-effect imports (Pro)
import '@univerjs-pro/sheets-pivot/facade';
import '@univerjs-pro/engine-formula/facade';
import '@univerjs-pro/sheets-chart/facade';
import '@univerjs-pro/sheets-sparkline/facade';
import '@univerjs-pro/sheets-shape/facade';
import '@univerjs-pro/sheets-print/facade';
import '@univerjs-pro/exchange-client/facade';

const worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });

const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.ZH_CN,
});

// License first
univer.registerPlugin(UniverLicensePlugin, {
  license: process.env.CLIENT_LICENSE_TEXT, // or your license string
});

univer.registerPlugins([
  [UniverRenderEnginePlugin],
  [UniverProFormulaEnginePlugin, { notExecuteFormula: true }],
  [UniverUIPlugin, { container: 'app' }],
  [UniverRPCMainThreadPlugin, { workerURL: worker }],
  [UniverSheetsPlugin, { notExecuteFormula: true }],
  [UniverSheetsUIPlugin],
  // Pro features
  [UniverSheetsPivotTablePlugin, { notExecuteFormula: true }],
  [UniverSheetsPivotTableUIPlugin],
  [UniverSheetsChartPlugin],
  [UniverSheetsChartUIPlugin],
  [UniverSheetSparklinePlugin],
  [UniverSheetSparklineUIPlugin],
  [UniverSheetsShapePlugin],
  [UniverSheetsShapeUIPlugin],
  [UniverSheetsPrintPlugin],
  [UniverExchangeClientPlugin, {
    uploadFileServerUrl: 'https://your-server/universer-api/stream/file/upload',
    getTaskServerUrl: 'https://your-server/universer-api/exchange/task/{taskID}',
    signUrlServerUrl: 'https://your-server/universer-api/file/{fileID}/sign-url',
    importServerUrl: 'https://your-server/universer-api/exchange/{type}/import',
    exportServerUrl: 'https://your-server/universer-api/exchange/{type}/export',
    downloadEndpointUrl: 'https://your-server/',
  }],
  [UniverSheetsExchangeClientPlugin],
]);

univer.createUnit(UniverInstanceType.UNIVER_SHEET, {});
const univerAPI = FUniver.newAPI(univer);

3. Pro Worker 设置

Pro worker 必须包含 UniverProFormulaEnginePlugin、UniverLicensePlugin 和 UniverSheetsPivotTablePlugin：

// worker.js
import { LocaleType, LogLevel, Univer } from '@univerjs/core';
import { UniverRPCWorkerThreadPlugin } from '@univerjs/rpc';
import { UniverSheetsPlugin } from '@univerjs/sheets';
import { UniverRemoteSheetsFormulaPlugin } from '@univerjs/sheets-formula';
import { UniverSheetsFilterPlugin } from '@univerjs/sheets-filter';

import { UniverLicensePlugin } from '@univerjs-pro/license';
import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula';
import { UniverSheetsPivotTablePlugin } from '@univerjs-pro/sheets-pivot';

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  logLevel: LogLevel.VERBOSE,
});

univer.registerPlugin(UniverLicensePlugin, {
  license: process.env.CLIENT_LICENSE_TEXT,
});
univer.registerPlugin(UniverSheetsPlugin, { onlyRegisterFormulaRelatedMutations: true });
univer.registerPlugin(UniverProFormulaEnginePlugin);
univer.registerPlugin(UniverRPCWorkerThreadPlugin);
univer.registerPlugin(UniverRemoteSheetsFormulaPlugin);
univer.registerPlugin(UniverSheetsFilterPlugin);
univer.registerPlugin(UniverSheetsPivotTablePlugin, { notExecuteFormula: false });

self.univer = univer;

核心概念

优先注册许可证

创建 Univer 实例后，必须立即注册 UniverLicensePlugin，并且要在其他 Pro 插件之前注册。如果没有有效许可证，Pro 功能将以评估模式运行（显示水印、限制规模、限制协作配额）。

Pro 公式引擎

Univer Pro 使用 UniverProFormulaEnginePlugin 替代开源公式引擎。使用 Pro 时，请注册该插件，而不是 UniverFormulaEnginePlugin。它支持数据透视表和服务器端计算所需的高级函数。

插件注册顺序

Pro 集成的顺序如下：

1. UniverLicensePlugin
2. 引擎插件（UniverRenderEnginePlugin、UniverProFormulaEnginePlugin）
3. UI 基础设施（UniverUIPlugin、UniverRPCMainThreadPlugin）
4. 单元核心（UniverSheetsPlugin、UniverDocsPlugin）
5. 单元 UI（UniverSheetsUIPlugin、UniverDocsUIPlugin）
6. Pro 功能（数据透视表、图表、迷你图、形状、打印、交换）
7. 协作功能（如有需要）

版本策略

所有 @univerjs/* 和 @univerjs-pro/* 包必须保持版本一致。切勿混用不同版本——这是运行时错误最常见的原因。

Pro 功能概览

功能	核心插件	UI 插件	Facade 导入
数据透视表	UniverSheetsPivotTablePlugin	UniverSheetsPivotTableUIPlugin	@univerjs-pro/sheets-pivot/facade
图表	UniverSheetsChartPlugin	UniverSheetsChartUIPlugin	@univerjs-pro/sheets-chart/facade
迷你图	UniverSheetSparklinePlugin	UniverSheetSparklineUIPlugin	@univerjs-pro/sheets-sparkline/facade
形状	UniverSheetsShapePlugin	UniverSheetsShapeUIPlugin	@univerjs-pro/sheets-shape/facade
打印	UniverSheetsPrintPlugin	—	@univerjs-pro/sheets-print/facade
交换（导入/导出）	UniverExchangeClientPlugin	UniverSheetsExchangeClientPlugin	@univerjs-pro/exchange-client/facade
协作	UniverCollaborationPlugin + UniverCollaborationClientPlugin	UniverCollaborationClientUIPlugin	@univerjs-pro/collaboration-client/facade
实时共享	UniverLiveSharePlugin	—	@univerjs-pro/live-share/facade
许可证	UniverLicensePlugin	—	—

常见任务

导入 XLSX

const unitId = await univerAPI.importXLSXToUnitIdAsync(file);
// file can be a File object or a URL string

导出 XLSX

import { downloadFile } from '@univerjs-pro/exchange-client';

const fWorkbook = univerAPI.getActiveWorkbook();
const file = await univerAPI.exportXLSXByUnitIdAsync(fWorkbook.getId());
downloadFile(file, 'export', 'xlsx');

打印

const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.updatePrintConfig({
  area: univerAPI.Enum.PrintArea.CurrentSheet,
  paperSize: univerAPI.Enum.PrintPaperSize.A4,
  scale: univerAPI.Enum.PrintScale.FitPage,
});
fWorkbook.updatePrintRenderConfig({ gridlines: true });
fWorkbook.print();

插入图表

const fWorksheet = univerAPI.getActiveWorkbook().getActiveSheet();
const chartInfo = fWorksheet.newChart()
  .setChartType(univerAPI.Enum.ChartType.Column)
  .addRange('A1:D6')
  .setPosition(1, 1, 0, 0)
  .build();
await fWorksheet.insertChart(chartInfo);

插入形状

const shapeInfo = fWorksheet.newShape()
  .setShapeType(univerAPI.Enum.ShapeTypeEnum.Rect)
  .setPosition(1, 1, 0, 0)
  .setWidth(200)
  .setHeight(200)
  .build();
await fWorksheet.insertShape(shapeInfo);

参考资料

• Pro 功能指南：references/pro-features-guide.md — 完整的 Pro 插件注册表、工作线程配置和功能矩阵
• 协作指南：references/collaboration-guide.md — 实时协作设置、套接字服务、加载服务单元、状态监控
• 交换指南：references/exchange-guide.md — XLSX/DOCX 导入导出、服务 URL、快照转换、下载工具
• 打印指南：references/print-guide.md — 打印配置、预览对话框、截图到剪贴板、事件
• 许可证指南：references/license-guide.md — 许可证获取、客户端/服务端配置、评估限制、验证
• 外观扩展（Pro）：references/facade-extension-pro.md — FUniver、FWorkbook、FWorksheet、FCollaboration 上 Pro 专属的外观方法