univer-pro-integrate

Univer Pro の統合

既存の Web アプリケーションに Univer Pro を組み込むためのガイドです。Univer Pro は、コラボレーション、インポート／エクスポート、印刷、ピボットテーブル、チャート、スパークライン、図形、ライセンス管理などのエンタープライズ機能を追加し、オープンソース版の Univer を拡張します。

互換性：このスキルは Univer Pro v0.20.x 向けに作成されています。基本概念はマイナーバージョン間で安定していますが、メソッドの具体的なシグネチャは変更される場合があります。ユーザーがインストールした @univerjs-pro/* のバージョンを確認し、プロジェクトで既に使用されている API のパターンを優先してください。

前提条件：Univer Pro を使用するには、オープンソース版の Univer コアが必要です。Pro 機能を適用する前に、基本的な統合パターン（初期化、Facade API、プラグインアーキテクチャ）については univer-integrate スキルを参照してください。

クイックスタート

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 ワーカーのセットアップ

Pro ワーカーには 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;

基本概念

ライセンスを最初に登録する

UniverLicensePlugin は、Univer インスタンスの作成直後、他の 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 — ライセンスの取得、クライアント／サーバーの設定、評価版の制限、検証
• Facade 拡張機能（Pro）：references/facade-extension-pro.md — FUniver、FWorkbook、FWorksheet、FCollaboration の Pro 固有の Facade メソッド