# 頁面與元素結構

- Human documentation: [https://docs.univer.ai/zh-TW/guides/slides/model/slide-page](https://docs.univer.ai/zh-TW/guides/slides/model/slide-page)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/slides/model/slide-page.md](https://docs.univer.ai/zh-TW/guides/slides/model/slide-page.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [slides/model/slide-page.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/slides/model/slide-page.zh-TW.mdx)

---

## ISlidePage

`ISlidePage` 描述 Univer Slides 中的單個頁面物件。普通投影片、母片、版面配置、講義母片和備註母片都使用這個結構，並透過 `pageType` 和可選屬性區塊區分。

### 頁面屬性

| 屬性                 | 類型                                      | 描述                                   |
| ------------------ | --------------------------------------- | ------------------------------------ |
| id                 | `string`                                | 頁面唯一 ID。                             |
| pageType           | `PageType`                              | 頁面類型，例如 `SLIDE`、`MASTER` 或 `LAYOUT`。 |
| zIndex             | `number`                                | 頁面的渲染順序。                             |
| title              | `string`                                | 頁面標題。                                |
| description        | `string`                                | 頁面描述。                                |
| pageBackgroundFill | `IColorStyle`                           | 頁面背景填充。                              |
| colorScheme?       | `ThemeColorType`                        | 頁面使用的主題色方案。                          |
| pageElements       | `{ [elementId: string]: IPageElement }` | 頁面上的元素，以元素 ID 為 key。                 |
| slideProperties?   | `ISlideProperties`                      | 普通投影片頁面的屬性。                          |
| layoutProperties?  | `ILayoutProperties`                     | 版面配置頁面的屬性。                           |
| masterProperties?  | `IMasterProperties`                     | 母片頁面的屬性。                             |

## IPageElement

`IPageElement` 是頁面元素的通用容器。每個元素都有 `left`、`top`、`width`、`height`、`angle`、`scaleX`、`scaleY`、`flipX`、`flipY` 等變換欄位，並根據 `type` 選擇一個內容載荷。

| 元素類型                          | 載荷            | 描述                                   |
| ----------------------------- | ------------- | ------------------------------------ |
| `PageElementType.SHAPE`       | `shape`       | 預設或自訂形狀，包括形狀文字和形狀屬性。                 |
| `PageElementType.IMAGE`       | `image`       | 圖片屬性，以及可選的佔位符和連結資訊。                  |
| `PageElementType.TEXT`        | `richText`    | 富文字元素。`rich` 欄位可以儲存 `IDocumentData`。 |
| `PageElementType.SPREADSHEET` | `spreadsheet` | 已廢棄的嵌入式工作表載荷。                        |
| `PageElementType.DOCUMENT`    | `document`    | 已廢棄的嵌入式文件載荷。                         |
| `PageElementType.SLIDE`       | `slide`       | 已廢棄的嵌入式投影片載荷。                        |

### 範例

```typescript
const page: ISlidePage = {
  id: 'slide-1',
  pageType: PageType.SLIDE,
  zIndex: 10,
  title: '議程',
  description: '',
  pageBackgroundFill: { rgb: 'rgb(255,255,255)' },
  pageElements: {
    title: {
      id: 'title',
      zIndex: 1,
      left: 72,
      top: 64,
      width: 600,
      height: 80,
      title: 'Title',
      description: '',
      type: PageElementType.TEXT,
      richText: {
        text: '季度複盤',
      },
    },
  },
}
```

### 注意事項

* `pageOrder` 控制可見投影片順序，`zIndex` 控制繪製順序。
* 文字元素可以透過 `richText.text` 儲存純文字，也可以透過 `richText.rich` 儲存更完整的文件資料。
* 外掛自有的元素載荷應使用 `customBlock`，不要繼續重用已廢棄的嵌入式載荷欄位。