# 安裝與基本使用

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

本章介紹 Univer Slides 的安裝與基本使用。本指南使用 Web SDK 的 Slides 套件。目前沒有 Slides preset，因此需要透過 plugin mode 建立 Slides 應用。

如果你還不熟悉 Univer 的基礎概念，建議先閱讀 [快速開始](https://docs.univer.ai/zh-TW/guides/slides/getting-started/quickstart.md)。

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

## 透過外掛模式建立

Univer 以外掛形式提供 Slides 能力。瀏覽器端編輯器通常需要先註冊 Univer 共用 runtime、授權外掛、Docs 與 Drawing 依賴，然後再註冊 Slides 的模型和 UI 外掛。

### 使用套件管理器

使用支援 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/docs @univerjs/docs-ui @univerjs/drawing @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/slides @univerjs-pro/slides-ui
```

#### npm

```shell
npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/slides @univerjs-pro/slides-ui
```

#### yarn

```shell
yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/slides @univerjs-pro/slides-ui react react-dom rxjs
```

#### bun

```shell
bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/slides @univerjs-pro/slides-ui
```

#### 使用

初始化 Univer 前，先建立容器並設定明確的高度：

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

呼叫 `FUniver.newAPI(univer)` 前，請引入下方範例使用的 facade 入口。樣式依 `@univerjs/design`、`@univerjs/ui`、產品 CSS 的順序引入。

> [!WARNING: 注意事項]
> * 註冊 Slides 外掛前，需要先註冊 `UniverLicensePlugin`。
> * 樣式檔案的引入順序很重要，請先引入共用 UI 樣式，再引入產品 UI 樣式。
> * 列印、表格、圖表、匯入匯出等可選功能套件，只在產品需要對應能力時再加入。
> * `UniverSlidesUIPlugin` 會為形狀功能自動載入 `UniverProFormulaEnginePlugin`。如果同一個 `Univer` 執行個體還註冊了 `UniverFormulaEnginePlugin`，請安裝 `@univerjs-pro/engine-formula`，並在初始化程式碼中將一般引擎的匯入與註冊替換為 `UniverProFormulaEnginePlugin`。請勿同時註冊兩個公式引擎。

1.
   引入樣式檔案、語言包和必要外掛：
   
   ```typescript
   import { UniverLicensePlugin } from '@univerjs-pro/license'
   import { UniverSlidesPlugin } from '@univerjs-pro/slides'
   import { UniverSlidesUIPlugin } from '@univerjs-pro/slides-ui'
   import SlidesUIZhTW from '@univerjs-pro/slides-ui/locale/zh-TW'
   import SlidesZhTW from '@univerjs-pro/slides/locale/zh-TW'
   import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'
   import DesignZhTW from '@univerjs/design/locale/zh-TW'
   import { UniverDocsPlugin } from '@univerjs/docs'
   import { UniverDocsUIPlugin } from '@univerjs/docs-ui'
   import DocsUIZhTW from '@univerjs/docs-ui/locale/zh-TW'
   import { UniverDrawingPlugin } from '@univerjs/drawing'
   import { UniverRenderEnginePlugin } from '@univerjs/engine-render'
   import { UniverUIPlugin } from '@univerjs/ui'
   import UIZhTW from '@univerjs/ui/locale/zh-TW'
   
   import '@univerjs/design/lib/index.css'
   import '@univerjs/ui/lib/index.css'
   import '@univerjs/docs-ui/lib/index.css'
   import '@univerjs-pro/slides-ui/lib/index.css'
   ```

1.
   如果需要使用 Facade API[^facade-entry]，可以引入相關 facade 入口：
   
   ```typescript
   import { FUniver } from '@univerjs/core/facade'
   import '@univerjs-pro/slides/facade'
   ```

1.
   建立 Univer 實例，註冊外掛，並建立 Slides unit：
   
   ```typescript
   const univer = new Univer({
     locale: LocaleType.ZH_TW,
     locales: {
       [LocaleType.ZH_TW]: mergeLocales(
         DesignZhTW,
         UIZhTW,
         DocsUIZhTW,
         SlidesZhTW,
         SlidesUIZhTW,
       ),
     },
   })
   
   univer.registerPlugin(UniverRenderEnginePlugin)
   univer.registerPlugin(UniverUIPlugin, {
     container: 'app',
   })
   
   univer.registerPlugin(UniverDocsPlugin)
   univer.registerPlugin(UniverDocsUIPlugin)
   univer.registerPlugin(UniverDrawingPlugin)
   
   univer.registerPlugin(UniverLicensePlugin, {
     license: process.env.CLIENT_LICENSE_TEXT,
   })
   
   univer.registerPlugin(UniverSlidesPlugin)
   univer.registerPlugin(UniverSlidesUIPlugin)
   
   univer.createUnit(UniverInstanceType.UNIVER_SLIDE, {})
   
   const univerAPI = FUniver.newAPI(univer)
   ```

這裡返回的 `univerAPI` 物件被稱為 Univer 的 Facade API，透過它可以建立簡報並呼叫 Slides 相關能力。

#### `univer.registerPlugin` 與 `univer.registerPlugins` 方法

`univer.registerPlugin` 用於將外掛註冊到 Univer 實例。可於建立實例後呼叫。

使用方式：`univer.registerPlugin(Plugin, options)`，其中 `Plugin` 為外掛類別，`options` 為該外掛的（可選）設定。

亦可透過 `univer.registerPlugins` 傳入陣列，一次性註冊多個外掛，便於集中管理：

```typescript
univer.registerPlugins([
  UniverRenderEnginePlugin,
  [UniverUIPlugin, {
    container: 'app',
  }],
  UniverDocsPlugin,
  UniverDocsUIPlugin,
  UniverDrawingPlugin,
  [UniverLicensePlugin, {
    license: process.env.CLIENT_LICENSE_TEXT,
  }],
  UniverSlidesPlugin,
  UniverSlidesUIPlugin,
])
```

#### 可選功能套件

當編輯器需要對應能力時，再安裝功能套件：

```shell
pnpm add @univerjs-pro/slides-print
pnpm add @univerjs-pro/slides-table @univerjs-pro/slides-table-ui
pnpm add @univerjs-pro/chart-ui @univerjs-pro/slides-chart @univerjs-pro/slides-chart-ui
pnpm add @univerjs-pro/slides-exchange-client
```

功能註冊範例請參考 [列印](https://docs.univer.ai/zh-TW/guides/slides/features/print.md)、[表格](https://docs.univer.ai/zh-TW/guides/slides/features/tables.md)、[圖表](https://docs.univer.ai/zh-TW/guides/slides/features/charts.md) 和 [匯入匯出](https://docs.univer.ai/zh-TW/guides/slides/features/import-export.md)。

#### 懶載入部分外掛

插件模式的一個優勢是可以延遲載入可選功能：

```typescript
univer.createUnit(UniverInstanceType.UNIVER_SLIDE, {})

import('@univerjs-pro/slides-chart').then(({ UniverSlidesChartPlugin }) => {
  univer.registerPlugin(UniverSlidesChartPlugin)
})
```

### 服務端使用

在 Node.js 中，通常只註冊模型外掛，不註冊瀏覽器 UI 外掛：

```typescript
univer.registerPlugin(UniverSlidesPlugin)
```

模型外掛用於無頭快照處理。需要提供協同或檔案轉換介面時，請另外接入對應的 [Server SDK 模組](https://docs.univer.ai/zh-TW/server.md)；僅註冊此外掛不會建立這些服務。

## 行動裝置支援

> [!WARNING]
> 這些範例要求安裝的 SDK 套件包含下列行動版匯出。所有 `@univerjs/*` 與 `@univerjs-pro/*` 依賴應保持**相同版本**。
> 
> `1.0.0-rc.0` 尚未匯出 `UniverSlidesMobileUIPlugin`。使用以下範例前，請選擇已包含該行動版入口的建置版本。

在 Univer Slides 中使用**行動版 UI 外掛**提供觸控操作介面。[^mobile-ui-mode] 請在建立編輯器前選定 UI 模式。

在上方外掛模式範例中，**替換**以下 UI 外掛的匯入與註冊，並在 `createUnit()` 前完成；不要加到已初始化的桌面版編輯器中。保留模型外掛、引擎、語言套件、CSS 與 Facade 匯入。桌面版與行動版類別是**同一個套件入口**的不同具名匯出。

```typescript
import { UniverSlidesMobileUIPlugin } from '@univerjs-pro/slides-ui'
import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'
import { UniverMobileUIPlugin } from '@univerjs/ui'

univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })
univer.registerPlugin(UniverDocsMobileUIPlugin)
univer.registerPlugin(UniverSlidesMobileUIPlugin)
```

### 外掛對照

僅註冊所需功能，並保留其模型外掛與必要依賴。提供行動版 UI 匯出不代表兩端介面完全相同。Pro 功能仍需相應授權；需要後端的功能，請在業務應用程式中透過 [Univer Server SDK](https://docs.univer.ai/zh-TW/server.md) 接入相應能力。

| 套件                                       | 桌面版註冊                               | 行動版註冊                                     |
| ---------------------------------------- | ----------------------------------- | ----------------------------------------- |
| `@univerjs/ui`                           | `UniverUIPlugin`                    | `UniverMobileUIPlugin`                    |
| `@univerjs/docs-ui`                      | `UniverDocsUIPlugin`                | `UniverDocsMobileUIPlugin`                |
| `@univerjs-pro/slides-ui`                | `UniverSlidesUIPlugin`              | `UniverSlidesMobileUIPlugin`              |
| `@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-pro/slides-chart-ui`          | `UniverSlidesChartUIPlugin`         | `UniverSlidesChartMobileUIPlugin`         |
| `@univerjs-pro/slides-print`             | `UniverSlidesPrintPlugin`           | `UniverSlidesPrintMobilePlugin`           |
| `@univerjs-pro/slides-table-ui`          | `UniverSlidesTableUIPlugin`         | `UniverSlidesTableMobileUIPlugin`         |
| `@univerjs-pro/slides-thread-comment-ui` | `UniverSlidesThreadCommentUIPlugin` | `UniverSlidesThreadCommentMobileUIPlugin` |

### 容器與觸控互動

為容器指定明確高度，並設定頁面 viewport。`100dvh` 隨動態視口高度變化。請在目標行動瀏覽器上檢查捲動、雙指縮放、文字選取、剪貼簿存取與螢幕鍵盤彈出後的版面。僅縮小桌面版編輯器不會切換至行動版外掛。

`UniverMobileUIPlugin` 預設使用 `disableAutoFocus: true`，避免編輯器在初始化時自動取得焦點。

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

## 其他發佈版本

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

### Alpha / Beta 版本

當團隊完成新功能或重大調整，可能會預先發佈於 alpha 或 beta 通道。可用以下指令安裝：

#### npm

```bash
npm install @univerjs-pro/slides@alpha # Alpha 版本
npm install @univerjs-pro/slides@beta # Beta 版本
```

#### pnpm

```bash
pnpm add @univerjs-pro/slides@alpha # Alpha 版本
pnpm add @univerjs-pro/slides@beta # Beta 版本
```

#### yarn

```bash
yarn add @univerjs-pro/slides@alpha # Alpha 版本
yarn add @univerjs-pro/slides@beta # Beta 版本
```

#### bun

```bash
bun add @univerjs-pro/slides@alpha # Alpha 版本
bun add @univerjs-pro/slides@beta # Beta 版本
```

若於使用 alpha / beta 過程遇到問題或有建議，歡迎透過 [GitHub Issues](https://github.com/dream-num/univer/issues) 回報。

祝你搶先體驗愉快！

## 下一步

* 在 [Facade API](https://docs.univer.ai/zh-TW/guides/slides/getting-started/facade.md) 中了解如何透過 Facade API 操作 Slides。
* [授權設定](https://docs.univer.ai/zh-TW/server/license.md)
* [Server SDK 整合](https://docs.univer.ai/zh-TW/server.md)
* 按需接入 [功能](https://docs.univer.ai/zh-TW/guides/slides/features/print.md) 章節中的外掛。

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

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

[^mobile-ui-mode]: 行動版 UI 外掛在初始化時選擇觸控元件與行動版服務，不會自動判斷裝置，也不會在視窗大小改變時切換既有實例。如需切換模式，請先保留文件狀態、銷毀舊實例，再以選定的外掛組合初始化。