API 参考

GitHubdream-num/univer

Univer SheetsUniver DocsUniver SlidesUniver Pro架构设计与最佳实践

安装和基本使用

GitHub在 GitHub 上编辑

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

通过预设模式创建

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

使用包管理器

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

安装

选择你所使用的包管理器以安装 @univerjs/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, 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 提供的许多功能。

Live preview

你也可以通过 @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 并不会正确地安装 peerDependencies1。
  • 如果你正在使用 pnpm，请确保使用的版本为 pnpm@8 及以上。如果你正在使用 pnpm@6 ~ pnpm@7，可以尝试配置 auto-install-peers=true 2来解决依赖安装问题。
  • 如果你正在使用 yarn，你需要手动安装缺失的 peerDependencies3，不过别担心，下面的安装命令中已经包含了这些依赖。
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, 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'

如果你需要使用 Facade API，你可以在这里引入相关的 facade 包，这是可选的（我相信你会需要它们 😀）：

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'

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

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)
Live preview

univer.registerPlugin 方法

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

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

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

univer.registerPlugin([
  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 提供了实验性质的移动端支持。移动端版本针对触摸交互进行了优化，提供了适配移动设备的 UI 组件和交互体验。

  • UI 插件：为了适配不同设备的交互方式，部分 UI 插件提供了桌面端和移动端两个版本。这两个版本在同一个 npm 包中，通过不同的导出路径区分。
  • 核心逻辑插件：如公式引擎（UniverFormulaEnginePlugin）、渲染引擎（UniverRenderEnginePlugin）等，在桌面端和移动端保持一致，无需区分版本。

移动端与桌面端插件并非两个完全独立的包，而是同一个包在不同平台的表现形式。例如 @univerjs/sheets-ui 既提供了桌面端的 UniverSheetsUIPlugin，也提供了移动端的 UniverSheetsMobileUIPlugin。

注意事项

  • 移动端支持目前处于实验阶段，部分功能可能不够完善。
  • 移动端 UI 插件与桌面端 UI 插件不能同时使用，需要根据设备类型选择对应的插件。
  • 建议在实际部署前进行充分的测试。
Live preview

切换至移动端插件

只需将相应的 UI 插件替换为移动端版本即可：

import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'
import { UniverSheetsMobileUIPlugin } from '@univerjs/sheets-ui'

univer.registerPlugin(UniverSheetsUIPlugin) 
univer.registerPlugin(UniverSheetsMobileUIPlugin)

桌面端与移动端插件对照

下表列出了所有提供移动端版本的 UI 插件。如果你需要根据设备类型动态选择插件，可以参考以下对照表：

桌面端插件移动端插件来源包
UniverUIPluginUniverMobileUIPlugin@univerjs/ui
UniverSheetsUIPluginUniverSheetsMobileUIPlugin@univerjs/sheets-ui
UniverSheetsFilterUIPluginUniverSheetsFilterMobileUIPlugin@univerjs/sheets-filter-ui
UniverSheetsDataValidationUIPluginUniverSheetsDataValidationMobileUIPlugin@univerjs/sheets-data-validation-ui
UniverSheetsConditionalFormattingUIPluginUniverSheetsConditionalFormattingMobileUIPlugin@univerjs/sheets-conditional-formatting-ui

在后续功能文档中，如果某个功能存在移动端的适配插件，我们会在对应的章节中进行说明。

通过 CDN 使用 Univer

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

其他发布版本

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

Alpha / Beta 版本

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

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

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

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

下一步

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

Footnotes

  1. https://blog.npmjs.org/post/110924823920/npm-weekly-5 ↩

  2. https://pnpm.io/npmrc#auto-install-peers ↩

  3. https://github.com/yarnpkg/yarn/issues/1503 ↩

你觉得这篇文档如何？

目录

通过预设模式创建
使用包管理器
安装
使用
createUniver 方法
通过 CDN 使用 Univer
通过插件模式创建
使用包管理器
安装
使用
univer.registerPlugin 方法
懒加载部分插件
移动端适配
切换至移动端插件
桌面端与移动端插件对照
通过 CDN 使用 Univer
其他发布版本
Alpha / Beta 版本
下一步
Footnotes
Capalyze