# 演示文稿数据结构

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

## ISlideData

`ISlideData` 是一份 Univer Slides 演示文稿的持久化快照，存储演示文稿元数据、有序的幻灯片集合、可选的母版与版式层、切换效果、主题和资源。

### 必填属性

| 属性                | 类型                           | 描述                    |
| ----------------- | ---------------------------- | --------------------- |
| `id`              | `string`                     | 演示文稿 unit 的唯一 ID。     |
| `name`            | `string`                     | 演示文稿显示名称。             |
| `defaultPageSize` | `ISlidePageSize`             | 页面未指定自身尺寸时使用的默认宽度和高度。 |
| `slideOrder`      | `string[]`                   | 按演示顺序排列的幻灯片 ID。       |
| `slides`          | `Record<string, ISlidePage>` | 以幻灯片 ID 为键的普通幻灯片。     |

### 可选属性

| 属性                        | 类型                                        | 描述                   |
| ------------------------- | ----------------------------------------- | -------------------- |
| `rev?`                    | `number`                                  | 快照修订号。               |
| `appVersion?`             | `string`                                  | 生成快照的 Univer 版本。     |
| `locale?`                 | `LocaleType`                              | 演示文稿语言环境。            |
| `masterPageOrder?`        | `string[]`                                | 按存储顺序排列的母版页面 ID。     |
| `masterPages?`            | `Record<string, ISlideMasterPage>`        | 以 ID 为键的母版页面。        |
| `layoutPageOrder?`        | `string[]`                                | 按存储顺序排列的版式页面 ID。     |
| `layoutPages?`            | `Record<string, ISlideLayoutPage>`        | 以 ID 为键的版式页面。        |
| `handoutMasterPageOrder?` | `string[]`                                | 按存储顺序排列的讲义母版 ID。     |
| `handoutMasterPages?`     | `Record<string, ISlideHandoutMasterPage>` | 以 ID 为键的讲义母版。        |
| `notesMasterPageOrder?`   | `string[]`                                | 按存储顺序排列的备注母版 ID。     |
| `notesMasterPages?`       | `Record<string, ISlideNotesMasterPage>`   | 以 ID 为键的备注母版。        |
| `activeSlideId?`          | `string`                                  | 当前活动幻灯片 ID。          |
| `transitionRecords?`      | `Record<string, ISlideTransition>`        | 以切换效果 ID 为键的可复用切换效果。 |
| `slideTransitionRefs?`    | `Record<string, string>`                  | 幻灯片 ID 到切换效果 ID 的映射。 |
| `theme?`                  | `ISlideThemeData`                         | 演示文稿默认主题。            |
| `themes?`                 | `Record<string, ISlideThemeData>`         | 以主题 ID 为键的附加主题。      |
| `zoomRatio?`              | `number`                                  | 持久化的演示文稿缩放比例。        |
| `resources?`              | `IResources`                              | Slides 与功能插件提供的资源。   |
| `custom?`                 | `SlideCustomData`                         | 应用自定义的演示文稿元数据。       |

### 有序页面记录

`slideOrder` 中的每个 ID 都应对应 `slides` 中的一项。可选的母版、版式、讲义母版和备注母版层也采用“顺序数组 + 以 ID 为键的记录”这一结构。存在 `activeSlideId` 时，它应对应 `slides` 中的一项。

```typescript
import type { ISlideData } from '@univerjs-pro/slides'
import { PageTypeEnum } from '@univerjs-pro/slides'

const slideData: ISlideData = {
  id: 'deck-1',
  name: '产品路线图',
  defaultPageSize: { width: 960, height: 540 },
  slideOrder: ['slide-1'],
  slides: {
    'slide-1': {
      id: 'slide-1',
      name: '开场页',
      pageType: PageTypeEnum.Slide,
      elementOrder: [],
      elements: {},
    },
  },
  activeSlideId: 'slide-1',
}
```

### 使用方法

将快照传给 `univerAPI.createPresentation(slideData)` 可以恢复演示文稿。通过 `presentation.save()` 获取当前 `ISlideData` 快照，用于持久化、导出、打印或服务端处理。

> [!WARNING: 注意]
> 快照是持久化数据，不是运行中的 `SlideModel`。演示文稿启动后，请使用 Slides Facade 方法或已注册的命令，不要直接修改快照对象。