Web SDK

安装和基本使用

本章介绍 Univer Docs 的安装与基本使用，包含预设模式与插件模式的配置流程。若你还不熟悉 Univer 的基础术语与两种模式的差异，建议先阅读 基本概念。

通过预设模式创建

在这里我们将简单介绍下如何通过不到二十行的代码来快速搭建一个 Univer Docs 应用。

使用包管理器

如果你的项目中已经引入了现代前端开发工具，那么引入 Univer 将会非常简单。我们推荐使用 Vite、esbuild 或 Webpack 5 等对 ES Module 支持较好的构建工具来构建 Univer 应用。如果你使用了其它构建工具（例如 Webpack 4），可能会需要一些额外的配置。

安装

选择你所使用的包管理器以安装 @univerjs/presets：

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

使用

如果你的构建工具不支持 package.json 的 exports 字段（常见于 Webpack 4），你需要手动将映射的路径修改为实际的路径。

通过以下代码，你就可以快速创建一个 Univer Docs 应用：

HTML
<div id="app" style="height: 600px"></div>
TypeScript
import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'import UniverPresetDocsCoreZhCN from '@univerjs/preset-docs-core/locales/zh-CN'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-docs-core/lib/index.css'const { univer, univerAPI } = createUniver({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetDocsCoreZhCN,    ),  },  presets: [    UniverDocsCorePreset({      container: 'app',    }),  ],})univerAPI.createDocument({})

这里返回的 univerAPI 对象被称为 Univer 的面板 API（Facade API），通过它可以调用 Univer 提供的许多功能。

预览

你也可以通过 @univerjs/presets/preset-docs-core 来引入 UniverDocsCorePreset，但必须确保你的构建工具支持 package.json 的 exports 字段。

createUniver 方法

createUniver 方法接受一个配置对象，其中包含了 Univer 的配置信息，例如语言、主题、插件等。这个方法会返回一个包含了 Univer 实例和 Univer Facade API 实例的对象。

配置对象的部分属性如下：

  • locale：语言环境，可以是 LocaleType 枚举值。
  • locales：语言包，一个对象，键为语言环境，值为语言包对象。
  • theme：主题，一个可选主题对象。
  • presets：一个 preset 数组，包含了需要注册的预设包，例如 UniverDocsCorePreset。
  • plugins：一个插件数组，包含了需要额外注册的插件。

当你使用了一个未包含在任何预设包中的插件或者你自己实现了一个插件时，可以通过 plugins 属性来注册这些插件。也可以选择在获得 Univer 实例后通过 univer.registerPlugin 方法来注册插件。

你可以在 API Reference / createUniver 找到更多关于 createUniver 方法的详细信息。

通过 CDN 使用 Univer

如果你不想使用包管理器，或者只是想快速尝试 Univer 的功能，你可以通过 CDN 引入 Univer 的相关资源。详情请参考 通过 CDN 使用 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/* 包应保持相同版本。

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

使用

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

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

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

注意事项

  • 并非所有的插件都包含了 facade 包、语言包和样式文件，我们会在每个功能的文档对此进行说明。
  • 样式文件的引入顺序很重要，确保你在依次引入 @univerjs/design、@univerjs/ui 的 CSS 样式后再引入其他插件的样式文件。

  1. 你需要在项目中引入 Univer 的样式文件、语言包，以及一些必要的插件：

    TypeScript
    import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { FUniver } from '@univerjs/core/facade'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 { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'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'

  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_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      DesignZhCN,      UIZhCN,      DocsUIZhCN,    ),  },})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 实例后调用这个方法来注册插件。

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

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

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

懒加载部分插件

使用插件模式的一个优势是你可以更加灵活地控制插件的加载时机，一种常见的方式是在应用初始化时仅加载必须的插件，而将部分插件的加载时机延迟到首次渲染完成之后。

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

Alpha / Beta 版本

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

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

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

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

下一步

  • 在 基础概念 章节了解本章中出现的插件、命令和 Facade API 等概念。
  • 在 功能 相关章节中了解修改文档内容的所有操作。

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.