インストールと基本的な使い方

Univer はプラグイン志向の設計で、柔軟で拡張可能なドキュメントアプリ基盤を提供します。プラグイン構成により機能モジュールを容易に統合できますが、初めて触れる開発者にとっては複雑に感じることがあります。

そのため Univer では プラグインモード と プリセットモード の 2 つを用意し、素早く導入できるようにしています。プリセットは事前に構成されたプラグインの組み合わせで、複雑な拡張をしない限り両者の機能は同等です。

プリセットモードとプラグインモードの違い：

Univer にはプリセットモードとプラグインモードの 2 つの導入方法があります。プリセットモードは構成済みのプラグインをまとめて読み込むため、簡単に導入できます。高度なカスタマイズや拡張が必要な場合は、プラグインを個別に組み合わせて設定できるプラグインモードを推奨します。

プラグインモードでのセットアップ

Univer はプラグインとして機能を提供します。必須のコアプラグインに加えて、必要に応じて他のプラグインを選択できます。ここでは最小構成の Univer Docs を例に、手動でプラグインを組み合わせる方法を紹介します。

プリセットモードと異なり、プラグインモードには Facade API¹ がデフォルトでは含まれません。以下の例では Facade API を使用するため、API インスタンスを作成する前に対応する facade パッケージを読み込んでください。

パッケージマネージャーの使用

インストール

Univer は UI に React、データストリームに RxJS を使用し、Vue や Angular アプリにも組み込めます。peer dependencies² の react、react-dom、rxjs がインストールされていることを確認してください。以下の Yarn コマンドにはこれらを明示的に含めています。

すべての @univerjs/* と @univerjs-pro/* パッケージのバージョンを揃えてください。

pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui react react-dom rxjs

bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

使い方

Univer の初期化前にコンテナーを作成し、高さを指定してください：

<div id="app" style="height: 600px"></div>

FUniver.newAPI(univer) を呼び出す前に、以下の例で使用する facade エントリーをインポートしてください。CSS は @univerjs/design、@univerjs/ui、製品 CSS の順にインポートします。

1. プロジェクトで Univer のスタイル、言語パック、必要なプラグインを読み込みます。

   TypeScript

   import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { FUniver } from '@univerjs/core/facade'import DesignJaJP from '@univerjs/design/locale/ja-JP'import { UniverDocsPlugin } from '@univerjs/docs'import { UniverDocsUIPlugin } from '@univerjs/docs-ui'import DocsUIJaJP from '@univerjs/docs-ui/locale/ja-JP'import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'import { UniverRenderEnginePlugin } from '@univerjs/engine-render'import { UniverUIPlugin } from '@univerjs/ui'import UIJaJP from '@univerjs/ui/locale/ja-JP'import '@univerjs/design/lib/index.css'import '@univerjs/ui/lib/index.css'import '@univerjs/docs-ui/lib/index.css'

2. 例で使用する facade パッケージを読み込みます。

   TypeScript

   import '@univerjs/engine-formula/facade'import '@univerjs/ui/facade'import '@univerjs/docs/facade'import '@univerjs/docs-ui/facade'

3. Univer インスタンスを作成し、プラグインを登録します。

   TypeScript

   const univer = new Univer({  locale: LocaleType.JA_JP,  locales: {    [LocaleType.JA_JP]: mergeLocales(      DesignJaJP,      UIJaJP,      DocsUIJaJP,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverFormulaEnginePlugin)univer.registerPlugin(UniverUIPlugin, {  container: 'app',})univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})

   コードを展開

univer.registerPlugin と univer.registerPlugins メソッド

univer.registerPlugin メソッドは、Univer インスタンスにプラグインを登録するために使用されます。Univer インスタンスを作成した後、このメソッドを呼び出してプラグインを登録できます。

univer.registerPlugin(Plugin, options) メソッドを使用してプラグインを登録できます。ここで Plugin は登録するプラグイン、options はオプションの設定項目で、各プラグインは異なる設定項目を持つ場合があります。

univer.registerPlugins に配列を渡して複数のプラグインを一度に登録することも可能です。これは、プラグインを一元管理する必要があるシナリオで便利です。

univer.registerPlugins([  UniverRenderEnginePlugin,  UniverFormulaEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,])

一部プラグインの遅延読み込み

プラグインモードの利点は、プラグインの読み込みタイミングを柔軟に制御できる点です。代表的な方法として、初期化時に必須プラグインのみ読み込み、初回レンダリング後に一部プラグインを読み込む方法があります。

// ...const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {  univer.registerPlugin(UniverWatermarkPlugin, {    textWatermarkSettings: {      content: 'Hello, Univer!',      fontSize: 36,    },  })})

CDN で Univer を使う

パッケージマネージャーを使わずに試したい場合は CDN で読み込めます。詳細は CDN で Univer を利用 を参照してください。

モバイル対応

Univer Docs のタッチ操作にはモバイル UI プラグインを使用します。³ エディターを作成する前に UI モードを選択してください。

上のプラグインモードの例で、次の UI のインポートと登録を createUnit() の前に置き換えます。初期化済みのデスクトップエディターに追加しないでください。モデル、エンジン、言語ファイル、CSS、Facade のインポートは維持します。両クラスは同じパッケージの入口からの名前付きエクスポートです。

import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsMobileUIPlugin)

現在の UniverSheetsCorePreset と UniverDocsCorePreset はデスクトップ UI を登録し、mobile: true オプションを持ちません。モバイルではプラグインを明示的に組み合わせます。デスクトッププリセットの後にモバイルプラグインを追加しても UI は置き換わりません。

プラグイン対応表

必要な機能だけを登録し、モデルプラグインと依存関係は維持してください。モバイル UI の提供は、両方の操作画面が同一であることを意味しません。Pro 機能には引き続きライセンスが必要です。バックエンドが必要な機能は、アプリに Univer Server SDK で対応する機能を組み込んでください。

コンテナーとタッチ操作

コンテナーの高さを明示し、ページの viewport を設定してください。100dvh は動的なビューポートの高さに追従します。対象のモバイルブラウザーでスクロール、ピンチ操作、文字選択、クリップボード、ソフトキーボード表示時の配置を確認してください。幅を狭めるだけではモバイルプラグインに切り替わりません。

UniverMobileUIPlugin の既定値は disableAutoFocus: true で、初期化時にエディターが自動でフォーカスを取得することを防ぎます。

<meta name="viewport" content="width=device-width, initial-scale=1" /><div id="app" style="height: 100dvh"></div>

プリセットモードで作成

ここでは 20 行未満のコードで Univer Docs アプリを作成する方法を紹介します。

パッケージマネージャーを使う

プロジェクトにモダンなフロントエンド開発環境があれば、Univer の導入は簡単です。ES Modules に対応したビルドツール（Vite、esbuild、Webpack 5 など）を推奨します。Webpack 4 などを使う場合は追加設定が必要になることがあります。

インストール

使用しているパッケージマネージャーで @univerjs/presets をインストールします。

pnpm add @univerjs/presets @univerjs/preset-docs-core

npm install @univerjs/presets @univerjs/preset-docs-core

yarn add @univerjs/presets @univerjs/preset-docs-core

bun add @univerjs/presets @univerjs/preset-docs-core

使い方

次のコードで Univer Docs アプリを作成できます。

<div id="app" style="height: 600px"></div>

import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'import UniverPresetDocsCoreJaJP from '@univerjs/preset-docs-core/locales/ja-JP'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-docs-core/lib/index.css'const { univer, univerAPI } = createUniver({  locale: LocaleType.JA_JP,  locales: {    [LocaleType.JA_JP]: mergeLocales(      UniverPresetDocsCoreJaJP,    ),  },  presets: [    UniverDocsCorePreset({      container: 'app',    }),  ],})univerAPI.createDocument({})

ここで返される univerAPI は Univer の Facade API で、Univer の機能を呼び出すために使用します。

createUniver メソッド

createUniver は言語、テーマ、プラグインなどを含む設定オブジェクトを受け取り、Univer インスタンスと Facade API インスタンスを返します。

設定オブジェクトの主な項目：

• locale：言語環境。LocaleType の列挙値。
• locales：言語パック。キーが言語環境、値が言語パック。
• theme：テーマ（任意）。
• presets：登録するプリセット配列（例：UniverDocsCorePreset）。
• plugins：追加で登録するプラグイン配列。

プリセットに含まれないプラグインや独自プラグインを使う場合は plugins に登録します。Univer インスタンスを取得した後に univer.registerPlugin で登録することもできます。

CDN で Univer を使う

パッケージマネージャーを使わずに試したい場合は CDN で読み込めます。詳細は CDN で Univer を利用 を参照してください。

その他のリリース

安定版リリースに加えて、Univer は alpha/beta および nightly チャンネルも提供しています。これらのバージョンでは、まだ正式にリリースされていない最新機能に早期にアクセスできます。ただし、機能が多いということはリスクも多いということを覚えておいてください。これらのバージョンにはバグ、不完全な機能、または不安定な機能が含まれている可能性があります。可能な限り、本番環境でのこれらのバージョンの使用は避けてください。

Alpha/Beta リリース

Univer 開発チームが新機能や重要な変更を完了すると、alpha または beta チャンネルにプレリリースすることがあります。以下のコマンドを使用して Univer パッケージの alpha/beta バージョンをインストールできます：

pnpm add @univerjs/<package-name>@alpha # Alpha バージョン
pnpm add @univerjs/<package-name>@beta # Beta バージョン

npm install @univerjs/<package-name>@alpha # Alpha バージョン
npm install @univerjs/<package-name>@beta # Beta バージョン

yarn add @univerjs/<package-name>@alpha # Alpha バージョン
yarn add @univerjs/<package-name>@beta # Beta バージョン

bun add @univerjs/<package-name>@alpha # Alpha バージョン
bun add @univerjs/<package-name>@beta # Beta バージョン

alpha/beta バージョンを使用中に問題が発生したり、フィードバックがある場合は、GitHub Issues から Univer 開発チームに報告してください。

これらの早期リリースについてのフィードバックを歓迎します。

次のステップ

• 基本概念 で本章に登場するプラグイン、コマンド、Facade API の概念を確認しましょう。
• 機能 でドキュメント操作の機能を確認しましょう。