# 安裝與基本使用

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

Univer 採用了外掛化的設計理念，旨在為開發者提供一個靈活、可擴充的電子文件應用框架。透過外掛化設計，Univer 可以輕鬆地整合各種功能模組，從而滿足不同使用者的需求。但外掛化的設計會增加應用的複雜性，尤其是對於首次接觸 Univer 的開發者來說。

為此，Univer 提供了**外掛模式**和**預設模式**兩種方式幫助你快速整合和使用 Univer。所謂**預設**實際上就是一組預先配置好的外掛組合，因此在無需進行復雜擴充的情況下，兩者所提供的能力是相同的。

> [!WARNING: 注意事項]
> * **依賴版本需一致**：無論是使用預設模式還是外掛模式的方式，你都必須保證所有依賴的版本號一致。
> * **謹慎混用外掛和預設**：如果一個外掛已經被包含在某個預設中，那麼在使用預設時就不需要再單獨引入該外掛了。否則可能會導致外掛衝突或功能異常。

預設模式與外掛模式的區別：

| 外掛模式               | 預設模式               |
| ------------------ | ------------------ |
| 需要手動引入對應的 facade 包 | 無需手動引入任何 facade 包  |
| 需要注意同型別功能外掛註冊順序    | 同功能被包含在預設中無需關注註冊順序 |
| 支援按需懶載入            | 設定的預設會在初始化時同步載入    |

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

## 透過外掛模式建立

Univer 以外掛的形式提供了一系列功能，除了一些產品所必需的核心外掛外，你還可以根據需要選擇性地引入其它外掛。這裡僅以最基礎的 Univer Docs 應用為例，介紹如何手動組合安裝外掛。

與預設模式不同，外掛模式預設並不包含 Facade API[^facade-entry]。下面的示例會使用 Facade API，因此需要在建立 API 例項前引入對應的 facade 包。

### 使用套件管理器

#### 安裝

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/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 入口。樣式依 `@univerjs/design`、`@univerjs/ui`、產品 CSS 的順序引入。

> [!WARNING: 注意事項]
> * 並非所有的外掛都包含了 facade 包、語言包和樣式檔案，我們會在每個功能的文件對此進行說明。
> * 樣式檔案的引入順序很重要，確保你在依次引入 `@univerjs/design`、`@univerjs/ui` 的 CSS 樣式後再引入其他外掛的樣式檔案。

1.
   你需要在專案中引入 Univer 的樣式檔案、語言包，以及一些必要的外掛：
   
   ```typescript
   import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
   import { FUniver } from '@univerjs/core/facade'
   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 { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'
   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'
   ```

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.ZH_TW,
     locales: {
       [LocaleType.ZH_TW]: mergeLocales(
         DesignZhTW,
         UIZhTW,
         DocsUIZhTW,
       ),
     },
   })
   
   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.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

如果你不想使用包管理器，或者只是想快速嘗試 Univer 的功能，你可以透過 CDN 引入 Univer 的相關資源。詳情請參考 [透過 CDN 使用 Univer](https://docs.univer.ai/zh-TW/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/zh-TW/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>
```

## 透過預設模式建立

在這裡我們將簡單介紹下如何透過不到二十行的程式碼來快速搭建一個 Univer Docs 應用。

### 使用包管理器

如果你的專案中已經引入了現代前端開發工具，那麼引入 Univer 將會非常簡單。我們推薦使用 [Vite](https://vitejs.dev/)、[esbuild](https://esbuild.github.io/) 或 [Webpack 5](https://webpack.js.org/) 等對 ES Module 支援較好的構建工具來構建 Univer 應用。如果你使用了其它構建工具（例如 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 UniverPresetDocsCoreZhTW from '@univerjs/preset-docs-core/locales/zh-TW'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-docs-core/lib/index.css'

const { univer, univerAPI } = createUniver({
  locale: LocaleType.ZH_TW,
  locales: {
    [LocaleType.ZH_TW]: mergeLocales(
      UniverPresetDocsCoreZhTW,
    ),
  },
  presets: [
    UniverDocsCorePreset({
      container: 'app',
    }),
  ],
})

univerAPI.createDocument({})
```

這裡返回的 `univerAPI` 物件被稱為 Univer 的面板 API（Facade API），透過它可以呼叫 Univer 提供的許多功能。

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

> [!WARNING]
> 你也可以透過 `@univerjs/presets/preset-docs-core` 來引入 `UniverDocsCorePreset`，但必須確保你的構建工具支援 `package.json` 的 `exports` 欄位。

#### `createUniver` 方法

`createUniver` 方法接受一個配置物件，其中包含了 Univer 的配置資訊，例如語言、主題、外掛等。這個方法會返回一個包含了 Univer 例項和 Univer Facade API 例項的物件。

配置物件的部分屬性如下：

* `locale`：語言環境，可以是 `LocaleType` 列舉值。
* `locales`：語言包，一個物件，鍵為語言環境，值為語言包物件。
* `theme`：主題，一個可選主題物件。
* `presets`：一個 preset 陣列，包含了需要註冊的預設包，例如 `UniverDocsCorePreset`。
* `plugins`：一個外掛陣列，包含了需要額外註冊的外掛。

當你使用了一個未包含在任何預設包中的外掛或者你自己實現了一個外掛時，可以透過 `plugins` 屬性來註冊這些外掛。也可以選擇在獲得 Univer 例項後透過 `univer.registerPlugin` 方法來註冊外掛。

> [!NOTE]
> 你可以在 [API Reference / createUniver](https://docs.univer.ai/zh-TW/reference/methods/create-univer.md) 找到更多關於 `createUniver` 方法的詳細資訊。

### 透過 CDN 使用 Univer

如果你不想使用包管理器，或者只是想快速嘗試 Univer 的功能，你可以透過 CDN 引入 Univer 的相關資源。詳情請參考 [透過 CDN 使用 Univer](https://docs.univer.ai/zh-TW/guides/docs/getting-started/installation/cdn.md#plugin-mode)。

## 其他發佈版本

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

### Alpha / Beta 版本

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

祝你搶先體驗愉快！

## 下一步

* 在 [基礎概念](https://docs.univer.ai/zh-TW/guides/docs/getting-started/quickstart.md#basic-concepts) 章節瞭解本章中出現的外掛、命令和 Facade API 等概念。
* 在 [功能](https://docs.univer.ai/zh-TW/guides/docs/features/core.md) 相關章節中瞭解修改文件內容的所有操作。

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

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

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