Web SDK

安裝與基本使用

本章介紹 Univer Boards 的安裝方式與基本用法。Boards 是 Univer Office SDK 產品，目前採用外掛程式模式提供。

如果不熟悉 Univer 的核心概念，請先閱讀快速入門。

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

透過外掛模式建立

Univer 以一組外掛程式的形式提供 Boards。瀏覽器編輯器通常會依序註冊共用的 Univer 執行環境、授權外掛程式、文件與繪圖相依套件，接著再註冊 Board 模型和 UI 外掛程式。

使用套件管理器

使用支援 ES Module 和 package.json 中 exports 欄位的建置工具。

安裝

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

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

Shell
pnpm add @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/drawing @univerjs/drawing-ui @univerjs/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/ink-ui @univerjs-pro/shape-editor-ui @univerjs-pro/boards @univerjs-pro/boards-ui

使用

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

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

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

注意

  • 請先註冊 UniverLicensePlugin，再註冊 Board 外掛程式。
  • 請先匯入共用 UI CSS，再匯入產品 UI CSS。
  • 開啟含有選用元素類型的快照前，請先註冊對應的元素外掛程式。
  • UniverBoardsUIPlugin 會為形狀功能自動載入 UniverProFormulaEnginePlugin。如果同一個 Univer 執行個體還註冊了 UniverFormulaEnginePlugin，請安裝 @univerjs-pro/engine-formula，並在初始化程式碼中將一般引擎的匯入與註冊替換為 UniverProFormulaEnginePlugin。請勿同時註冊兩個公式引擎。

  1. 匯入樣式、語系套件和必要的外掛程式：

    TypeScript
    import { UniverBoardsPlugin } from '@univerjs-pro/boards'import { UniverBoardsUIPlugin } from '@univerjs-pro/boards-ui'import BoardsUIEnUS from '@univerjs-pro/boards-ui/locale/en-US'import { UniverInkUIPlugin } from '@univerjs-pro/ink-ui'import InkUIZhTW from '@univerjs-pro/ink-ui/locale/zh-TW'import { UniverLicensePlugin } from '@univerjs-pro/license'import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'import DesignEnUS from '@univerjs/design/locale/en-US'import { UniverDocsPlugin } from '@univerjs/docs'import { UniverDocsUIPlugin } from '@univerjs/docs-ui'import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US'import { UniverDrawingPlugin } from '@univerjs/drawing'import { UniverDrawingUIPlugin } from '@univerjs/drawing-ui'import DrawingUIEnUS from '@univerjs/drawing-ui/locale/en-US'import { UniverRenderEnginePlugin } from '@univerjs/engine-render'import { UniverUIPlugin } from '@univerjs/ui'import UIEnUS from '@univerjs/ui/locale/en-US'import '@univerjs/design/lib/index.css'import '@univerjs/ui/lib/index.css'import '@univerjs/docs-ui/lib/index.css'import '@univerjs/drawing-ui/lib/index.css'import '@univerjs-pro/ink-ui/lib/index.css'import '@univerjs-pro/boards-ui/lib/index.css'

  2. 如要使用 Facade API2，請匯入 Facade 進入點：

    TypeScript
    import { FUniver } from '@univerjs/core/facade'import '@univerjs-pro/boards/facade'

  3. 建立 Univer 執行個體、註冊外掛程式，並建立 Board 單元：

    TypeScript
    const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      DocsUIEnUS,      DrawingUIEnUS,      InkUIZhTW,      BoardsUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverDrawingUIPlugin)univer.registerPlugin(UniverInkUIPlugin)univer.registerPlugin(UniverLicensePlugin, {  license: process.env.CLIENT_LICENSE_TEXT,})univer.registerPlugin(UniverBoardsPlugin)univer.registerPlugin(UniverBoardsUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_BOARD, {})const univerAPI = FUniver.newAPI(univer)

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,  UniverDrawingUIPlugin,  UniverInkUIPlugin,  [UniverLicensePlugin, {    license: process.env.CLIENT_LICENSE_TEXT,  }],  UniverBoardsPlugin,  UniverBoardsUIPlugin,])

FUniver.newAPI(univer) 傳回的 univerAPI 物件就是 Univer 的 Facade API。您可以使用它建立白板及操作白板元素。

行動裝置支援

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

1.0.0-rc.0 尚未匯出 UniverBoardsMobileUIPlugin。使用以下範例前，請選擇已包含該行動版入口的建置版本。

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

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

TypeScript
import { UniverBoardsMobileUIPlugin } from '@univerjs-pro/boards-ui'import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'import { UniverDrawingMobileUIPlugin } from '@univerjs/drawing-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsMobileUIPlugin)univer.registerPlugin(UniverDrawingMobileUIPlugin)univer.registerPlugin(UniverBoardsMobileUIPlugin)

外掛對照

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

套件桌面版註冊行動版註冊
@univerjs/uiUniverUIPluginUniverMobileUIPlugin
@univerjs/docs-uiUniverDocsUIPluginUniverDocsMobileUIPlugin
@univerjs/drawing-uiUniverDrawingUIPluginUniverDrawingMobileUIPlugin
@univerjs-pro/boards-uiUniverBoardsUIPluginUniverBoardsMobileUIPlugin
@univerjs/thread-comment-uiUniverThreadCommentUIPluginUniverThreadCommentMobileUIPlugin
@univerjs-pro/shape-editor-uiUniverShapeEditorUIPluginUniverShapeEditorMobileUIPlugin
@univerjs-pro/chart-uiUniverChartUIPluginUniverChartMobileUIPlugin
@univerjs-pro/exchange-clientUniverExchangeClientPluginUniverExchangeClientMobileUIPlugin
@univerjs-pro/boards-chart-uiUniverBoardsChartUIPluginUniverBoardsChartMobileUIPlugin
@univerjs-pro/boards-mind-uiUniverBoardsMindUIPluginUniverBoardsMindMobileUIPlugin
@univerjs-pro/boards-resources-uiUniverBoardsResourcesUIPluginUniverBoardsResourcesMobileUIPlugin
@univerjs-pro/boards-table-uiUniverBoardsTableUIPluginUniverBoardsTableMobileUIPlugin
@univerjs-pro/boards-thread-comment-uiUniverBoardsThreadCommentUIPluginUniverBoardsThreadCommentMobileUIPlugin

容器與觸控互動

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

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

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

選用功能套件

當 Board 編輯器需要對應的元素類型時，請加入相關功能套件：

Shell
pnpm add @univerjs-pro/boards-table @univerjs-pro/boards-table-uipnpm add @univerjs-pro/boards-mind @univerjs-pro/boards-mind-ui

如需功能註冊範例，請參閱表格、心智圖和匯入匯出。

其他發佈版本

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

Alpha / Beta 版本

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

Shell
pnpm add @univerjs-pro/boards@alpha # Alpha 版本
pnpm add @univerjs-pro/boards@beta # Beta 版本

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

祝你搶先體驗愉快！

下一步

Footnotes

  1. peerDependencies 表示需要由宿主專案提供相容版本的相依套件，讓 Univer 與應用程式共用 React 等函式庫，而不是各自攜帶一份。 ↩

  2. Facade 是面向應用程式的 API，封裝已註冊外掛的能力。匯入 Facade 入口會擴充 API 方法，但不會取代功能外掛的註冊。 ↩

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

你覺得這篇文檔如何？

© 2026 DreamNum Co., Ltd.