univer-integrate

Univer 統合

アプリケーションに Univer を埋め込み、公開 Facade API を通じて操作します。

ソースの基準バージョン：Univer 1.0.0-beta.0。現在の dream-num/univer ソースと同期しています。まず、ユーザーがインストールしている @univerjs/* のバージョンと既存のセットアップを確認し、既存のプロジェクトを変更する場合はそのバージョンを維持してください。

1.0 の製品範囲

UniverInstanceType で表される製品マトリックスは、現在、Sheets、Docs、Slides、Bases、Boards、PDFs を対象としています。この OSS スキルが担当するのは、Sheets と Docs のプリセット統合、および OSS Slides パッケージの境界です。現在ライセンスが必要な Slides 製品と Bases、Boards、PDFs には univer-pro-integrate を使用してください。これらの製品では、Pro 専用のプラグイン、Facade エントリー、CSS、ユニットスナップショットが使用されます。

統合モードを選択する

• 新しいアプリケーションや一般的な統合には、Preset Mode を使用してください。プリセットが必要なプラグインと Facade 登録を組み合わせます。ブラウザーのスタイルとロケールバンドルは、引き続き明示的にインポートする必要があります。
• カスタム読み込み、小さなバンドル、プラグインの置き換え、または正確な登録制御が必要な場合に限り、Plugin Mode を使用してください。プラグインを手動で組み合わせる前に、references/plugin-registry.md を読んでください。
• 専用のヘッドレス Node.js ワークフローには、univer-node-backend を使用してください。

クイックスタート：Sheets プリセット

すべての @univerjs/* 依存関係で、同じバージョンを指定してください。

npm install @univerjs/[email protected] @univerjs/[email protected] [email protected] [email protected] [email protected]

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core';
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US';
import { createUniver, defaultTheme, LocaleType, mergeLocales } from '@univerjs/presets';

import '@univerjs/preset-sheets-core/lib/index.css';

const { univer, univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(UniverPresetSheetsCoreEnUS),
  },
  theme: defaultTheme,
  presets: [
    UniverSheetsCorePreset({
      container: 'app',
    }),
  ],
});

const workbook = univerAPI.createWorkbook({
  id: 'workbook-1',
  name: 'Demo',
  sheetOrder: ['sheet-1'],
  sheets: {
    'sheet-1': {
      id: 'sheet-1',
      name: 'Sheet1',
      rowCount: 100,
      columnCount: 20,
    },
  },
});

workbook.getActiveSheet()!.getRange('A1:B2').setValues([
  ['Hello', 'Univer'],
  [1, 2],
]);

window.addEventListener('pagehide', () => univer.dispose(), { once: true });

コンポーネントフレームワークでは、コンポーネント自身の破棄処理で univer.dispose() を呼び出してください。

ページには、サイズが指定されたコンテナーが必要です。

<div id="app" style="height: 100vh"></div>

プリセットで機能を追加する

各機能を @univerjs/presets と同じバージョンでインストールし、そのロケールをインポートしてから、プリセットを追加してください。

import { UniverSheetsDataValidationPreset } from '@univerjs/preset-sheets-data-validation';
import UniverPresetSheetsDataValidationEnUS from '@univerjs/preset-sheets-data-validation/locales/en-US';

import '@univerjs/preset-sheets-data-validation/lib/index.css';

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDataValidationEnUS,
    ),
  },
  presets: [
    UniverSheetsCorePreset({ container: 'app' }),
    UniverSheetsDataValidationPreset(),
  ],
});

利用可能な OSS プリセットは references/plugin-registry.md に記載されています。ブラウザーで使用する各プリセットが提供するスタイルシートをインポートしてください。プリセットと、その基盤となる同じプラグインの両方を登録しないでください。

Facade API のルール

プリセットパッケージは Facade 拡張を登録します。Plugin Mode では、使用する各機能の /facade エントリーを明示的にインポートしてください。

import { FUniver } from '@univerjs/core/facade';

import '@univerjs/engine-formula/facade';
import '@univerjs/sheets/facade';
import '@univerjs/sheets-formula/facade';
import '@univerjs/ui/facade';

const univerAPI = FUniver.newAPI(univer);

内部サービスよりも、機能レベルの Facade メソッドとビルダーを優先してください。

const workbook = univerAPI.getActiveWorkbook();
if (!workbook) throw new Error('No active workbook');

const worksheet = workbook.getActiveSheet();
if (!worksheet) throw new Error('No active worksheet');

worksheet.getRange('A1')
  .setValue('Hello')
  .setBackground('#ff0000')
  .setFontColor('#ffffff');

const snapshot = workbook.save();

現在のメソッド名と機能のインポート一覧については、references/facade-api-guide.md を読んでください。

バージョンポリシー

1. package.json、ロックファイル、または node_modules/@univerjs/core/package.json を確認します。
2. すべての @univerjs/* パッケージで、プロジェクトにインストールされている正確なバージョンを再利用します。
3. このソースの基準バージョンを対象に新しいプロジェクトを作成する場合は、1.0.0-beta.0 を使用します。
4. OSS とプリセットのパッケージで異なるバージョンを混在させないでください。Pro が含まれている場合は、@univerjs-pro/* も同じリリース系列に揃えてください。

ランタイムの互換性

現在の Univer は、Edge 88 以降、Firefox 90 以降、Chrome 88 以降、Safari 14.1 以降、Electron 12 以降を対象としています。ヘッドレス Univer は Node.js 18.17 以降をサポートします。対象ランタイムに Intl.Segmenter がない場合は、ポリフィルを追加してください。

テーマとロケール

初期テーマは createUniver で設定します。現在のソースでは、Facade を通じた実行時のテーマ変更もサポートされています。

univerAPI.setTheme(defaultTheme);
univerAPI.toggleDarkMode(true);
univerAPI.setLocale(LocaleType.EN_US);

ブランドに合わせた配色、ダークモード、プラグインの CSS 変数、6 製品のテーマ範囲、現在のテーマメソッドに対するインストール済みリリースの判定には、univer-customize-theme を使用してください。

setTheme()、getCurrentTheme()、isDarkMode() を出力する前に、インストール済みの FUniver 宣言を確認してください。現在のソースのプレリリースバージョンラベルが付いた npm 公開パッケージでは、これらのメソッドがまだ含まれていない場合があります。テーマ選択の移植性を確保するには、初期化時に設定してください。

登録するプリセットまたはプラグインが提供するすべてのロケールバンドルを読み込んでください。翻訳済みの文字列を独自にキャッシュしないでください。

コアモデル

• univerAPI.createWorkbook(data) は FWorkbook を作成して返します。
• univerAPI.getWorkbook(id) は、指定したワークブックを取得します。
• workbook.getActiveSheet() と workbook.getSheetByName(name) は、FWorksheet オブジェクトを返します。
• worksheet.getRange('A1:B2') は FRange を返します。
• workbook.save() は、現在の IWorkbookData スナップショットを返します。
• univerAPI.disposeUnit(id) は 1 つのユニットを破棄し、univer.dispose() はアプリケーションを終了します。

対応する Docs プリセット／プラグインを登録してから、createDocument を使用してください。Bases、Boards、PDF、または現行の Pro Slides 製品をワークブックとして扱わないでください。これらには、univer-pro-integrate に記載されている各製品固有の Facade 作成メソッドを使用してください。

アンチパターン

• Workbook や Worksheet のモデルを直接変更しないでください。取り消し／やり直しとリアクティブな更新の整合性を保つため、Facade メソッドまたは Commands を使用してください。
• 古いリリースの Facade メソッドを推測して使用しないでください。インストール済みパッケージのソースまたは型を確認してください。いくつかの 0.x のメソッド名は 1.0.0-beta.0 で変更されています。
• 既存のプリセットが同じ構成を管理している場合、新しいアプリにプラグイン一覧を手動でコピーしないでください。
• ブラウザビルドでプリセットまたはプラグインの CSS を省略しないでください。
• ユニットまたは Univer インスタンスの破棄後も、ワークブック、ワークシート、範囲のハンドルを保持しないでください。
• 別のワークブックを追加するためだけに、Univer インスタンスを新たに作成しないでください。ページに独立したエディターコンテナが本当に必要な場合を除き、複数のユニットを使用してください。

一般的な操作

const workbook = univerAPI.getActiveWorkbook()!;
const worksheet = workbook.getActiveSheet()!;

worksheet.getRange('A1:D2').setValues([
  ['Product', 'Qty', 'Price', 'Total'],
  ['Apple', 2, 3, '=B2*C2'],
]);

worksheet.setColumnWidth(0, 140);
worksheet.setRowHeight(0, 32);
workbook.undo();
workbook.redo();

参考資料

• references/facade-api-guide.md — 現行の Facade 階層、メソッド名、インポート、機能の例
• references/common-tasks.md — 永続化、書式設定、ハイパーリンク、イベント、CSV、テーマ、大規模データセット
• references/plugin-registry.md — 現行の OSS プリセットと手動で追加するプラグイン
• references/framework-integration.md — React、Vue 3、Web Component、iframe、Node のライフサイクルパターン
• references/worker-setup.md — 現行のブラウザおよび Node 用ワーカープリセット
• references/custom-functions.md — 同期および非同期のカスタム数式関数
• references/permissions.md — ワークブック、ワークシート、範囲の権限 Facade
• references/multi-unit-management.md — 複数ユニットの作成、取得、フォーカス、破棄
• references/network-and-others.md — Network、Watermark、Action Recorder、Telemetry の適用範囲

テンプレート

assets/templates/ から、最も適した小規模なテンプレートをコピーしてください。

• react-vite/
• vue3-vite/
• plain-html/
• node/