安裝與基本使用

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

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

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

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

透過外掛模式建立

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

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

使用套件管理器

安裝

Univer 使用 React 建構介面、RxJS 處理資料流，也可以嵌入 Vue 或 Angular 應用程式。請確認已安裝 react、react-dom 和 rxjs 這些 peer dependencies²；下方 Yarn 指令已明確包含它們。

所有 @univerjs/* 和 @univerjs-pro/* 套件應保持相同版本。

pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

yarn add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui react react-dom rxjs

bun add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/ui

使用

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

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

呼叫 FUniver.newAPI(univer) 前，請引入下方範例使用的 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'

2. 引入示例中使用到的 facade 包：

   TypeScript

   import '@univerjs/engine-formula/facade'import '@univerjs/ui/facade'import '@univerjs/docs/facade'import '@univerjs/docs-ui/facade'

3. 然後建立一個 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({})

   展開程式碼

univer.registerPlugin 與 univer.registerPlugins 方法

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

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

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

univer.registerPlugins([  UniverRenderEnginePlugin,  UniverFormulaEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,])

懶載入部分外掛

使用外掛模式的一個優勢是你可以更加靈活地控制外掛的載入時機，一種常見的方式是在應用初始化時僅載入必須的外掛，而將部分外掛的載入時機延遲到首次渲染完成之後。

// ...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。

行動裝置支援

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

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

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

容器與觸控互動

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

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

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

透過預設模式建立

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

使用包管理器

如果你的專案中已經引入了現代前端開發工具，那麼引入 Univer 將會非常簡單。我們推薦使用 Vite、esbuild 或 Webpack 5 等對 ES Module 支援較好的構建工具來構建 Univer 應用。如果你使用了其它構建工具（例如 Webpack 4），可能會需要一些額外的配置。

安裝

選擇你所使用的包管理器以安裝 @univerjs/presets：

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

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

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

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

使用

透過以下程式碼，你就可以快速建立一個 Univer Docs 應用：

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

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 提供的許多功能。

createUniver 方法

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

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

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

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

透過 CDN 使用 Univer

如果你不想使用包管理器，或者只是想快速嘗試 Univer 的功能，你可以透過 CDN 引入 Univer 的相關資源。詳情請參考 透過 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 等概念。
• 在 功能 相關章節中瞭解修改文件內容的所有操作。