# 頁面與元素

> 瞭解 PDF 頁面、原生來源內容、可編輯疊加層和座標系統。

- Human documentation: [https://docs.univer.ai/zh-TW/guides/pdfs/model/pages-and-elements](https://docs.univer.ai/zh-TW/guides/pdfs/model/pages-and-elements)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/pdfs/model/pages-and-elements.md](https://docs.univer.ai/zh-TW/guides/pdfs/model/pages-and-elements.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [pdfs/model/pages-and-elements.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/pdfs/model/pages-and-elements.zh-TW.mdx)

---

## 文件結構

`IPdfDocument` 包含正規化的 PDF 文件模型：

* `pages` 儲存頁面順序、大小、旋轉、圖層、標籤和原生 PDF 邊界方塊。
* `objects` 儲存語意文件物件。
* `displayLists` 保留呈現層級的 PDF 操作和來源保真度。
* `textStories` 讓可編輯文字流獨立於不穩定的 PDF 字形分組。
* `assets`、`styles` 和 `native` 保留可重複使用及來源特有的資源。
* `sources`、`edits` 和 `exportPlan` 記錄來源和匯出意圖。

對於匯入的 PDF，並非所有可見的來源操作都會成為可編輯的 Facade 元素。原生內容可以保留在顯示清單中，直到使用者操作將其提升或取代。

## 頁面

`FPdf` 依具現化後的順序讀取頁面，並可插入空白頁：

```ts
const pages = pdf.getPages()
const firstPage = pdf.getPageByIndex(0)
const pageById = firstPage ? pdf.getPageById(firstPage.getId()) : null
const appendedPage = pdf.insertPage()
```

`insertPage(index)` 接受從 `0` 到目前頁數之間的整數。新頁面會繼承相鄰頁面的大小、旋轉和 PDF 邊界方塊。如果沒有相鄰頁面，則使用 595 × 842 點的 A4 尺寸。

## 原生內容與可編輯疊加層

`FPdfPage.getElements()` 依疊放順序傳回持久化的可編輯疊加元素。型別化存取子會篩選同一疊加層：

| 存取子                | Facade 包裝器       |
| ------------------ | ---------------- |
| `getTextBoxes()`   | `FPdfTextBox`    |
| `getParagraphs()`  | `FPdfParagraph`  |
| `getLists()`       | `FPdfList`       |
| `getTables()`      | `FPdfTable`      |
| `getImages()`      | `FPdfImage`      |
| `getDividers()`    | `FPdfDivider`    |
| `getAnnotations()` | `FPdfAnnotation` |

`getTextSpans()` 與它們不同：它會列舉可見原生文字操作的快照。在文字片段上呼叫 `replaceText()` 會抑制原生操作並建立新的可編輯文字方塊。

## 座標系統

核心模型和公開 Facade 刻意使用不同的單位：

| 邊界                     | 單位與原點           |
| ---------------------- | --------------- |
| Facade 位置、大小、註解路徑和筆畫寬度 | PDF 點，左上角定位     |
| 核心模型頁面和物件幾何            | EMU，左上角原點       |
| 匯入的 `pdfBoxes` 和原生來源對應 | PDF 使用者空間，左下角原點 |

在應用程式碼中使用 `getTransform`、`setPosition`、`setSize`、`setRotation` 和型別化 Facade 插入選項。僅在建構較底層的模型資料時使用 `ptToEmu`、`emuToPt` 及相關轉換輔助函式。

## 公開編輯限制

Facade 會驗證多項模型限制：

* 寬度和高度必須是有限正數；位置和旋轉必須是有限數值。
* 清單層級範圍為 `0` 到 `8`；有序清單的起始編號必須是正整數。
* 表格必須具有正整數維度，且不可超過 10,000 個儲存格。
* Facade 註解插入支援醒目提示、底線、刪除線、波浪線和筆跡註解。
* 圖片不透明度範圍為 `0` 到 `1`，裁剪矩形必須具有正面積。
* 文字範圍使用起始位置包含、結束位置不包含的 UTF-16 位移。

如需面向任務的範例，請繼續閱讀[編輯 PDF](https://docs.univer.ai/zh-TW/guides/pdfs/features/core/editing.md)。