# Univer PDFs API

> 透過 PDF Facade API 建立、尋找、儲存、進入和卸載 PDF 單元。

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [pdfs/features/core/pdfs-api.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/pdfs/features/core/pdfs-api.zh-TW.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-TW/guides/pdfs/features/core/pages-and-elements.md)、[文字與清單](https://docs.univer.ai/zh-TW/guides/pdfs/features/core/text-and-lists.md)、[表格](https://docs.univer.ai/zh-TW/guides/pdfs/features/core/tables.md)、[圖片與分隔線](https://docs.univer.ai/zh-TW/guides/pdfs/features/core/images-and-dividers.md)或[註解與原生文字](https://docs.univer.ai/zh-TW/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-TW/reference/facade/pdf.md)。