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

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

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

- Requested language: `ja-JP`

- Content language: `ja-JP`

- Documentation version: `1.2.0`

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

---

Univer PDFs は Univer Office SDK 製品で、現在プリセットは提供されていません。PDF アプリケーションはプラグインモードで作成してください。

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

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

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

ES Modules と `package.json` の `exports` フィールドに対応したビルドツールを使用してください。

#### インストール

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/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### npm

```shell
npm install @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### yarn

```shell
yarn add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui react react-dom rxjs
```

#### bun

```shell
bun add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

すべての `@univerjs/*` パッケージと `@univerjs-pro/*` パッケージで**同じバージョン**を使用してください。

#### 使い方

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

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

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

1.
   共通 UI のスタイルを PDF UI のスタイルより先にインポートし、アプリケーションで有効にするロケールパックを統合します。
   
   ```ts
   import { UniverLicensePlugin } from '@univerjs-pro/license'
   import { UniverPdfsPlugin } from '@univerjs-pro/pdfs'
   import { UniverPdfsUIPlugin } from '@univerjs-pro/pdfs-ui'
   import PdfsUIEnUS from '@univerjs-pro/pdfs-ui/locale/en-US'
   import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
   import { FUniver } from '@univerjs/core/facade'
   import DesignEnUS from '@univerjs/design/locale/en-US'
   import { UniverUIPlugin } from '@univerjs/ui'
   import UIEnUS from '@univerjs/ui/locale/en-US'
   
   import '@univerjs/design/lib/index.css'
   import '@univerjs/ui/lib/index.css'
   import '@univerjs-pro/pdfs-ui/lib/index.css'
   ```

1.
   PDF Facade[^facade-entry] エントリをインポートします。この副作用インポートにより、`FUniver` に PDF のメソッドと列挙型が追加されます。
   
   ```ts
   import '@univerjs-pro/pdfs/facade'
   ```

1.
   ランタイムを作成し、明示的なプラグインスタックを登録してから、PDF を作成します。
   
   ```ts
   const univer = new Univer({
     locale: LocaleType.EN_US,
     locales: {
       [LocaleType.EN_US]: mergeLocales(
         DesignEnUS,
         UIEnUS,
         PdfsUIEnUS,
       ),
     },
   })
   
   univer.registerPlugin(UniverUIPlugin, { container: 'app' })
   univer.registerPlugin(UniverLicensePlugin, {
     license: process.env.CLIENT_LICENSE_TEXT,
   })
   univer.registerPlugin(UniverPdfsPlugin)
   univer.registerPlugin(UniverPdfsUIPlugin)
   
   const univerAPI = FUniver.newAPI(univer)
   univerAPI.createPdf({ name: 'Untitled PDF' })
   ```

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

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

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

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

```typescript
univer.registerPlugins([
  [UniverUIPlugin, { container: 'app' }],
  [UniverLicensePlugin, {
    license: process.env.CLIENT_LICENSE_TEXT,
  }],
  UniverPdfsPlugin,
  UniverPdfsUIPlugin,
])
```

## モバイル対応

現在の `@univerjs-pro/pdfs-ui` は独立したモバイル UI プラグインをエクスポートしていません。存在しない `MobileUIPlugin` や `mobile: true` オプションを使わないでください。狭いコンテナーだけではタッチ操作の完全な対応を確認できません。対象端末で既存 UI を検証してください。

## 任意のサムネイル Worker

ページサムネイルは、追加設定なしでメインスレッド上にレンダリングできます。大きなドキュメントには、`thumbnailWorkerURL` を通じて専用のモジュール Worker を指定できます。

`pdf-thumbnail.worker.ts` などの Worker エントリを作成します。

```ts
import { startPdfPageThumbnailWorker } from '@univerjs-pro/pdfs-ui'

startPdfPageThumbnailWorker()
```

PDF UI プラグインの登録時にその URL を渡します。

```ts
univer.registerPlugin(UniverPdfsUIPlugin, {
  thumbnailWorkerURL: new Worker(new URL('./pdf-thumbnail.worker.ts', import.meta.url), { type: 'module' }),
})
```

このオプションには文字列 URL または既存の `Worker` も指定できます。Worker または `OffscreenCanvas` を利用できない場合、サムネイルのレンダリングはメインスレッドにフォールバックします。

## 共同編集を使用する場合

`@univerjs-pro/pdfs-editor` はローカル専用の構成には含めません。単独で登録せず、まず[共同編集](https://docs.univer.ai/ja-JP/guides/pdfs/features/collaboration.md)の説明に従って `@univerjs-pro/collaboration`、`@univerjs-pro/collaboration-client`、`@univerjs-pro/collaboration-client-ui` の完全な構成をインストールして登録し、その後で PDF エディターのライフサイクルプラグインをインストールして登録してください。

## Node.js での使用

Node.js サービスでは、ブラウザー UI パッケージを使わずに `UniverPdfsPlugin` だけを登録できます。永続化された PDF ユニットの読み込みまたは同期が必要な場合にのみ、上記の完全な共同編集構成を追加してください。

## その他のリリース

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

### Alpha/Beta リリース

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

#### npm

```bash
npm install @univerjs-pro/pdfs@alpha # Alpha バージョン
npm install @univerjs-pro/pdfs@beta # Beta バージョン
```

#### pnpm

```bash
pnpm add @univerjs-pro/pdfs@alpha # Alpha バージョン
pnpm add @univerjs-pro/pdfs@beta # Beta バージョン
```

#### yarn

```bash
yarn add @univerjs-pro/pdfs@alpha # Alpha バージョン
yarn add @univerjs-pro/pdfs@beta # Beta バージョン
```

#### bun

```bash
bun add @univerjs-pro/pdfs@alpha # Alpha バージョン
bun add @univerjs-pro/pdfs@beta # Beta バージョン
```

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

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

## 次のステップ

* [クイックスタート](https://docs.univer.ai/ja-JP/guides/pdfs/getting-started/quickstart.md)
* [Facade API](https://docs.univer.ai/ja-JP/guides/pdfs/getting-started/facade.md)
* [ライセンス設定](https://docs.univer.ai/ja-JP/server/license.md)
* [Server SDK の統合](https://docs.univer.ai/ja-JP/server.md)

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

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