# UI 概览

> 配置 PDF Canvas、编辑器控件、语言包和缩略图 Worker。

- Human documentation: [https://docs.univer.ai/zh-CN/guides/pdfs/ui/overview](https://docs.univer.ai/zh-CN/guides/pdfs/ui/overview)

- Agent Markdown: [https://docs.univer.ai/zh-CN/guides/pdfs/ui/overview.md](https://docs.univer.ai/zh-CN/guides/pdfs/ui/overview.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [pdfs/ui/overview.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/pdfs/ui/overview.zh-CN.mdx)

---

`@univerjs-pro/pdfs-ui` 将 PDF 单元挂载到 Univer 的标准工作台中，并通过 Univer Office SDK 许可证授权。

## 包的职责

| 包                           | 职责                                           |
| --------------------------- | -------------------------------------------- |
| `@univerjs-pro/pdfs`        | 注册 `UNIVER_PDF` 单元、文档模型和可持久化的 PDF 命令。        |
| `@univerjs-pro/pdfs-ui`     | 挂载浏览器 Canvas、缩略图栏和底栏；默认启用本地编辑控件。             |
| `@univerjs-pro/pdfs-editor` | 声明协同编辑侧的依赖，不挂载 PDF UI，也不控制 `editor.enabled`。 |

`UniverPdfsUIPlugin` 依赖 `UniverLicensePlugin` 和 `UniverPdfsPlugin`。请先完成带许可证的 PDF 基础配置，再注册 UI 插件。

## 注册 UI 插件

```ts
import { UniverPdfsUIPlugin } from '@univerjs-pro/pdfs-ui'
import PdfsUIZhCN from '@univerjs-pro/pdfs-ui/locale/zh-CN'

import '@univerjs-pro/pdfs-ui/lib/index.css'

univer.registerPlugin(UniverPdfsUIPlugin)
```

将 `PdfsUIZhCN` 合并到传给 `new Univer(...)` 的语言包中。该语言包包含 PDF 功能区、检查器、右键菜单和页面栏的文案。

## 查看和编辑模式

插件始终挂载页面缩略图栏、PDF Canvas 和底栏。编辑默认开启，并额外注册功能区、右键菜单、检查器、剪贴板、插入命令，以及编辑操作和控制器。

如果当前应用只需查看 PDF，可以关闭编辑控件：

```ts
univer.registerPlugin(UniverPdfsUIPlugin, {
  editor: { enabled: false },
})
```

此选项只改变已挂载的 UI 以及编辑专用控制器和服务，不是权限策略，也不会修改已保存的 PDF 快照。

## 缩略图 Worker

`thumbnailWorkerURL` 接受字符串、`URL` 或现有 `Worker`。对应模块必须启动包导出的 Worker 运行时：

```ts title="pdf-thumbnail-worker.ts"
import { startPdfPageThumbnailWorker } from '@univerjs-pro/pdfs-ui'

startPdfPageThumbnailWorker()
```

```ts
univer.registerPlugin(UniverPdfsUIPlugin, {
  thumbnailWorkerURL: new URL('./pdf-thumbnail-worker.js', import.meta.url),
})
```

该 Worker 必须运行在专用 Worker 作用域中。未配置 Worker、浏览器缺少所需 API，或页面依赖只能在主线程解析的资源时，缩略图会回退到主线程渲染。

## 公共 API 边界

UI 会在内部调用 PDF 命令和服务，功能区中有按钮并不代表存在同名公共方法。支持的编程式编辑请查看 [PDF Facade 指南](https://docs.univer.ai/zh-CN/guides/pdfs/getting-started/facade.md)，格式转换请查看[导入导出](https://docs.univer.ai/zh-CN/guides/pdfs/features/import-export.md)，浏览器打印请查看[打印](https://docs.univer.ai/zh-CN/guides/pdfs/features/print.md)。