# 簡報資料結構

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

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

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [slides/model/slide-data.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/slides/model/slide-data.zh-TW.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 方法或已註冊的命令，不要直接修改快照物件。