# Univer Slides API

- Human documentation: [https://docs.univer.ai/zh-TW/guides/slides/features/core/slides-api](https://docs.univer.ai/zh-TW/guides/slides/features/core/slides-api)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/slides/features/core/slides-api.md](https://docs.univer.ai/zh-TW/guides/slides/features/core/slides-api.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [slides/features/core/slides-api.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/slides/features/core/slides-api.zh-TW.mdx)

---

Slides Facade 會在 `FUniver` 上擴充簡報和投影片物件。請在建立 API 物件前匯入其副作用入口：

```ts
import { FUniver } from '@univerjs/core/facade'

import '@univerjs-pro/slides/facade'

const univerAPI = FUniver.newAPI(univer)
```

## 建立和尋找簡報

```ts
const presentation = univerAPI.createPresentation({
  id: 'quarterly-review',
  name: 'Quarterly review',
})

const activePresentation = univerAPI.getActivePresentation()
const samePresentation = univerAPI.getPresentation(presentation.getId())
```

`createPresentation()` 接受部分 `ISlideData` 快照。傳入 `save()` 傳回的快照可以還原簡報。

## 操作簡報 Unit

`FPresentation` 提供 Unit 識別碼、名稱、頁面尺寸、投影片、目前投影片、轉場效果、權限和獨立快照：

```ts
presentation.setName('FY 2027 review')

const opening = presentation.getSlideByIndex(0) ?? presentation.appendSlide({
  name: 'Opening',
})

presentation.setActiveSlide(opening)
const snapshot = presentation.save()
```

不要透過修改 `snapshot` 更新執行中的簡報。請使用 Facade 方法或命令，確保算繪和歷史記錄保持同步。

## 進入投影片

`FSlide` 是投影片背景、講者備忘稿、轉場效果和元素的操作入口：

```ts
const slide = presentation.getActiveSlide()

if (slide) {
  const elements = slide.getElements()
  const notes = slide.getSpeakerNotes()
}
```

具體操作請繼續閱讀[投影片與版面配置](https://docs.univer.ai/zh-TW/guides/slides/features/core/slides-and-layouts.md)、[圖案與文字](https://docs.univer.ai/zh-TW/guides/slides/features/core/shapes-and-text.md)和[圖片與群組](https://docs.univer.ai/zh-TW/guides/slides/features/core/images-and-groups.md)。

## 解析命令目標

命令事件參數可能包含簡報和投影片識別碼。無需依賴目前選取項目即可解析目標：

```ts
const listener = univerAPI.addEvent(
  univerAPI.Event.CommandExecuted,
  ({ params }) => {
    const target = univerAPI.getSlideCommandTarget(params)
    console.log(target?.presentation.getId(), target?.slide.getId())
  }
)
```

宿主元件卸載時請釋放監聽器。

## 卸載簡報

不再需要某個 Slides 單元時，請依 ID 卸載。只有在銷毀整個應用程式時，才應釋放根 `univer` 執行個體。

```ts
const presentation = univerAPI.getActivePresentation()

if (presentation) {
  univerAPI.disposeUnit(presentation.getId())
}
```