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

- Human documentation: [https://docs.univer.ai/ja-JP/guides/docs/getting-started/installation](https://docs.univer.ai/ja-JP/guides/docs/getting-started/installation)

- Agent Markdown: [https://docs.univer.ai/ja-JP/guides/docs/getting-started/installation.md](https://docs.univer.ai/ja-JP/guides/docs/getting-started/installation.md)

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.1.0`

- Source: [docs/getting-started/installation/index.ja-JP.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/docs/getting-started/installation/index.ja-JP.mdx)

---

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

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

> [!WARNING: 注意事項]
> * **依存バージョンの一致**：プリセット/プラグインどちらの方法でも、依存関係のバージョンは揃える必要があります。
> * **プリセットとプラグインの併用に注意**：プリセットに含まれるプラグインを重複して読み込むと、衝突や不具合の原因になります。

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

| プラグインモード                       | プリセットモード                  |
| ------------------------------ | ------------------------- |
| 対応する facade パッケージを手動で読み込む必要がある | facade パッケージの手動読み込みは不要    |
| 同種の機能プラグインの登録順に注意が必要           | プリセット内の機能は登録順を気にしなくてよい    |
| 必要に応じた遅延読み込みが可能                | 設定したプリセットは初期化時に同期的に読み込まれる |

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

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

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

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

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

#### インストール

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

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

#### pnpm

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

#### npm

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

#### yarn

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

#### bun

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

#### 使い方

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

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

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

> [!WARNING: 注意事項]
> * すべてのプラグインに facade パッケージ、言語パック、スタイルファイルがあるわけではありません。各機能のドキュメントで案内します。
> * スタイルの読み込み順が重要です。`@univerjs/design` と `@univerjs/ui` の CSS を先に読み込み、その後に他プラグインの 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'
   ```

1.
   例で使用する facade パッケージを読み込みます。
   
   ```typescript
   import '@univerjs/engine-formula/facade'
   import '@univerjs/ui/facade'
   import '@univerjs/docs/facade'
   import '@univerjs/docs-ui/facade'
   ```

1.
   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({})
   ```

> Interactive example: [Open the playground](/playground/docs/slim-via-plugin)

#### `univer.registerPlugin` と `univer.registerPlugins` メソッド

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

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

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

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

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

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

```typescript
// ...

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 を利用](https://docs.univer.ai/ja-JP/guides/docs/getting-started/installation/cdn.md#plugin-mode) を参照してください。

## モバイル対応

> [!WARNING]
> 以下のモバイルプラグインをエクスポートする SDK パッケージが必要です。すべての `@univerjs/*` と `@univerjs-pro/*` の依存関係を**同じバージョン**に揃えてください。
> 
> `1.0.0-rc.0` は `UniverDocsMobileUIPlugin` をエクスポートしません。このモバイルエントリーを含むビルドで以下の例を使用してください。

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

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

```typescript
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](https://docs.univer.ai/ja-JP/server.md) で対応する機能を組み込んでください。

| パッケージ                              | デスクトップの登録                         | モバイルの登録                                 |
| ---------------------------------- | --------------------------------- | --------------------------------------- |
| `@univerjs/ui`                     | `UniverUIPlugin`                  | `UniverMobileUIPlugin`                  |
| `@univerjs/docs-ui`                | `UniverDocsUIPlugin`              | `UniverDocsMobileUIPlugin`              |
| `@univerjs/drawing-ui`             | `UniverDrawingUIPlugin`           | `UniverDrawingMobileUIPlugin`           |
| `@univerjs/thread-comment-ui`      | `UniverThreadCommentUIPlugin`     | `UniverThreadCommentMobileUIPlugin`     |
| `@univerjs-pro/shape-editor-ui`    | `UniverShapeEditorUIPlugin`       | `UniverShapeEditorMobileUIPlugin`       |
| `@univerjs-pro/chart-ui`           | `UniverChartUIPlugin`             | `UniverChartMobileUIPlugin`             |
| `@univerjs-pro/exchange-client`    | `UniverExchangeClientPlugin`      | `UniverExchangeClientMobileUIPlugin`    |
| `@univerjs/docs-drawing-ui`        | `UniverDocsDrawingUIPlugin`       | `UniverDocsDrawingMobileUIPlugin`       |
| `@univerjs/docs-hyper-link-ui`     | `UniverDocsHyperLinkUIPlugin`     | `UniverDocsHyperLinkMobileUIPlugin`     |
| `@univerjs/docs-thread-comment-ui` | `UniverDocsThreadCommentUIPlugin` | `UniverDocsThreadCommentMobileUIPlugin` |
| `@univerjs-pro/docs-callout-ui`    | `UniverDocsCalloutUIPlugin`       | `UniverDocsCalloutMobileUIPlugin`       |
| `@univerjs-pro/docs-chart-ui`      | `UniverDocsChartUIPlugin`         | `UniverDocsChartMobileUIPlugin`         |
| `@univerjs-pro/docs-code-ui`       | `UniverDocsCodeUIPlugin`          | `UniverDocsCodeMobileUIPlugin`          |
| `@univerjs-pro/docs-column-ui`     | `UniverDocsColumnUIPlugin`        | `UniverDocsColumnMobileUIPlugin`        |
| `@univerjs-pro/docs-formula-ui`    | `UniverDocsFormulaUIPlugin`       | `UniverDocsFormulaMobileUIPlugin`       |
| `@univerjs-pro/docs-latex-ui`      | `UniverDocsLatexUIPlugin`         | `UniverDocsLatexMobileUIPlugin`         |
| `@univerjs-pro/docs-list-ui`       | `UniverDocsListUIPlugin`          | `UniverDocsListMobileUIPlugin`          |
| `@univerjs-pro/docs-quote-ui`      | `UniverDocsQuoteUIPlugin`         | `UniverDocsQuoteMobileUIPlugin`         |
| `@univerjs-pro/docs-shape-ui`      | `UniverDocsShapeUIPlugin`         | `UniverDocsShapeMobileUIPlugin`         |
| `@univerjs-pro/docs-table-ui`      | `UniverDocsTableUIPlugin`         | `UniverDocsTableMobileUIPlugin`         |

### コンテナーとタッチ操作

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

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

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

## プリセットモードで作成

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

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

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

#### インストール

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

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

#### 使い方

> [!WARNING]
> ビルドツールが package.json の `exports` をサポートしていない場合（例：Webpack 4）、マッピングされたパスを実際のパスに変更する必要があります。

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

```html title="index.html"
<div id="app" style="height: 600px"></div>
```

```typescript
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 の機能を呼び出すために使用します。

> Interactive example: [Open the playground](/playground/docs/slim-via-preset)

> [!WARNING]
> `@univerjs/presets/preset-docs-core` から `UniverDocsCorePreset` を読み込むこともできますが、`exports` に対応したビルドツールが必要です。

#### `createUniver` メソッド

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

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

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

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

> [!NOTE]
> `createUniver` の詳細は [API Reference / createUniver](https://docs.univer.ai/ja-JP/reference/methods/create-univer.md) を参照してください。

### CDN で Univer を使う

パッケージマネージャーを使わずに試したい場合は CDN で読み込めます。詳細は [CDN で Univer を利用](https://docs.univer.ai/ja-JP/guides/docs/getting-started/installation/cdn.md#plugin-mode) を参照してください。

## その他のリリース

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

### Alpha/Beta リリース

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

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

alpha/beta バージョンを使用中に問題が発生したり、フィードバックがある場合は、[GitHub Issues](https://github.com/dream-num/univer/issues) から Univer 開発チームに報告してください。

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

## 次のステップ

* [基本概念](https://docs.univer.ai/ja-JP/guides/docs/getting-started/quickstart.md#basic-concepts) で本章に登場するプラグイン、コマンド、Facade API の概念を確認しましょう。
* [機能](https://docs.univer.ai/ja-JP/guides/docs/features/core.md) でドキュメント操作の機能を確認しましょう。

[^facade-entry]: Facade は、登録済みプラグインの機能をアプリケーションから操作する API です。Facade のエントリをインポートすると API メソッドが追加されますが、機能プラグイン自体は登録されません。

[^peer-dependency]: `peerDependencies` は、ホストアプリケーションが互換性のあるバージョンを用意する依存パッケージです。Univer とアプリケーションが React などのライブラリを共有できます。

[^mobile-ui-mode]: モバイル UI プラグインは初期化時にタッチ用の部品とサービスを選択します。端末の自動判定や、ウィンドウサイズ変更による既存インスタンスの切り替えは行いません。モードを変更する場合は文書の状態を保存し、旧インスタンスを破棄してから選択したプラグインで初期化します。