安装和基本使用
本章介绍 Univer Sheets 的安装与基本使用,包括预设模式和插件模式的配置流程。如果尚未熟悉 Univer 的基础术语,建议先阅读 基本概念。
Univer 是一个电子文档应用框架,由插件组合而成。核心部分保持精简,应用只引入自身需要的模块。代价是搭建过程更为繁琐,首次集成 Univer 时尤其明显。
为此,Univer 提供插件模式和预设模式两种集成方式。预设是一组预先配置好的插件,因此在不做自定义扩展的情况下,两种模式提供的能力相同。预设模式可以缩短配置流程,一次导入即可引入一组已配置好的插件;如果需要深度扩展,则应使用插件模式,逐一组合和配置插件。
让 Agent 辅助接入(可选)
在向现有应用接入 Web SDK 时,可以使用 univer-integrate。该 Skill 会引导编程 Agent 完成预设或插件的配置、编辑器初始化以及 Facade API 的使用。
npx skills add dream-num/skills --skill univer-integrate在 Agent 打开的项目目录中运行该命令。需要跨项目使用时加 -g,也可以用 -a codex 或 -a claude-code 指定 Agent。随后查看已安装的 Skills:
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 的处理方式不同,有几点需要注意:
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/uinpm 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/uiyarn 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 rxjsbun 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,再引入其他插件的样式。
引入 Univer 的样式文件、语言文件以及应用所需的插件:
TypeScriptimport { 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 包。这一步是可选的,但建议完成:
TypeScriptimport '@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 实例并注册这些插件:
TypeScriptconst 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
containerstring | HTMLElement编辑器挂载到的 DOM 元素,或它的 ID。
UniverWatermarkPlugin
textWatermarkSettingsobject文字水印设置。contentstring默认值:''要显示的文字。fontSizenumber默认值:16字号,单位为像素。
univer.registerPlugin 与 univer.registerPlugins 方法
univer.registerPlugin 方法用于向 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 采用了同样的优化,可供参考。
移动端适配
这些示例要求所安装的 SDK 包导出下文列出的移动端插件。所有 @univerjs/* 和 @univerjs-pro/* 依赖必须保持同一个版本。
Univer Sheets 的触摸交互由移动端 UI 插件提供。6 UI 模式需要在创建编辑器之前确定。
Sheets 的移动端支持仍处于实验阶段。应用所需的功能需要在目标设备上验证。
在上面的插件模式示例中,应将 UI 插件的导入和注册替换为下文列出的内容,并在 createUnit() 之前完成。不要将它们追加到已经初始化的桌面端编辑器上。模型插件、引擎、语言文件、CSS 和 Facade 导入均需保留。桌面端与移动端的类都是同一个包入口的具名导出。
UniverMobileUIPlugin
containerstring | HTMLElement编辑器挂载到的 DOM 元素,或它的 ID。disableAutoFocustrue默认值:true编辑器启动时不会自动获得焦点。
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/ui | UniverUIPlugin | UniverMobileUIPlugin |
@univerjs/docs-ui | UniverDocsUIPlugin | UniverDocsMobileUIPlugin |
@univerjs/sheets-ui | UniverSheetsUIPlugin | UniverSheetsMobileUIPlugin |
@univerjs/sheets-formula-ui | UniverSheetsFormulaUIPlugin | UniverSheetsFormulaMobileUIPlugin |
@univerjs/sheets-numfmt-ui | UniverSheetsNumfmtUIPlugin | UniverSheetsNumfmtMobileUIPlugin |
@univerjs/drawing-ui | UniverDrawingUIPlugin | UniverDrawingMobileUIPlugin |
@univerjs/thread-comment-ui | UniverThreadCommentUIPlugin | UniverThreadCommentMobileUIPlugin |
@univerjs-pro/shape-editor-ui | UniverShapeEditorUIPlugin | UniverShapeEditorMobileUIPlugin |
@univerjs-pro/chart-ui | UniverChartUIPlugin | UniverChartMobileUIPlugin |
@univerjs-pro/exchange-client | UniverExchangeClientPlugin | UniverExchangeClientMobileUIPlugin |
@univerjs/sheets-conditional-formatting-ui | UniverSheetsConditionalFormattingUIPlugin | UniverSheetsConditionalFormattingMobileUIPlugin |
@univerjs/sheets-crosshair-highlight | UniverSheetsCrosshairHighlightPlugin | UniverSheetsCrosshairHighlightMobileUIPlugin |
@univerjs/sheets-data-validation-ui | UniverSheetsDataValidationUIPlugin | UniverSheetsDataValidationMobileUIPlugin |
@univerjs/sheets-drawing-ui | UniverSheetsDrawingUIPlugin | UniverSheetsDrawingMobileUIPlugin |
@univerjs/sheets-filter-ui | UniverSheetsFilterUIPlugin | UniverSheetsFilterMobileUIPlugin |
@univerjs/sheets-find-replace | UniverSheetsFindReplacePlugin | UniverSheetsFindReplaceMobileUIPlugin |
@univerjs/sheets-hyper-link-ui | UniverSheetsHyperLinkUIPlugin | UniverSheetsHyperLinkMobileUIPlugin |
@univerjs/sheets-sort-ui | UniverSheetsSortUIPlugin | UniverSheetsSortMobileUIPlugin |
@univerjs/sheets-table-ui | UniverSheetsTableUIPlugin | UniverSheetsTableMobileUIPlugin |
@univerjs/sheets-thread-comment-ui | UniverSheetsThreadCommentUIPlugin | UniverSheetsThreadCommentMobileUIPlugin |
@univerjs-pro/sheets-chart-ui | UniverSheetsChartUIPlugin | UniverSheetsChartMobileUIPlugin |
@univerjs-pro/sheets-exchange-client | UniverSheetsExchangeClientPlugin | UniverSheetsExchangeClientMobileUIPlugin |
@univerjs-pro/sheets-history-ui | UniverSheetsHistoryUIPlugin | UniverSheetsHistoryMobileUIPlugin |
@univerjs-pro/sheets-outline-ui | UniverSheetsOutlineUIPlugin | UniverSheetsOutlineMobileUIPlugin |
@univerjs-pro/sheets-pivot-ui | UniverSheetsPivotTableUIPlugin | UniverSheetsPivotTableMobileUIPlugin |
@univerjs-pro/sheets-print | UniverSheetsPrintPlugin | UniverSheetsPrintMobileUIPlugin |
@univerjs-pro/sheets-shape-ui | UniverSheetsShapeUIPlugin | UniverSheetsShapeMobileUIPlugin |
@univerjs-pro/sheets-sparkline-ui | UniverSheetSparklineUIPlugin | UniverSheetSparklineMobileUIPlugin |
@univerjs/find-replace | UniverFindReplacePlugin | UniverFindReplaceMobileUIPlugin |
容器与触摸交互
为容器指定明确的高度,并配置页面 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 的过程较为直接。建议使用对 ES Module 支持较完整的构建工具,例如 Vite、esbuild 或 Webpack 5。使用 Webpack 4 等较早的工具时,可能需要额外的配置。
安装
使用包管理器安装 @univerjs/presets:
pnpm add @univerjs/presets @univerjs/preset-sheets-corenpm install @univerjs/presets @univerjs/preset-sheets-coreyarn add @univerjs/presets @univerjs/preset-sheets-corebun add @univerjs/presets @univerjs/preset-sheets-core使用
如果构建工具不支持 package.json 的 exports 字段(Webpack 4 中较为常见),需要自行将映射路径改为实际路径。
以下两个文件即可启动一个 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 Facade API。Univer 提供的各项功能都通过它调用。
也可以从 @univerjs/presets/preset-sheets-core 引入 UniverSheetsCorePreset,前提是构建工具支持 package.json 的 exports 字段。
预设配置
UniverSheetsCorePreset
containerstring | 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 版本使用以下命令:
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 开发团队。
下一步
Footnotes
你觉得这篇文档如何?