# 安裝與基本使用

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

Univer PDFs 是 Univer Office SDK 產品，目前不提供預設。請使用外掛模式建立 PDF 應用程式。

Univer 提供*預設模式*與*外掛模式*兩種整合方式。預設模式透過預先組合好的外掛簡化設定，更容易上手；如果**需要深度擴充**，建議使用外掛模式，依需求組合與設定外掛。

## 透過外掛模式建立

### 使用套件管理器

使用支援 ES Module 和 `package.json` 中 `exports` 欄位的建置工具。

#### 安裝

Univer 使用 React 建構介面、RxJS 處理資料流，也可以嵌入 Vue 或 Angular 應用程式。請確認已安裝 `react`、`react-dom` 和 `rxjs` 這些 peer dependencies[^peer-dependency]；下方 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 入口。樣式依 `@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.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。

建立一個 Worker 入口，例如 `pdf-thumbnail.worker.ts`：

```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/zh-TW/guides/pdfs/features/collaboration.md)文件安裝並註冊完整的 `@univerjs-pro/collaboration`、`@univerjs-pro/collaboration-client` 和 `@univerjs-pro/collaboration-client-ui` 外掛程式堆疊，再安裝並註冊 PDF 編輯器生命週期外掛程式。

## Node.js 用法

Node.js 服務只需註冊 `UniverPdfsPlugin`，不需要瀏覽器 UI 套件。僅當服務需要載入或同步已持久化的 PDF 單元時，才加入上述完整協作外掛程式堆疊。

## 其他發佈版本

除穩定版外，Univer 亦提供 alpha / beta 通道。這些版本可讓你搶先體驗未正式釋出的新功能；但請注意，功能更多同時代表風險更高，可能包含錯誤、未完成或不穩定特性。生產環境請謹慎使用。

### Alpha / Beta 版本

當團隊完成新功能或重大調整，可能會預先發佈於 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) 回報。

祝你搶先體驗愉快！

## 下一步

* [快速入門](https://docs.univer.ai/zh-TW/guides/pdfs/getting-started/quickstart.md)
* [Facade API](https://docs.univer.ai/zh-TW/guides/pdfs/getting-started/facade.md)
* [授權設定](https://docs.univer.ai/zh-TW/server/license.md)
* [Server SDK 整合](https://docs.univer.ai/zh-TW/server.md)

[^peer-dependency]: `peerDependencies` 表示需要由宿主專案提供相容版本的相依套件，讓 Univer 與應用程式共用 React 等函式庫，而不是各自攜帶一份。

[^facade-entry]: Facade 是面向應用程式的 API，封裝已註冊外掛的能力。匯入 Facade 入口會擴充 API 方法，但不會取代功能外掛的註冊。