Web SDK

安装和基本使用

本章介绍 Univer Bases 的安装与基本用法。Bases 作为 Univer Office SDK 产品发布，目前采用插件模式。

如果你还不熟悉 Univer 的核心概念，请先阅读快速入门。

通过插件模式创建

浏览器端的 Bases 应用通常需要依次注册 Univer 共享运行时、渲染引擎、UI 外壳、公式引擎和 许可证，然后再注册 Bases 模型插件与 UI 插件。

使用包管理器

使用支持 ES Module 和 package.json 中 exports 字段的构建工具。

安装

Univer 使用 React 构建界面、RxJS 处理数据流，也可以嵌入 Vue 或 Angular 应用。请确认已安装 react、react-dom 和 rxjs 这些 peer dependencies；下方 Yarn 命令已显式包含它们。

所有 @univerjs/* 和 @univerjs-pro/* 包应保持相同版本。

Shell
pnpm add @univerjs/core @univerjs/design @univerjs/engine-formula @univerjs/engine-render @univerjs/ui @univerjs-pro/bases @univerjs-pro/bases-ui @univerjs-pro/engine-formula @univerjs-pro/license

使用

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

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

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

注意

  • 请先注册 UniverLicensePlugin，再注册 Bases 插件。
  • 请先导入共享 UI CSS，再导入产品 UI CSS。
  • 公式字段使用 UniverProFormulaEnginePlugin，它替代 UniverFormulaEnginePlugin，不要同时注册。

  1. 导入样式、语言包和所需插件：

    TypeScript
    import { UniverBasesPlugin } from '@univerjs-pro/bases'import { UniverBasesUIPlugin } from '@univerjs-pro/bases-ui'import BasesUIEnUS from '@univerjs-pro/bases-ui/locale/en-US'import BasesEnUS from '@univerjs-pro/bases/locale/en-US'import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula'import { UniverLicensePlugin } from '@univerjs-pro/license'import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'import DesignEnUS from '@univerjs/design/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-pro/bases-ui/lib/index.css'

  2. 如需使用 Facade API，请导入 Facade 入口：

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

  3. 创建 Univer 实例、注册插件并创建 Base 单元：

    TypeScript
    const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      BasesEnUS,      BasesUIEnUS,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverUIPlugin, { container: 'app' })univer.registerPlugin(UniverProFormulaEnginePlugin)univer.registerPlugin(UniverLicensePlugin, {  license: process.env.CLIENT_LICENSE_TEXT,})univer.registerPlugin(UniverBasesPlugin)univer.registerPlugin(UniverBasesUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_BASE, {})const univerAPI = FUniver.newAPI(univer)

univer.registerPlugin 与 univer.registerPlugins 方法

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

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

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

TypeScript
univer.registerPlugins([  UniverRenderEnginePlugin,  [UniverUIPlugin, { container: 'app' }],  UniverProFormulaEnginePlugin,  [UniverLicensePlugin, {    license: process.env.CLIENT_LICENSE_TEXT,  }],  UniverBasesPlugin,  UniverBasesUIPlugin,])

其他发布版本

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

Alpha / Beta 版本

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

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

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

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

下一步

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.