安装和基本使用

Univer PDFs 属于 Univer Office SDK,目前尚未提供预设,因此 PDF 应用采用插件模式构建。

Univer 提供两种集成方式:预设模式和插件模式。预设模式提供预先配置好的插件组合,可以减少装配工作量;如果需要深度定制或扩展,则使用插件模式,由开发者自行选择和配置每个插件。

通过插件模式创建

使用包管理器

构建工具需要支持 ES Modules 以及 package.json 中的 exports 字段。

安装

Univer 的界面基于 React,数据流基于 RxJS,也可以嵌入 Vue 或 Angular 应用。请确认 react、react-dom、rxjs 这几个 peer dependencies1 已经安装;下面的 Yarn 命令会一并安装它们。

所有 @univerjs/* 和 @univerjs-pro/* 包必须保持相同版本。

Shell
pnpm add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui

所有 @univerjs/* 和 @univerjs-pro/* 包均须保持相同版本。

使用

先创建容器并指定明确的高度,再初始化 Univer:

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

调用 FUniver.newAPI(univer) 之前,先导入下文用到的 facade 入口。样式按 @univerjs/design、@univerjs/ui、产品 CSS 的顺序引入。

  1. 先引入公共 UI 样式,再引入 PDF UI 样式,并合并应用启用的语言包:

    TypeScript
    import { UniverLicensePlugin } from '@univerjs-pro/license'import { UniverPdfsPlugin } from '@univerjs-pro/pdfs'import { UniverPdfsUIPlugin } from '@univerjs-pro/pdfs-ui'import PdfsUIEnUS from '@univerjs-pro/pdfs-ui/locale/en-US'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { FUniver } from '@univerjs/core/facade'import DesignEnUS from '@univerjs/design/locale/en-US'import { UniverUIPlugin } from '@univerjs/ui'import UIEnUS from '@univerjs/ui/locale/en-US'import '@univerjs/design/lib/index.css'import '@univerjs/ui/lib/index.css'import '@univerjs-pro/pdfs-ui/lib/index.css'
  2. 导入 PDF Facade2 入口。该副作用导入会为 FUniver 增加 PDF 方法和枚举:

    TypeScript
    import '@univerjs-pro/pdfs/facade'
  3. 创建运行时,注册显式的插件栈,然后创建一个 PDF:

    TypeScript
    const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      PdfsUIEnUS,    ),  },})univer.registerPlugin(UniverUIPlugin, { container: 'app' })univer.registerPlugin(UniverLicensePlugin, {  license: process.env.CLIENT_LICENSE_TEXT,})univer.registerPlugin(UniverPdfsPlugin)univer.registerPlugin(UniverPdfsUIPlugin)const univerAPI = FUniver.newAPI(univer)univerAPI.createPdf({ name: 'Untitled PDF' })

插件配置

UniverUIPlugin

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

UniverLicensePlugin

  • license
    string
    客户端许可证文件的内容。

univer.registerPlugin 与 univer.registerPlugins 方法

Univer 实例创建完成后,调用 univer.registerPlugin 即可在该实例上注册插件。

调用形式为 univer.registerPlugin(Plugin, options):Plugin 是要注册的插件,options 是可选配置对象,每个插件可以定义自己的配置项。

如需一次注册多个插件,可向 univer.registerPlugins 传入数组,以便集中管理插件。

TypeScript
univer.registerPlugins([  [UniverUIPlugin, { container: 'app' }],  [UniverLicensePlugin, {    license: process.env.CLIENT_LICENSE_TEXT,  }],  UniverPdfsPlugin,  UniverPdfsUIPlugin,])

移动端适配

当前 @univerjs-pro/pdfs-ui 包没有导出独立的移动端 UI 插件,既不存在 MobileUIPlugin 导入项,也不存在 mobile: true 选项,请不要尝试使用它们。容器变窄并不能说明触摸支持已经完整,现有 UI 需要在目标设备上实际验证。

可选的缩略图 Worker

页面缩略图默认在主线程渲染,无需额外配置。文档较大时,可通过 thumbnailWorkerURL 交给专用的模块 Worker 处理。

创建一个 Worker 入口,例如 pdf-thumbnail.worker.ts:

TypeScript
import { UniverPdfsUIWorkerPlugin } from '@univerjs-pro/pdfs-ui/worker'import { Univer } from '@univerjs/core'const univer = new Univer()univer.registerPlugin(UniverPdfsUIWorkerPlugin)

注册 PDF UI 插件时传入该 Worker 的 URL:

UniverPdfsUIPlugin

  • thumbnailWorkerURL
    string | URL | Worker
    在浏览器 Worker 中生成页面缩略图。
TypeScript
univer.registerPlugin(UniverPdfsUIPlugin, {  thumbnailWorkerURL: new Worker(new URL('./pdf-thumbnail.worker.ts', import.meta.url), { type: 'module' }),})

该选项也接受字符串 URL 或已有的 Worker。如果 Worker 或 OffscreenCanvas 不可用,缩略图渲染会回退到主线程。

基于协作的编辑

@univerjs-pro/pdfs-editor 不属于纯本地的插件栈,也不能单独工作。请先按协作文档安装并注册完整的 @univerjs-pro/collaboration、@univerjs-pro/collaboration-client、@univerjs-pro/collaboration-client-ui 插件栈,再安装并注册 PDF 编辑器生命周期插件。

Node.js 用法

Node.js 服务可以只注册 UniverPdfsPlugin,不需要任何浏览器 UI 包。只有服务需要加载或同步已持久化的 PDF 单元时,才需要加上上述协作插件栈。

其他发布版本

除稳定版外,Univer 还维护 alpha 和 beta 通道,可用于提前使用尚未正式发布的功能。功能更多也意味着风险更高:这些版本可能存在缺陷、功能不完整或特性不稳定,应尽量避免用于生产环境。

Alpha / Beta 版本

Univer 团队完成新功能或较大改动后,可能先将其发布到 alpha 或 beta 通道。安装某个包的 alpha / beta 版本:

Shell
pnpm add @univerjs-pro/pdfs@alpha # Alpha 版本
pnpm add @univerjs-pro/pdfs@beta # Beta 版本

使用 alpha / beta 版本时如遇到问题或有反馈,请通过 GitHub Issues 告知 Univer 团队。欢迎反馈这些早期版本的实际使用情况。

下一步

Footnotes

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

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

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.