# 安裝與基本使用

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

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

---

Univer 採用外掛化的設計理念，旨在為開發者提供一個彈性、可擴充的電子文件應用框架。透過外掛式設計，Univer 能輕鬆整合各類功能模組，以滿足不同使用者的需求。但此種設計也提高了應用的複雜度，尤其對初次接觸 Univer 的開發者來說可能較陌生。

為此，Univer 提供 **外掛模式** 與 **預設模式** 兩種方式協助你快速整合與使用。所謂「預設」其實就是一組預先配置好的外掛組合；在無需進行進階擴充的情況下，兩種模式能提供的能力是等同的。

> [!WARNING: 注意事項]
> * **相依套件版本需一致**：無論使用預設模式或外掛模式，請務必確保所有相依套件的版本號保持一致。
> * **謹慎混用外掛與預設**：若某個外掛已被某個預設包含，使用該預設時就不需再額外單獨引入，否則可能導致衝突或功能異常。

預設模式與外掛模式的差異：

| 外掛模式                | 預設模式               |
| ------------------- | ------------------ |
| 需要手動引入對應的 Facade 套件 | 無需手動引入任何 Facade 套件 |
| 需注意同類型功能外掛的註冊順序     | 預設內已處理註冊順序，無需關注    |
| 支援按需（懶）載入           | 設定的預設會在初始化時同步載入    |

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

## 透過外掛模式建立

Univer 以外掛形式提供多種功能。除核心必要外掛外，你可按需求選擇性導入。以下以最基礎的 Univer Sheets 應用示範手動組合安裝。

與預設模式不同，外掛模式預設不包含 Facade API[^facade-entry]；下列程式碼中 Facade 相關部分皆為可選，可按需求移除。

### 使用套件管理器

#### 安裝

Univer 以 React 建構視圖（仍可在 Vue / Angular 中使用），並使用 RxJS 處理資料流。由於兩者在現代前端普及，我們將其列為 peerDependencies[^peer-dependency]。不同套件管理器對 peerDependencies 行為不同，需注意細節。

> [!NOTE]
> * 使用 npm：請確保版本為 npm\@7 以上；npm\@3 \~ npm\@6 不會正確安裝 `peerDependencies`。[^1]
> * 使用 pnpm：請使用 pnpm\@8 以上；若為 pnpm\@6 \~ pnpm\@7，可設定 `auto-install-peers=true`[^2]。
> * 使用 yarn：需手動安裝缺少的 `peerDependencies`[^3]；以下指令已納入。

#### pnpm

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

#### npm

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

#### yarn

```shell
yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/sheets @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui @univerjs/sheets-ui @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/sheets @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui @univerjs/sheets-ui @univerjs/ui
```

#### 使用

> [!WARNING: 注意事項]
> * 非所有外掛皆包含 Facade 套件、語系包與樣式；各功能文件會個別說明。
> * 樣式檔引入順序很重要：請先依序引入 `@univerjs/design`、`@univerjs/ui` 的 CSS，再引入其他外掛樣式。

1.
   在專案中引入樣式、語系與必要外掛：
   
   ```typescript
   import { LocaleType, mergeLocales, Univer, UniverInstanceType } 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 { UniverSheetsPlugin } from '@univerjs/sheets'
   import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'
   import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'
   import SheetsFormulaUIZhTW from '@univerjs/sheets-formula-ui/locale/zh-TW'
   import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'
   import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'
   import SheetsNumfmtUIZhTW from '@univerjs/sheets-numfmt-ui/locale/zh-TW'
   import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'
   import SheetsUIZhTW from '@univerjs/sheets-ui/locale/zh-TW'
   import SheetsZhTW from '@univerjs/sheets/locale/zh-TW'
   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/sheets-ui/lib/index.css'
   import '@univerjs/sheets-formula-ui/lib/index.css'
   import '@univerjs/sheets-numfmt-ui/lib/index.css'
   ```

1.
   若需使用 Facade API，可選擇引入以下 Facade 套件（建議引入）：
   
   ```typescript
   import '@univerjs/engine-formula/facade'
   import '@univerjs/ui/facade'
   import '@univerjs/docs-ui/facade'
   import '@univerjs/sheets/facade'
   import '@univerjs/sheets-ui/facade'
   import '@univerjs/sheets-formula/facade'
   import '@univerjs/sheets-numfmt/facade'
   ```

1.
   建立 Univer 實例並註冊外掛：
   
   ```typescript
   const univer = new Univer({
     locale: LocaleType.ZH_TW,
     locales: {
       [LocaleType.ZH_TW]: mergeLocales(
         DesignZhTW,
         UIZhTW,
         DocsUIZhTW,
         SheetsZhTW,
         SheetsUIZhTW,
         SheetsFormulaUIZhTW,
         SheetsNumfmtUIZhTW,
       ),
     },
   })
   
   univer.registerPlugin(UniverRenderEnginePlugin)
   univer.registerPlugin(UniverFormulaEnginePlugin)
   
   univer.registerPlugin(UniverUIPlugin, {
     container: 'app',
   })
   
   univer.registerPlugin(UniverDocsPlugin)
   univer.registerPlugin(UniverDocsUIPlugin)
   
   univer.registerPlugin(UniverSheetsPlugin)
   univer.registerPlugin(UniverSheetsUIPlugin)
   univer.registerPlugin(UniverSheetsFormulaPlugin)
   univer.registerPlugin(UniverSheetsFormulaUIPlugin)
   univer.registerPlugin(UniverSheetsNumfmtPlugin)
   univer.registerPlugin(UniverSheetsNumfmtUIPlugin)
   
   univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})
   
   const univerAPI = FUniver.newAPI(univer)
   ```

> Interactive example: [Open the playground](/playground/sheets/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,
  UniverSheetsPlugin,
  UniverSheetsUIPlugin,
  UniverSheetsFormulaPlugin,
  UniverSheetsFormulaUIPlugin,
  UniverSheetsNumfmtPlugin,
  UniverSheetsNumfmtUIPlugin,
])
```

#### 懶載入部分外掛

外掛模式的優勢之一是可更靈活控制載入時機。常見策略：初始化時僅載入必要外掛，將其他外掛延後至首次渲染後再載入。

```typescript
// ...

univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})

import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {
  univer.registerPlugin(UniverWatermarkPlugin, {
    textWatermarkSettings: {
      content: 'Hello, Univer!',
      fontSize: 36,
    },
  })
})
```

Univer 的[官方範例](https://github.com/dream-num/univer/blob/0d849012594882307186f33734b8b89d80a729e9/examples/src/sheets/main.ts) 即採此優化技巧，可供參考。

### 行動裝置支援

> [!WARNING]
> 這些範例要求安裝的 SDK 套件包含下列行動版匯出。所有 `@univerjs/*` 與 `@univerjs-pro/*` 依賴應保持**相同版本**。

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

Sheets 行動版支援仍屬**實驗性質**，請在目標裝置上驗證應用程式實際使用的功能。

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

```typescript
import { UniverSheetsFormulaMobileUIPlugin } from '@univerjs/sheets-formula-ui'
import { UniverSheetsNumfmtMobileUIPlugin } from '@univerjs/sheets-numfmt-ui'
import { UniverSheetsMobileUIPlugin } from '@univerjs/sheets-ui'
import { UniverMobileUIPlugin } from '@univerjs/ui'

univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })
univer.registerPlugin(UniverSheetsMobileUIPlugin)
univer.registerPlugin(UniverSheetsFormulaMobileUIPlugin)
univer.registerPlugin(UniverSheetsNumfmtMobileUIPlugin)
```

**Sheets 中請保留 `UniverDocsUIPlugin`。** `UniverSheetsMobileUIPlugin` 依賴它提供儲存格內的文件編輯功能。獨立的 Docs 編輯器才使用 `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/sheets-ui`                        | `UniverSheetsUIPlugin`                      | `UniverSheetsMobileUIPlugin`                      |
| `@univerjs/sheets-formula-ui`                | `UniverSheetsFormulaUIPlugin`               | `UniverSheetsFormulaMobileUIPlugin`               |
| `@univerjs/sheets-numfmt-ui`                 | `UniverSheetsNumfmtUIPlugin`                | `UniverSheetsNumfmtMobileUIPlugin`                |
| `@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/sheets-conditional-formatting-ui` | `UniverSheetsConditionalFormattingUIPlugin` | `UniverSheetsConditionalFormattingMobileUIPlugin` |
| `@univerjs/sheets-crosshair-highlight`       | `UniverSheetsCrosshairHighlightPlugin`      | `UniverSheetsCrosshairHighlightMobileUIPlugin`    |
| `@univerjs/sheets-data-validation-ui`        | `UniverSheetsDataValidationUIPlugin`        | `UniverSheetsDataValidationMobileUIPlugin`        |
| `@univerjs/sheets-drawing-ui`                | `UniverSheetsDrawingUIPlugin`               | `UniverSheetsDrawingMobileUIPlugin`               |
| `@univerjs/sheets-filter-ui`                 | `UniverSheetsFilterUIPlugin`                | `UniverSheetsFilterMobileUIPlugin`                |
| `@univerjs/sheets-find-replace`              | `UniverSheetsFindReplacePlugin`             | `UniverSheetsFindReplaceMobileUIPlugin`           |
| `@univerjs/sheets-hyper-link-ui`             | `UniverSheetsHyperLinkUIPlugin`             | `UniverSheetsHyperLinkMobileUIPlugin`             |
| `@univerjs/sheets-sort-ui`                   | `UniverSheetsSortUIPlugin`                  | `UniverSheetsSortMobileUIPlugin`                  |
| `@univerjs/sheets-table-ui`                  | `UniverSheetsTableUIPlugin`                 | `UniverSheetsTableMobileUIPlugin`                 |
| `@univerjs/sheets-thread-comment-ui`         | `UniverSheetsThreadCommentUIPlugin`         | `UniverSheetsThreadCommentMobileUIPlugin`         |
| `@univerjs-pro/sheets-chart-ui`              | `UniverSheetsChartUIPlugin`                 | `UniverSheetsChartMobileUIPlugin`                 |
| `@univerjs-pro/sheets-exchange-client`       | `UniverSheetsExchangeClientPlugin`          | `UniverSheetsExchangeClientMobileUIPlugin`        |
| `@univerjs-pro/sheets-history-ui`            | `UniverSheetsHistoryUIPlugin`               | `UniverSheetsHistoryMobileUIPlugin`               |
| `@univerjs-pro/sheets-outline-ui`            | `UniverSheetsOutlineUIPlugin`               | `UniverSheetsOutlineMobileUIPlugin`               |
| `@univerjs-pro/sheets-pivot-ui`              | `UniverSheetsPivotTableUIPlugin`            | `UniverSheetsPivotTableMobileUIPlugin`            |
| `@univerjs-pro/sheets-print`                 | `UniverSheetsPrintPlugin`                   | `UniverSheetsPrintMobileUIPlugin`                 |
| `@univerjs-pro/sheets-shape-ui`              | `UniverSheetsShapeUIPlugin`                 | `UniverSheetsShapeMobileUIPlugin`                 |
| `@univerjs-pro/sheets-sparkline-ui`          | `UniverSheetSparklineUIPlugin`              | `UniverSheetSparklineMobileUIPlugin`              |
| `@univerjs/find-replace`                     | `UniverFindReplacePlugin`                   | `UniverFindReplaceMobileUIPlugin`                 |

#### 容器與觸控互動

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

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

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

> Interactive example: [Open the playground](/playground/sheets/mobile-via-plugin)

### 透過 CDN 使用 Univer

若不想使用套件管理器，或僅需快速試用，可透過 CDN 引入資源。詳見[透過 CDN 使用 Univer](https://docs.univer.ai/zh-TW/guides/sheets/getting-started/installation/cdn.md#plugin-mode)。

## 透過預設模式建立

以下示範如何用不到二十行程式碼快速搭建一個 Univer Sheets 應用。

### 使用套件管理器

若你的專案已採用現代前端建置工具，導入 Univer 會非常簡單。我們推薦使用 [Vite](https://vitejs.dev/)、[esbuild](https://esbuild.github.io/) 或 [Webpack 5](https://webpack.js.org/) 等對 ES Module 支援良好的建置工具。若使用較舊工具（如 Webpack 4），可能需要額外設定。

#### 安裝

選擇你使用的套件管理器安裝 `@univerjs/presets`：

#### npm

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

#### pnpm

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

#### yarn

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

#### bun

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

#### 使用

> [!WARNING]
> 若建置工具不支援 package.json 的 `exports` 欄位（常見於 Webpack 4），需手動調整對應的匯入路徑。

以下程式碼可快速建立一個 Univer Sheets 應用：

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

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

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

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

univerAPI.createWorkbook({})
```

此處回傳的 `univerAPI` 物件即為 Univer 的 Facade API，你可透過它呼叫眾多功能。

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

> [!WARNING]
> 你也可改用 `@univerjs/presets/preset-sheets-core` 匯入 `UniverSheetsCorePreset`，但必須確保建置工具支援 `package.json` 的 `exports`。

#### `createUniver` 方法

`createUniver` 接受一組設定物件，包含語系、主題、預設、外掛等資訊。其回傳物件內含 Univer 實例與 Facade API。

主要屬性說明（節錄）：

* `locale`：語系，為 `LocaleType` 列舉值。
* `locales`：語系包對應物件，鍵為語系代碼、值為語系包。
* `theme`：主題（可選）。
* `presets`：預設（preset）陣列，例如 `UniverSheetsCorePreset`。
* `plugins`：額外註冊的外掛陣列。

若使用的外掛不在任何預設中，或為自行實作，可透過 `plugins` 註冊，或於取得實例後使用 `univer.registerPlugin`。

> [!NOTE]
> 參見 [API Reference / createUniver](https://docs.univer.ai/zh-TW/reference/methods/create-univer.md) 取得更多細節。

### 透過 CDN 使用 Univer

若不想使用套件管理器，或只想快速試用，可透過 CDN 引入相關資源。詳見[透過 CDN 使用 Univer](https://docs.univer.ai/zh-TW/guides/sheets/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/sheets/getting-started/quickstart.md#basic-concepts) 了解本章提到的外掛、命令與 Facade API 等概念。
* 於 [功能](https://docs.univer.ai/zh-TW/guides/sheets/features/core.md) 相關章節了解修改試算表資料的各項操作。

***

[^1]: [https://blog.npmjs.org/post/110924823920/npm-weekly-5](https://blog.npmjs.org/post/110924823920/npm-weekly-5)

[^2]: [https://pnpm.io/npmrc#auto-install-peers](https://pnpm.io/npmrc#auto-install-peers)

[^3]: [https://github.com/yarnpkg/yarn/issues/1503](https://github.com/yarnpkg/yarn/issues/1503)

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

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

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