安装和基本使用

Univer 采用了插件化的设计理念，旨在为开发者提供一个灵活、可扩展的电子文档应用框架。通过插件化设计，Univer 可以轻松地集成各种功能模块，从而满足不同用户的需求。但插件化的设计会增加应用的复杂性，尤其是对于首次接触 Univer 的开发者来说。

为此，Univer 提供了插件模式和预设模式两种方式帮助你快速集成和使用 Univer。所谓预设实际上就是一组预先配置好的插件组合，因此在无需进行复杂扩展的情况下，两者所提供的能力是相同的。

注意事项

依赖版本需一致：无论是使用预设模式还是插件模式的方式，你都必须保证所有依赖的版本号一致。
谨慎混用插件和预设：如果一个插件已经被包含在某个预设中，那么在使用预设时就不需要再单独引入该插件了。否则可能会导致插件冲突或功能异常。

预设模式与插件模式的区别：

插件模式	预设模式
需要手动引入对应的 facade 包	无需手动引入任何 facade 包
需要注意同类型功能插件注册顺序	同功能被包含在预设中无需关注注册顺序
支持按需懒加载	仅支持预设级别的懒加载，预设内的插件包只能同步加载

通过预设模式创建

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

使用包管理器

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

安装

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

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

使用

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

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

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'
import { createUniver, LocaleType, merge } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'

const { univer, univerAPI } = createUniver({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: merge(
      {},
      UniverPresetSheetsCoreZhCN,
    ),
  },
  presets: [
    UniverSheetsCorePreset({
      container: 'app',
    }),
  ],
})

univerAPI.createWorkbook({})

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

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

`createUniver` 方法

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

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

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

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

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

通过 CDN 使用 Univer

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

通过插件模式创建

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

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

使用包管理器

安装

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

如果你正在使用 npm，请确保使用的版本为 npm@7 及以上。这是因为 npm@3 ~ npm@6 并不会正确地安装 peerDependencies¹。
如果你正在使用 pnpm，请确保使用的版本为 pnpm@8 及以上。如果你正在使用 pnpm@6 ~ pnpm@7，可以尝试配置 auto-install-peers=true ²来解决依赖安装问题。
如果你正在使用 yarn，你需要手动安装缺失的 peerDependencies³，不过别担心，下面的安装命令中已经包含了这些依赖。

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

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

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

使用

注意事项

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

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

import { LocaleType, merge, 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'

// 这里的 Facade API 是可选的，你可以根据自己的需求来决定是否引入
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'

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'

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

const univer = new Univer({
  locale: LocaleType.ZH_CN,
  locales: {
    [LocaleType.ZH_CN]: merge(
      {},
      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.createUnit(UniverInstanceType.UNIVER_SHEET, {})

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

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

npm install @univerjs/<package-name>@alpha # Alpha 版本
npm install @univerjs/<package-name>@beta # Beta 版本

Nightly 版本

Nightly 版本是 Univer 自动构建的版本，每天都会生成最新的更改、错误修复和实验性功能。这些版本非常不稳定，不适合在生产环境中使用。但它们非常适合测试最新的功能和确保与最新的代码库兼容。

npm install @univerjs/<package-name>@nightly

警告

夜间版本是非常不稳定的，可能包含致命的错误、不完整的功能或者实验性的特性。请绝对不要在生产环境中使用这些版本。

如果你在使用夜间版本时遇到任何问题或者有任何反馈，请通过适当的渠道向 Univer 开发团队报告，比如 Github Issues 或者 Discord 社区。

祝你在抢先体验中玩得愉快！

下一步

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

你觉得这篇文档如何？

安装和基本使用

通过预设模式创建

使用包管理器

安装

使用

`createUniver` 方法

通过 CDN 使用 Univer

通过插件模式创建

使用包管理器

安装

使用

懒加载部分插件

通过 CDN 使用 Univer

其他发布版本

Alpha / Beta 版本

Nightly 版本

下一步

目录