安装和基本使用

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

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

通过插件模式创建

Univer 以插件的形式提供了一系列功能，除了一些产品所必需的核心插件外，你还可以根据需要选择性地引入其它插件。这里仅以最基础的 Univer Sheets 应用为例，介绍如何手动组合安装插件。

与预设模式不同，插件模式默认并不包含 Facade API¹，以下代码示例中有关 Facade API 的部分都是可选的，你可以根据自己的需求来决定是否删除。

使用包管理器

安装

Univer 使用了 React 开发视图（当然这并不影响你在 Vue 或者 Angular 中使用 Univer），使用 Rxjs 来处理数据流，由于这两个库被广泛使用在现代前端开发中，因此我们将它们作为 peerDependencies²。而不同的包管理工具在对于 peerDependencies 有着不同的行为策略，因此你可能需要注意一些细节。

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

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

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

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

使用

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

   TypeScript

   import { LocaleType, mergeLocales, Univer, UniverInstanceType } 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 { UniverSheetsPlugin } from '@univerjs/sheets'import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'import SheetsFormulaUIZhCN from '@univerjs/sheets-formula-ui/locale/zh-CN'import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'import SheetsNumfmtUIZhCN from '@univerjs/sheets-numfmt-ui/locale/zh-CN'import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'import SheetsUIZhCN from '@univerjs/sheets-ui/locale/zh-CN'import SheetsZhCN from '@univerjs/sheets/locale/zh-CN'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/sheets-ui/lib/index.css'import '@univerjs/sheets-formula-ui/lib/index.css'import '@univerjs/sheets-numfmt-ui/lib/index.css'

   展开代码

2. 如果你需要使用 Facade API，你可以在这里引入相关的 facade 包，这是可选的，但建议引入：

   TypeScript

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

3. 然后创建一个 Univer 实例，并注册这些插件：

   TypeScript

   const univer = new Univer({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      DesignZhCN,      UIZhCN,      DocsUIZhCN,      SheetsZhCN,      SheetsUIZhCN,      SheetsFormulaUIZhCN,      SheetsNumfmtUIZhCN,    ),  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverFormulaEnginePlugin)univer.registerPlugin(UniverUIPlugin, {  container: 'app',})univer.registerPlugin(UniverDocsPlugin)univer.registerPlugin(UniverDocsUIPlugin)univer.registerPlugin(UniverSheetsPlugin)univer.registerPlugin(UniverSheetsUIPlugin)univer.registerPlugin(UniverSheetsFormulaPlugin)univer.registerPlugin(UniverSheetsFormulaUIPlugin)univer.registerPlugin(UniverSheetsNumfmtPlugin)univer.registerPlugin(UniverSheetsNumfmtUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})const univerAPI = FUniver.newAPI(univer)

   展开代码

univer.registerPlugin 与 univer.registerPlugins 方法

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

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

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

univer.registerPlugins([  UniverRenderEnginePlugin,  UniverFormulaEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,  UniverSheetsPlugin,  UniverSheetsUIPlugin,  UniverSheetsFormulaPlugin,  UniverSheetsFormulaUIPlugin,  UniverSheetsNumfmtPlugin,  UniverSheetsNumfmtUIPlugin,])

懒加载部分插件

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

// ...univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {  univer.registerPlugin(UniverWatermarkPlugin, {    textWatermarkSettings: {      content: 'Hello, Univer!',      fontSize: 36,    },  })})

Univer 的 官方 demo 就使用了这样的优化技巧，可供参考。

移动端适配

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

Sheets 移动端支持仍属于实验性质，请在目标设备上验证应用实际使用的功能。

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

import { UniverSheetsFormulaMobileUIPlugin } from '@univerjs/sheets-formula-ui'import { UniverSheetsNumfmtMobileUIPlugin } from '@univerjs/sheets-numfmt-ui'import { UniverSheetsMobileUIPlugin } from '@univerjs/sheets-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverSheetsMobileUIPlugin)univer.registerPlugin(UniverSheetsFormulaMobileUIPlugin)univer.registerPlugin(UniverSheetsNumfmtMobileUIPlugin)

Sheets 中保留 UniverDocsUIPlugin。 UniverSheetsMobileUIPlugin 依赖它提供单元格内的文档编辑能力。独立的 Docs 编辑器才使用 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>

通过 CDN 使用 Univer

如果你不想使用包管理器，或者只是想快速尝试 Univer 的功能，你可以通过 CDN 引入 Univer 的相关资源。详情请参考 通过 CDN 使用 Univer。

通过预设模式创建

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

使用包管理器

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

安装

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

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

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

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

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

使用

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

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

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'const { univer, univerAPI } = createUniver({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,    ),  },  presets: [    UniverSheetsCorePreset({      container: 'app',    }),  ],})univerAPI.createWorkbook({})

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

createUniver 方法

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

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

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

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

通过 CDN 使用 Univer

如果你不想使用包管理器，或者只是想快速尝试 Univer 的功能，你可以通过 CDN 引入 Univer 的相关资源。详情请参考 通过 CDN 使用 Univer。

其他发布版本

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

Alpha / Beta 版本

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

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 向 Univer 开发团队报告。

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

下一步

• 在 基础概念 章节了解本章中出现的插件、命令和 Facade API 等概念。
• 在 功能 相关章节中了解修改电子表格数据的所有操作。