安裝與基本使用

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

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

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

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

透過外掛模式建立

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

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

使用套件管理器

安裝

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

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 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 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 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

使用

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'

   展開程式碼

2. 若需使用 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'

3. 建立 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)

   展開程式碼

univer.registerPlugin 與 univer.registerPlugins 方法

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

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

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

univer.registerPlugins([  UniverRenderEnginePlugin,  UniverFormulaEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,  UniverSheetsPlugin,  UniverSheetsUIPlugin,  UniverSheetsFormulaPlugin,  UniverSheetsFormulaUIPlugin,  UniverSheetsNumfmtPlugin,  UniverSheetsNumfmtUIPlugin,])

懶載入部分外掛

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

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

Univer 的官方範例 即採此優化技巧，可供參考。

行動裝置支援

在 Univer Sheets 中使用行動版 UI 外掛提供觸控操作介面。⁶ 請在建立編輯器前選定 UI 模式。

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

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

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 接入相應能力。

容器與觸控互動

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

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

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

透過 CDN 使用 Univer

若不想使用套件管理器，或僅需快速試用，可透過 CDN 引入資源。詳見透過 CDN 使用 Univer。

透過預設模式建立

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

使用套件管理器

若你的專案已採用現代前端建置工具，導入 Univer 會非常簡單。我們推薦使用 Vite、esbuild 或 Webpack 5 等對 ES Module 支援良好的建置工具。若使用較舊工具（如 Webpack 4），可能需要額外設定。

安裝

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

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

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

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

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

使用

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

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

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，你可透過它呼叫眾多功能。

createUniver 方法

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

主要屬性說明（節錄）：

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

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

透過 CDN 使用 Univer

若不想使用套件管理器，或只想快速試用，可透過 CDN 引入相關資源。詳見透過 CDN 使用 Univer。

其他發佈版本

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

Alpha / Beta 版本

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

pnpm add @univerjs/<package-name>@alpha # Alpha 版本
pnpm add @univerjs/<package-name>@beta # Beta 版本

npm install @univerjs/<package-name>@alpha # Alpha 版本
npm install @univerjs/<package-name>@beta # Beta 版本

yarn add @univerjs/<package-name>@alpha # Alpha 版本
yarn add @univerjs/<package-name>@beta # Beta 版本

bun add @univerjs/<package-name>@alpha # Alpha 版本
bun add @univerjs/<package-name>@beta # Beta 版本

若於使用 alpha / beta 過程遇到問題或有建議，歡迎透過 GitHub Issues 回報。

祝你搶先體驗愉快！

下一步

• 前往 基礎概念 了解本章提到的外掛、命令與 Facade API 等概念。
• 於 功能 相關章節了解修改試算表資料的各項操作。