Web SDK

安装和基本使用

本章介绍 Univer Slides 的安装与基本使用。本指南使用 Web SDK 的 Slides 包。目前没有 Slides 预设，因此需要通过插件模式创建 Slides 应用。

如果你还不熟悉 Univer 的基础概念，建议先阅读 快速开始。

Univer 提供预设模式和插件模式两种集成方式。预设模式通过预先组合好的插件简化配置，上手更简单；如果需要深度扩展，推荐使用插件模式，按需组合和配置插件。

通过插件模式创建

Univer 以插件的形式提供 Slides 能力。一个浏览器端编辑器通常需要先注册 Univer 通用运行时、授权插件、Docs 与 Drawing 依赖，然后再注册 Slides 的模型和 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/engine-render @univerjs/ui @univerjs-pro/license @univerjs-pro/slides @univerjs-pro/slides-ui

使用

初始化 Univer 前，先创建容器并设置明确的高度：

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

调用 FUniver.newAPI(univer) 前，请引入下方示例使用的 facade 入口。样式按 @univerjs/design、@univerjs/ui、产品 CSS 的顺序引入。

注意事项

  • 注册 Slides 插件前，需要先注册 UniverLicensePlugin。
  • 样式文件的引入顺序很重要，请先引入通用 UI 样式，再引入产品 UI 样式。
  • 打印、表格、图表、导入导出等可选功能包，只在产品需要对应能力时再加入。
  • UniverSlidesUIPlugin 会为形状功能自动加载 UniverProFormulaEnginePlugin。如果同一个 Univer 实例还注册了 UniverFormulaEnginePlugin，请安装 @univerjs-pro/engine-formula，并在初始化代码中将普通引擎的导入和注册替换为 UniverProFormulaEnginePlugin。不要同时注册两个公式引擎。

  1. 引入样式文件、语言包和必要插件：

    TypeScript
    import { UniverLicensePlugin } from '@univerjs-pro/license'import { UniverSlidesPlugin } from '@univerjs-pro/slides'import { UniverSlidesUIPlugin } from '@univerjs-pro/slides-ui'import SlidesUIZhCN from '@univerjs-pro/slides-ui/locale/zh-CN'import SlidesZhCN from '@univerjs-pro/slides/locale/zh-CN'import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'import DesignZhCN from '@univerjs/design/locale/zh-CN'import { UniverDocsPlugin } from '@univerjs/docs'import { UniverDocsUIPlugin } from '@univerjs/docs-ui'import DocsUIZhCN from '@univerjs/docs-ui/locale/zh-CN'import { UniverDrawingPlugin } from '@univerjs/drawing'import { UniverRenderEnginePlugin } from '@univerjs/engine-render'import { UniverUIPlugin } from '@univerjs/ui'import UIZhCN from '@univerjs/ui/locale/zh-CN'import '@univerjs/design/lib/index.css'import '@univerjs/ui/lib/index.css'import '@univerjs/docs-ui/lib/index.css'import '@univerjs-pro/slides-ui/lib/index.css'

  2. 如果需要使用 Facade API2，可以引入相关 facade 入口：

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

  3. 创建 Univer 实例，注册插件，并创建 Slides unit：

    TypeScript
    const univer = new Univer({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      DesignZhCN,      UIZhCN,      DocsUIZhCN,      SlidesZhCN,      SlidesUIZhCN,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverUIPlugin, {  container: 'app',})univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)univer.registerPlugin(UniverDrawingPlugin)univer.registerPlugin(UniverLicensePlugin, {  license: process.env.CLIENT_LICENSE_TEXT,})univer.registerPlugin(UniverSlidesPlugin)univer.registerPlugin(UniverSlidesUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_SLIDE, {})const univerAPI = FUniver.newAPI(univer)

这里返回的 univerAPI 对象被称为 Univer 的面板 API（Facade API），通过它可以创建演示文稿并调用 Slides 相关能力。

univer.registerPlugin 与 univer.registerPlugins 方法

univer.registerPlugin 方法用于注册一个插件到 Univer 实例中。你可以在创建 Univer 实例后调用这个方法来注册插件。

你可以通过 univer.registerPlugin(Plugin, options) 的方式来注册插件，其中 Plugin 是要注册的插件，options 是可选的配置项，每个插件可能有不同的配置项。

你也可以通过 univer.registerPlugins 传入一个数组，一次性注册多个插件。这对于需要集中管理插件的场景非常有用。

TypeScript
univer.registerPlugins([  UniverRenderEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,  UniverDrawingPlugin,  [UniverLicensePlugin, {    license: process.env.CLIENT_LICENSE_TEXT,  }],  UniverSlidesPlugin,  UniverSlidesUIPlugin,])

可选功能包

当编辑器需要对应能力时，再安装功能包：

Shell
pnpm add @univerjs-pro/slides-printpnpm add @univerjs-pro/slides-table @univerjs-pro/slides-table-uipnpm add @univerjs-pro/chart-ui @univerjs-pro/slides-chart @univerjs-pro/slides-chart-uipnpm add @univerjs-pro/slides-exchange-client

功能注册示例请参考 打印、表格、图表 和 导入导出。

懒加载部分插件

插件模式的一个优势是可以延迟加载可选功能：

TypeScript
univer.createUnit(UniverInstanceType.UNIVER_SLIDE, {})import('@univerjs-pro/slides-chart').then(({ UniverSlidesChartPlugin }) => {  univer.registerPlugin(UniverSlidesChartPlugin)})

服务端使用

在 Node.js 中，通常只注册模型插件，不注册浏览器 UI 插件：

TypeScript
univer.registerPlugin(UniverSlidesPlugin)

模型插件用于无头快照处理。需要提供协同或文件转换接口时，请另外接入对应的 Server SDK 模块；仅注册此插件不会创建这些服务。

移动端适配

这些示例要求所安装的 SDK 包包含下列移动端导出。所有 @univerjs/* 和 @univerjs-pro/* 依赖应保持相同版本。

1.0.0-rc.0 尚未导出 UniverSlidesMobileUIPlugin。使用以下示例前，需要选择已包含该移动端入口的构建版本。

在 Univer Slides 中使用移动端 UI 插件提供触摸操作界面。3 请在创建编辑器前确定 UI 模式。

在上方插件模式示例中，替换以下 UI 插件的导入和注册，并在 createUnit() 前完成；不要追加到已初始化的桌面端编辑器中。保留模型插件、引擎、语言包、CSS 和 Facade 导入。桌面端和移动端类是同一个包入口的不同具名导出。

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

插件对照

仅注册需要的功能，并保留其模型插件和必要依赖。存在移动端 UI 导出不代表两端的操作界面完全相同。Pro 功能仍需相应的许可证；需要后端的功能，请在业务应用中通过 Univer Server SDK 接入相应能力。

来源包桌面端注册移动端注册
@univerjs/uiUniverUIPluginUniverMobileUIPlugin
@univerjs/docs-uiUniverDocsUIPluginUniverDocsMobileUIPlugin
@univerjs-pro/slides-uiUniverSlidesUIPluginUniverSlidesMobileUIPlugin
@univerjs/drawing-uiUniverDrawingUIPluginUniverDrawingMobileUIPlugin
@univerjs/thread-comment-uiUniverThreadCommentUIPluginUniverThreadCommentMobileUIPlugin
@univerjs-pro/shape-editor-uiUniverShapeEditorUIPluginUniverShapeEditorMobileUIPlugin
@univerjs-pro/chart-uiUniverChartUIPluginUniverChartMobileUIPlugin
@univerjs-pro/exchange-clientUniverExchangeClientPluginUniverExchangeClientMobileUIPlugin
@univerjs-pro/slides-chart-uiUniverSlidesChartUIPluginUniverSlidesChartMobileUIPlugin
@univerjs-pro/slides-printUniverSlidesPrintPluginUniverSlidesPrintMobilePlugin
@univerjs-pro/slides-table-uiUniverSlidesTableUIPluginUniverSlidesTableMobileUIPlugin
@univerjs-pro/slides-thread-comment-uiUniverSlidesThreadCommentUIPluginUniverSlidesThreadCommentMobileUIPlugin

容器与触摸交互

为容器指定明确高度，并配置页面 viewport。100dvh 随动态视口高度变化。请在目标移动浏览器上检查滚动、双指缩放、文字选择、剪贴板访问和软键盘弹出后的布局。仅缩小桌面端编辑器不会切换到移动端插件。

UniverMobileUIPlugin 默认使用 disableAutoFocus: true，避免编辑器在初始化时自动获取焦点。

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

其他发布版本

除了稳定版本之外，Univer 还提供了 alpha / beta 通道。这些版本可以让你提前体验到尚未正式发布的最新功能。但请记住，更多的功能同时意味着更多的风险。这些版本可能包含错误、不完整的功能或者不稳定的特性。请尽可能避免在生产环境中使用这些版本。

Alpha / Beta 版本

当 Univer 开发团队完成了一个新功能或重大更改时，可能会将其预发布到 alpha 或 beta 通道，你可以通过以下命令安装 alpha / beta 版本的 Univer 包：

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

如果你在使用 alpha / beta 版本时遇到任何问题或者有任何反馈，请通过 GitHub Issues 向 Univer 开发团队报告。

我们欢迎你对于这些早期版本的反馈。

下一步

Footnotes

  1. peerDependencies 表示需要由宿主项目提供兼容版本的依赖。这样 Univer 可以与应用共享 React 等库，而不是各自携带一份。 ↩

  2. Facade 是面向应用的 API，封装已注册插件的能力。导入 Facade 入口会扩展 API 方法，但不会代替功能插件的注册。 ↩

  3. 移动端 UI 插件在初始化时选择触摸控件和移动端服务，不会自动判断设备，也不会在窗口尺寸变化时切换已有实例。若要切换模式，应先保留文档状态，销毁旧实例，再使用所选插件组合初始化。 ↩

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.