# 页面与元素结构

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

- Source: [slides/model/slide-page.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/slides/model/slide-page.zh-CN.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`，不要继续复用已废弃的嵌入式载荷字段。