# 安装和基本使用

- Human documentation: [https://docs.univer.ai/zh-CN/guides/pdfs/getting-started/installation](https://docs.univer.ai/zh-CN/guides/pdfs/getting-started/installation)

- Agent Markdown: [https://docs.univer.ai/zh-CN/guides/pdfs/getting-started/installation.md](https://docs.univer.ai/zh-CN/guides/pdfs/getting-started/installation.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [pdfs/getting-started/installation/index.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/pdfs/getting-started/installation/index.zh-CN.mdx)

---

Univer PDFs 是 Univer Office SDK 产品，目前不提供预设。请使用插件模式创建 PDF 应用。

## 通过插件模式创建

### 使用包管理器

使用支持 ES Module 和 `package.json` 中 `exports` 字段的构建工具。

#### 安装

Univer 使用 React 构建界面、RxJS 处理数据流，也可以嵌入 Vue 或 Angular 应用。请确认已安装 `react`、`react-dom` 和 `rxjs` 这些 peer dependencies；下方 Yarn 命令已显式包含它们。

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

#### pnpm

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

#### npm

```shell
npm install @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui
```

#### yarn

```shell
yarn add @univerjs/core @univerjs/design @univerjs/ui @univerjs-pro/license @univerjs-pro/pdfs @univerjs-pro/pdfs-ui react react-dom rxjs
```

#### bun

```shell
bun 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 样式，并合并应用启用的语言包：
   
   ```ts
   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'
   ```

1.
   导入 PDF Facade 入口。这个副作用导入会向 `FUniver` 添加 PDF 方法和枚举：
   
   ```ts
   import '@univerjs-pro/pdfs/facade'
   ```

1.
   创建运行时，注册显式插件栈，然后创建 PDF：
   
   ```ts
   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' })
   ```

#### `univer.registerPlugin` 与 `univer.registerPlugins` 方法

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

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

你也可以通过 `univer.registerPlugins` 传入一个数组，一次性注册多个插件。这对于需要集中管理插件的场景非常有用。

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

## 可选的缩略图 Worker

无需额外配置，页面缩略图也可以在主线程渲染。对于较大的文档，可通过 `thumbnailWorkerURL` 提供专用模块 Worker。

创建一个 Worker 入口，例如 `pdf-thumbnail.worker.ts`：

```ts
import { startPdfPageThumbnailWorker } from '@univerjs-pro/pdfs-ui'

startPdfPageThumbnailWorker()
```

注册 PDF UI 插件时传入其 URL：

```ts
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` 不属于仅本地运行的插件栈。不要单独注册它：请先按照[协作](https://docs.univer.ai/zh-CN/guides/pdfs/features/collaboration.md)文档安装并注册完整的 `@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 版本的 Univer 包：

#### npm

```bash
npm install @univerjs-pro/pdfs@alpha # Alpha 版本
npm install @univerjs-pro/pdfs@beta # Beta 版本
```

#### pnpm

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

#### yarn

```bash
yarn add @univerjs-pro/pdfs@alpha # Alpha 版本
yarn add @univerjs-pro/pdfs@beta # Beta 版本
```

#### bun

```bash
bun add @univerjs-pro/pdfs@alpha # Alpha 版本
bun add @univerjs-pro/pdfs@beta # Beta 版本
```

如果你在使用 alpha / beta 版本时遇到任何问题或者有任何反馈，请通过 [GitHub Issues](https://github.com/dream-num/univer/issues) 向 Univer 开发团队报告。

我们欢迎你对于这些早期版本的反馈。

## 下一步

* [快速入门](https://docs.univer.ai/zh-CN/guides/pdfs/getting-started/quickstart.md)
* [Facade API](https://docs.univer.ai/zh-CN/guides/pdfs/getting-started/facade.md)
* [授权与部署](https://docs.univer.ai/zh-CN/guides/license.md)