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

Univer は、開発者に電子文書アプリケーション向けの柔軟で拡張可能なフレームワークを提供することを目的として、プラグインベースの設計思想を採用しています。このプラグインベースの設計により、Univer は様々な機能モジュールを簡単に統合して、異なるユーザーのニーズに対応できます。しかし、プラグインベースの設計はアプリケーションの複雑さを増し、特に Univer に慣れていない開発者にとっては難しくなります。

このため、Univer は迅速に統合・使用できるよう2つの方法を提供しています：プラグインモードとプリセットモードです。いわゆるプリセットは実際には事前設定されたプラグインの組み合わせであり、複雑な拡張を行わない限り、両方のモードが提供する機能は同じです。

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

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

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

Univer は一連の機能をプラグインの形で提供しています。製品に不可欠ないくつかのコアプラグインに加えて、必要に応じて他のプラグインを選択的に導入できます。ここでは、最も基本的な Univer Sheets アプリケーションを例に、プラグインを手動で組み合わせてインストールする方法を紹介します。

プリセットモードとは異なり、プラグインモードはデフォルトで Facade API¹ を含みません。以下のコード例で Facade API 関連の部分はオプションであり、必要に応じて削除するかどうかを決定できます。

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

インストール

ビュー開発には React を使用し（これは Vue や Angular での Univer の使用には影響しません）、データストリームの処理には Rxjs を使用しています。これら 2 つのライブラリはモダンなフロントエンド開発で広く使用されているため、peerDependencies² として扱っています。ただし、パッケージ管理ツールによって peerDependencies の動作が異なるため、いくつかの詳細に注意する必要があります。

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

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

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

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

使い方

1. プロジェクトで Univer のスタイルファイル、言語パック、および必要なプラグインをインポートする必要があります：

   TypeScript

   import { LocaleType, mergeLocales, Univer, UniverInstanceType } 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 { UniverSheetsPlugin } from '@univerjs/sheets'import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'import SheetsFormulaUIJaJP from '@univerjs/sheets-formula-ui/locale/ja-JP'import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'import SheetsNumfmtUIJaJP from '@univerjs/sheets-numfmt-ui/locale/ja-JP'import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'import SheetsUIJaJP from '@univerjs/sheets-ui/locale/ja-JP'import SheetsJaJP from '@univerjs/sheets/locale/ja-JP'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'import '@univerjs/sheets-ui/lib/index.css'import '@univerjs/sheets-formula-ui/lib/index.css'import '@univerjs/sheets-numfmt-ui/lib/index.css'

   コードを展開

2. Facade API を使用する必要がある場合は、ここで関連する facade パッケージをインポートできます。これはオプションですが、推奨します：

   TypeScript

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

3. 次に、Univer インスタンスを作成し、これらのプラグインを登録します：

   TypeScript

   const univer = new Univer({  locale: LocaleType.JA_JP,  locales: {    [LocaleType.JA_JP]: mergeLocales(      DesignJaJP,      UIJaJP,      DocsUIJaJP,      SheetsJaJP,      SheetsUIJaJP,      SheetsFormulaUIJaJP,      SheetsNumfmtUIJaJP,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverFormulaEnginePlugin)univer.registerPlugin(UniverUIPlugin, {  container: 'app',})univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)univer.registerPlugin(UniverSheetsPlugin)univer.registerPlugin(UniverSheetsUIPlugin)univer.registerPlugin(UniverSheetsFormulaPlugin)univer.registerPlugin(UniverSheetsFormulaUIPlugin)univer.registerPlugin(UniverSheetsNumfmtPlugin)univer.registerPlugin(UniverSheetsNumfmtUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})const univerAPI = FUniver.newAPI(univer)

   コードを展開

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,  UniverSheetsPlugin,  UniverSheetsUIPlugin,  UniverSheetsFormulaPlugin,  UniverSheetsFormulaUIPlugin,  UniverSheetsNumfmtPlugin,  UniverSheetsNumfmtUIPlugin,])

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

プラグインモードの一般的な利点は、プラグインの読み込みタイミングをより柔軟に制御できることです。一般的なアプローチは、アプリケーション初期化時に必要不可欠なプラグインのみを読み込み、一部のプラグインの読み込みを最初のレンダリング完了後まで遅延させることです。

// ...univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {  univer.registerPlugin(UniverWatermarkPlugin, {    textWatermarkSettings: {      content: 'Hello, Univer!',      fontSize: 36,    },  })})

私たちの公式デモでもこの最適化技術を使用しており、参考にしていただけます。

モバイル対応

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

Sheets のモバイル対応は引き続き実験段階です。対象端末でアプリに必要な機能を検証してください。

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

import { UniverSheetsFormulaMobileUIPlugin } from '@univerjs/sheets-formula-ui'import { UniverSheetsNumfmtMobileUIPlugin } from '@univerjs/sheets-numfmt-ui'import { UniverSheetsMobileUIPlugin } from '@univerjs/sheets-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverSheetsMobileUIPlugin)univer.registerPlugin(UniverSheetsFormulaMobileUIPlugin)univer.registerPlugin(UniverSheetsNumfmtMobileUIPlugin)

Sheets では UniverDocsUIPlugin を維持してください。 UniverSheetsMobileUIPlugin はセル内の文書編集にこのプラグインを使用します。独立した Docs エディターでは 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>

CDN からのインポート

パッケージマネージャーを使用したくない場合や、Univer の機能を素早く試したい場合は、CDN 経由で Univer の関連リソースをインポートできます。詳細については、CDN 経由での Univer 使用を参照してください。

プリセットモードでのセットアップ

ここでは、20 行未満のコードで Univer Sheets アプリケーションを迅速に構築する方法を簡単に紹介します。

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

プロジェクトで既にモダンなフロントエンド開発ツールを使用している場合、Univer の統合は非常に簡単です。ES モジュールに良好なサポートを持つ Vite、esbuild、Webpack 5 などのビルドツールを使用して Univer アプリケーションを構築することをお勧めします。他のビルドツール（Webpack 4 など）を使用している場合は、追加の設定が必要になる場合があります。

インストール

お使いのパッケージマネージャーを選択して@univerjs/presetsをインストールしてください：

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

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

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

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

使い方

以下のコードで、Univer Sheets アプリケーションを開始できます：

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

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

ここで返される univerAPI オブジェクトは Univer Facade API と呼ばれ、これを通して Univer が提供する多くの機能を呼び出すことができます。

createUniver メソッド

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

設定オブジェクトのいくつかのプロパティは以下の通りです：

• locale: 言語環境、LocaleType 列挙値を使用できます。
• locales: ロケール、オブジェクトで、キーは言語環境、値は言語パックオブジェクトです。
• theme: テーマオブジェクト、オプションです。
• presets: 登録するプリセットを含むプリセットの配列、例：UniverSheetsCorePreset。
• plugins: 追加で登録する必要があるプラグインを含むプラグインの配列。

どのプリセットパッケージにも含まれていないプラグインを使用する場合や、独自のプラグインを実装する場合は、plugins プロパティを通してこれらのプラグインを登録できます。また、Univer インスタンスを取得した後に univer.registerPlugin メソッドを使用してプラグインを登録することも可能です。

CDN からのインポート

パッケージマネージャーを使用したくない場合や、Univer の機能を素早く試したい場合は、CDN 経由で Univer の関連リソースをインポートできます。詳細については、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 開発チームに報告してください。

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

次のステップ

• 基本概念 - Univer の基本概念について学びます。
• 機能 - Univer の機能とデータ操作方法について学びます。