安装和基本使用

本章介绍 Univer Sheets 的安装与基本使用,包括预设模式和插件模式的配置流程。如果尚未熟悉 Univer 的基础术语,建议先阅读 基本概念。

Univer 是一个电子文档应用框架,由插件组合而成。核心部分保持精简,应用只引入自身需要的模块。代价是搭建过程更为繁琐,首次集成 Univer 时尤其明显。

为此,Univer 提供插件模式和预设模式两种集成方式。预设是一组预先配置好的插件,因此在不做自定义扩展的情况下,两种模式提供的能力相同。预设模式可以缩短配置流程,一次导入即可引入一组已配置好的插件;如果需要深度扩展,则应使用插件模式,逐一组合和配置插件。

让 Agent 辅助接入(可选)

在向现有应用接入 Web SDK 时,可以使用 univer-integrate。该 Skill 会引导编程 Agent 完成预设或插件的配置、编辑器初始化以及 Facade API 的使用。

Bash
npx skills add dream-num/skills --skill univer-integrate

在 Agent 打开的项目目录中运行该命令。需要跨项目使用时加 -g,也可以用 -a codex 或 -a claude-code 指定 Agent。随后查看已安装的 Skills:

Bash
npx skills list

列表中应包含 univer-integrate。如果未找到该项,请检查安装路径中是否存在 SKILL.md,必要时重新打开 Agent 会话。

旧教程中可能使用 dream-num/univer-sdk-skills。请改用上面的 dream-num/skills 命令,Skill 名称仍为 univer-integrate。接入前应核对该 Skill 要求的 SDK 版本基线,并以当前文档和项目实际安装的版本为准。

通过插件模式创建

Univer 以插件的形式提供各项功能。少数核心插件是产品正常运行所必需的,其余插件按需引入。本节手动构建一个最小的 Univer Sheets 应用,并逐一注册其中的插件。

与预设模式不同,插件模式默认不包含 Facade API1。下面代码中与 Facade 相关的部分是可选的,不需要时可以删除。

使用包管理器

安装

Univer 使用 React 渲染视图(这不影响在 Vue 或 Angular 中使用 Univer),并使用 Rxjs 处理数据流。这两个库在现代前端开发中应用广泛,因此 Univer 将它们作为 peerDependencies2 处理。不同包管理器对 peer dependencies 的处理方式不同,有几点需要注意:

  • 使用 npm 时,版本不得低于 npm@7。npm@3 ~ npm@6 无法正确安装 peerDependencies3。
  • 使用 pnpm 时,版本不得低于 pnpm@8。使用 pnpm@6 ~ pnpm@7 时,可以尝试设置 auto-install-peers=true 4 以解决依赖安装问题。
  • 使用 yarn 时,需要自行安装缺失的 peerDependencies5。下面的安装命令已经包含这些依赖。
Shell
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

使用

注意事项

  • 并非每个插件都包含 facade 包、语言文件和样式文件,各功能的文档会说明具体包含哪些内容。
  • 样式文件的引入顺序很重要。应先引入 @univerjs/design 和 @univerjs/ui 的 CSS,再引入其他插件的样式。
  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)

插件配置

UniverUIPlugin

  • container
    string | HTMLElement
    编辑器挂载到的 DOM 元素,或它的 ID。

UniverWatermarkPlugin

  • textWatermarkSettings
    object
    文字水印设置。
    • content
      string默认值: ''
      要显示的文字。
    • fontSize
      number默认值: 16
      字号,单位为像素。

univer.registerPlugin 与 univer.registerPlugins 方法

univer.registerPlugin 方法用于向 Univer 实例注册插件,应在创建实例之后调用。

注册时传入插件和配置项:univer.registerPlugin(Plugin, options)。其中 Plugin 是要注册的插件,options 是可选的配置项,不同插件的配置项各不相同。

如需一次注册多个插件,可以向 univer.registerPlugins 传入数组。这种方式适合集中管理插件。

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

懒加载部分插件

插件模式的一个优势是可以控制插件的加载时机。常见的做法是在初始化时只加载必需的插件,将其余插件推迟到首次渲染完成之后再加载。

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

Univer 的官方 demo 采用了同样的优化,可供参考。

移动端适配

这些示例要求所安装的 SDK 包导出下文列出的移动端插件。所有 @univerjs/* 和 @univerjs-pro/* 依赖必须保持同一个版本。

Univer Sheets 的触摸交互由移动端 UI 插件提供。6 UI 模式需要在创建编辑器之前确定。

Sheets 的移动端支持仍处于实验阶段。应用所需的功能需要在目标设备上验证。

在上面的插件模式示例中,应将 UI 插件的导入和注册替换为下文列出的内容,并在 createUnit() 之前完成。不要将它们追加到已经初始化的桌面端编辑器上。模型插件、引擎、语言文件、CSS 和 Facade 导入均需保留。桌面端与移动端的类都是同一个包入口的具名导出。

UniverMobileUIPlugin

  • container
    string | HTMLElement
    编辑器挂载到的 DOM 元素,或它的 ID。
  • disableAutoFocus
    true默认值: true
    编辑器启动时不会自动获得焦点。
TypeScript
import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'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(UniverDocsMobileUIPlugin)univer.registerPlugin(UniverSheetsMobileUIPlugin)univer.registerPlugin(UniverSheetsFormulaMobileUIPlugin)univer.registerPlugin(UniverSheetsNumfmtMobileUIPlugin)

在移动端,还需要将 UniverDocsUIPlugin 替换为 UniverDocsMobileUIPlugin,以便编辑单元格内的文档,并应在 UniverSheetsMobileUIPlugin 之前注册。

UniverSheetsCorePreset 和 UniverDocsCorePreset 目前注册的是桌面端 UI 插件,也没有 mobile: true 选项。在移动端需要显式组合插件。在桌面端预设之后追加移动端插件,无法替换预设的 UI。

插件对照

只注册实际使用的功能,同时保留其模型插件和必要依赖。提供移动端 UI 导出,并不意味着桌面端与移动端的操作界面完全一致。Pro 功能仍需要对应的许可证;需要后端的功能,需要在业务应用侧接入 Univer Server SDK。

来源包桌面端注册移动端注册
@univerjs/uiUniverUIPluginUniverMobileUIPlugin
@univerjs/docs-uiUniverDocsUIPluginUniverDocsMobileUIPlugin
@univerjs/sheets-uiUniverSheetsUIPluginUniverSheetsMobileUIPlugin
@univerjs/sheets-formula-uiUniverSheetsFormulaUIPluginUniverSheetsFormulaMobileUIPlugin
@univerjs/sheets-numfmt-uiUniverSheetsNumfmtUIPluginUniverSheetsNumfmtMobileUIPlugin
@univerjs/drawing-uiUniverDrawingUIPluginUniverDrawingMobileUIPlugin
@univerjs/thread-comment-uiUniverThreadCommentUIPluginUniverThreadCommentMobileUIPlugin
@univerjs-pro/shape-editor-uiUniverShapeEditorUIPluginUniverShapeEditorMobileUIPlugin
@univerjs-pro/chart-uiUniverChartUIPluginUniverChartMobileUIPlugin
@univerjs-pro/exchange-clientUniverExchangeClientPluginUniverExchangeClientMobileUIPlugin
@univerjs/sheets-conditional-formatting-uiUniverSheetsConditionalFormattingUIPluginUniverSheetsConditionalFormattingMobileUIPlugin
@univerjs/sheets-crosshair-highlightUniverSheetsCrosshairHighlightPluginUniverSheetsCrosshairHighlightMobileUIPlugin
@univerjs/sheets-data-validation-uiUniverSheetsDataValidationUIPluginUniverSheetsDataValidationMobileUIPlugin
@univerjs/sheets-drawing-uiUniverSheetsDrawingUIPluginUniverSheetsDrawingMobileUIPlugin
@univerjs/sheets-filter-uiUniverSheetsFilterUIPluginUniverSheetsFilterMobileUIPlugin
@univerjs/sheets-find-replaceUniverSheetsFindReplacePluginUniverSheetsFindReplaceMobileUIPlugin
@univerjs/sheets-hyper-link-uiUniverSheetsHyperLinkUIPluginUniverSheetsHyperLinkMobileUIPlugin
@univerjs/sheets-sort-uiUniverSheetsSortUIPluginUniverSheetsSortMobileUIPlugin
@univerjs/sheets-table-uiUniverSheetsTableUIPluginUniverSheetsTableMobileUIPlugin
@univerjs/sheets-thread-comment-uiUniverSheetsThreadCommentUIPluginUniverSheetsThreadCommentMobileUIPlugin
@univerjs-pro/sheets-chart-uiUniverSheetsChartUIPluginUniverSheetsChartMobileUIPlugin
@univerjs-pro/sheets-exchange-clientUniverSheetsExchangeClientPluginUniverSheetsExchangeClientMobileUIPlugin
@univerjs-pro/sheets-history-uiUniverSheetsHistoryUIPluginUniverSheetsHistoryMobileUIPlugin
@univerjs-pro/sheets-outline-uiUniverSheetsOutlineUIPluginUniverSheetsOutlineMobileUIPlugin
@univerjs-pro/sheets-pivot-uiUniverSheetsPivotTableUIPluginUniverSheetsPivotTableMobileUIPlugin
@univerjs-pro/sheets-printUniverSheetsPrintPluginUniverSheetsPrintMobileUIPlugin
@univerjs-pro/sheets-shape-uiUniverSheetsShapeUIPluginUniverSheetsShapeMobileUIPlugin
@univerjs-pro/sheets-sparkline-uiUniverSheetSparklineUIPluginUniverSheetSparklineMobileUIPlugin
@univerjs/find-replaceUniverFindReplacePluginUniverFindReplaceMobileUIPlugin

容器与触摸交互

为容器指定明确的高度,并配置页面 viewport。100dvh 会跟随动态视口高度变化。滚动、双指缩放、文字选择、剪贴板访问和软键盘,均需在目标移动浏览器上验证。仅调整桌面端编辑器的尺寸,不会切换到移动端插件。

UniverMobileUIPlugin 默认使用 disableAutoFocus: true,编辑器在初始化时不会自动获得焦点。

HTML
<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 的过程较为直接。建议使用对 ES Module 支持较完整的构建工具,例如 Vite、esbuild 或 Webpack 5。使用 Webpack 4 等较早的工具时,可能需要额外的配置。

安装

使用包管理器安装 @univerjs/presets:

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

使用

如果构建工具不支持 package.json 的 exports 字段(Webpack 4 中较为常见),需要自行将映射路径改为实际路径。

以下两个文件即可启动一个 Univer Sheets 应用:

HTML
<div id="app" style="height: 600px"></div>
TypeScript
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 Facade API。Univer 提供的各项功能都通过它调用。

也可以从 @univerjs/presets/preset-sheets-core 引入 UniverSheetsCorePreset,前提是构建工具支持 package.json 的 exports 字段。

预设配置

UniverSheetsCorePreset

  • container
    string | HTMLElement默认值: 'app'
    编辑器挂载到的 DOM 元素,或它的 ID。

createUniver 方法

createUniver 接收一个配置对象,其中包含 Univer 的语言、主题和插件等设置。它返回一个对象,包含 Univer 实例和 Univer Facade API 实例。

配置对象的主要属性如下:

  • locale:语言环境,取值为 LocaleType 枚举值。
  • locales:语言包对象,键为语言环境,值为对应的语言包。
  • theme:主题对象,可选。
  • presets:要注册的预设,例如 UniverSheetsCorePreset。
  • plugins:除预设之外需要额外注册的插件。

如果插件不属于任何预设包,或是自行编写的插件,可以通过 plugins 属性注册。也可以在获得 Univer 实例后调用 univer.registerPlugin 注册。

createUniver 的更多细节见 API Reference / createUniver。

通过 CDN 使用 Univer

如果不想使用包管理器,或希望快速试用 Univer,可以通过 CDN 加载 Univer。详见 通过 CDN 使用 Univer。

其他发布版本

除稳定版本外,Univer 还提供 alpha、beta 和 nightly 通道。这些版本可以提前使用尚未正式发布的新功能,同时也带来更高的风险:可能包含 bug、功能不完整或行为不稳定。生产环境中应尽量避免使用这些版本。

Alpha / Beta 版本

Univer 开发团队完成新功能或较大改动后,可能会先将其预发布到 alpha 或 beta 通道。安装 alpha 或 beta 版本使用以下命令:

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

使用 alpha 或 beta 版本时遇到问题或有反馈,可以通过 GitHub Issues 报告给 Univer 开发团队。

下一步

  • 阅读 基础概念,其中介绍了本章出现的插件、命令和 Facade API 等概念。
  • 阅读 功能,其中介绍了修改电子表格数据的各项操作。

Footnotes

  1. Facade 是面向应用的 API,封装已注册插件的能力。导入 Facade 入口会扩展 API 方法,但不会代替功能插件的注册。 ↩

  2. peerDependencies 表示需要由宿主项目提供兼容版本的依赖。这样 Univer 可以与应用共享 React 等库,而不是各自携带一份。 ↩

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

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

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

  6. 移动端 UI 插件在初始化时选择触摸控件和移动端服务,不会自动判断设备,也不会在窗口尺寸变化时切换已有实例。若要切换模式,应先保留文档状态,销毁旧实例,再使用所选插件组合初始化。 ↩

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.