# Univer PDFs API

> 通过 PDF Facade API 创建、查找、保存、进入和卸载 PDF 单元。

- Human documentation: [https://docs.univer.ai/zh-CN/guides/pdfs/features/core/pdfs-api](https://docs.univer.ai/zh-CN/guides/pdfs/features/core/pdfs-api)

- Agent Markdown: [https://docs.univer.ai/zh-CN/guides/pdfs/features/core/pdfs-api.md](https://docs.univer.ai/zh-CN/guides/pdfs/features/core/pdfs-api.md)

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

PDF Facade 为 `FUniver` 扩展 PDF 单元和页面入口。创建 API 对象前，请先导入其副作用入口。

## 启用 PDF Facade

```ts
import { FUniver } from '@univerjs/core/facade'

import '@univerjs-pro/pdfs/facade'

const univerAPI = FUniver.newAPI(univer)
```

请在 Univer 实例中注册 `UniverPdfsPlugin`，使应用能够承载 PDF 单元。

## 创建、查找和保存 PDF 单元

省略 `document` 时，`createPdf()` 会创建包含一张空白 A4 页面的单元。传入先前由 `save()` 返回的快照即可恢复单元。

```ts
const pdf = univerAPI.createPdf({
  id: 'project-brief',
  name: 'Project brief',
})

const activePdf = univerAPI.getActivePdf()
const samePdf = univerAPI.getPdf(pdf.getId())
const snapshot = pdf.save()
```

更新正在运行的 PDF 时，请使用 Facade 方法或命令。保存的快照应作为独立的持久化数据处理。

## 进入页面

`FPdfPage` 是访问页面可编辑覆盖元素和导入原生文本的常用入口：

```ts
const firstPage = pdf.getPageByIndex(0) ?? pdf.insertPage()
const elements = firstPage.getElements()
const nativeText = firstPage.getTextSpans()
```

具体操作请继续阅读[页面与元素](https://docs.univer.ai/zh-CN/guides/pdfs/features/core/pages-and-elements.md)、[文本与列表](https://docs.univer.ai/zh-CN/guides/pdfs/features/core/text-and-lists.md)、[表格](https://docs.univer.ai/zh-CN/guides/pdfs/features/core/tables.md)、[图片与分隔线](https://docs.univer.ai/zh-CN/guides/pdfs/features/core/images-and-dividers.md)或[批注与原生文本](https://docs.univer.ai/zh-CN/guides/pdfs/features/core/annotations-and-native-text.md)。

## 卸载 PDF 单元

不再需要某个 PDF 单元时，请按 ID 卸载。只有在销毁整个应用时，才应释放根 `univer` 实例。

```ts
const pdf = univerAPI.getActivePdf()

if (pdf) {
  univerAPI.disposeUnit(pdf.getId())
}
```

准确签名与返回类型请参阅 [PDF Facade 参考](https://docs.univer.ai/zh-CN/reference/facade/pdf.md)。