# PPTX API

PPTX APIs are called through the `app` returned by `widget.render()`:

```ts
const { widget } = await OfficeSdk.openfile({ docId: "demo-pptx", fileName: "demo.pptx", file });
const app = await widget.mount("#office-container").render();
```

## Components

| Component | Description |
| --- | --- |
| `Document` | Page number, zoom, layout, export, and read-only state |
| `Paragraph` | Text font, color, size, bold, italic, underline, strikethrough, and horizontal paragraph alignment |
| `TextBox` | Text box vertical alignment |
| `Player` | Slide playback and full-screen playback |
| `Selection` | Selection type, text style queries, and selection change events |
| `Viewer` | Current active target in the thumbnail area |
| `UndoRedo` | Undo, redo, and availability state |

## Quick Example

```ts
app.Document.setZoom(120);
app.Document.goToSlide(2);

app.Paragraph.setFontName("Arial");
app.Paragraph.setBold(true);
app.Paragraph.setAlignment(2);

app.TextBox.setVerticalAlignment(1);
app.Player.play(1);
```

Event example:

```ts
function onSelectionChange(info) {
  console.log(info.selectType);
}

app.Selection.addEventListener("SELECTION_CHANGE", onSelectionChange);
```

## Document

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `getSlideInfo` | `(): { total: number; current: number }` | `{ total; current }` | Gets total slide count and current slide. Page numbers start from `1`. |
| `getCurrentSlideIndex` | `(): number` | `number` | Gets current page number. Page numbers start from `1`. |
| `getSlideCount` | `(): number` | `number` | Gets total slide count. |
| `getZoom` | `(): number` | `number` | Gets zoom percentage. |
| `setZoom` | `(value: number): void` | `void` | Sets zoom percentage. Common values include `80`, `100`, and `120`. |
| `autoZoom` | `(): void` | `void` | Adjusts the zoom automatically. |
| `focusEditor` | `(): void` | `void` | Currently a no-op in the PPTX implementation. |
| `updateVisibleArea` | `(): void` | `void` | Recalculates the visible area. |
| `goToSlide` | `(slideNum: number): void` | `void` | Goes to a slide. `slideNum` starts from `1`. |
| `deleteSlides` | `(slides?: number[]): void` | `void` | Deletes specified slide indexes. If omitted, deletes the currently selected slide. `slides` uses zero-based indexes. |
| `addSlide` | `(layout?: SlideLayoutRef, position?: number): void` | `void` | Inserts a new slide. `layout` uses layout indexes, and `position` is the zero-based insert position. If `layout` is omitted, the layout near the current selection is reused. |
| `getSlideLayouts` | `(force?: boolean): SlideLayoutItem[][]` | `SlideLayoutItem[][]` | Gets layouts grouped by slide master. When `force = true`, refreshes the cache. |
| `exportDocument` | `(): Promise<void>` | `Promise<void>` | Exports the original PPTX file. |
| `exportPdf` | `(printOptions?: unknown): Promise<void>` | `Promise<void>` | Exports PDF with print options. |
| `copy` | `(): Promise<void>` | `Promise<void>` | Copies the current selection. |
| `cut` | `(): Promise<void>` | `Promise<void>` | Cuts the current selection. |
| `paste` | `(): Promise<void>` | `Promise<void>` | Pastes into the current selection. |
| `getColorPalette` | `(): { theme: unknown[]; standard: unknown[] }` | `{ theme; standard }` | Gets theme colors and standard colors. |
| `startReadOnly` | `(): void` | `void` | Enters read-only state. |
| `endReadOnly` | `(): void` | `void` | Exits read-only state. |
| `isReadOnly` | `(): boolean` | `boolean` | Whether the current state is read-only. |
| `isDisable` | `(): boolean` | `boolean` | Whether the current editor is disabled. |

```ts
type SlideLayoutRef = {
  masterIndex: number;
  layoutIndex: number;
};

type SlideLayoutItem = {
  img: unknown;
  name: string;
  xmlName: string;
  id: string | number;
  layoutIndex: number;
  slideMasterIndex: number;
};
```

`goToSlide(slideNum)` uses display page numbers starting from `1`; `deleteSlides(slides)` and `addSlide(layout, position)` use zero-based underlying indexes.

Document example:

```ts
const pages = app.Document.getSlideInfo();
console.log(pages.current, pages.total);

app.Document.goToSlide(1);
const layoutGroups = app.Document.getSlideLayouts();
const layout = layoutGroups[0][0];
app.Document.addSlide(
  {
    masterIndex: layout.slideMasterIndex,
    layoutIndex: layout.layoutIndex
  },
  1
);
app.Document.deleteSlides([0]);

await app.Document.exportDocument();
await app.Document.exportPdf();
```

Document component events:

| Event Name | Payload | Description |
| --- | --- | --- |
| `DOCUMENT_READY` | Raw event parameters | Document ready. |
| `DOCUMENT_EXPORT_READY` | Raw event parameters | Export completed. |
| `DOCUMENT_EDITING_ENABLED` | None | The document entered editable state. |
| `DOCUMENT_EDITING_DISABLED` | None | The document exited editable state. |
| `PPTX_SLIDES_CHANGED` | `(currentPage: number, totalPages: number)` | Current page or page count changed. |
| `PPTX_ZOOM_CHANGE` | `(zoom: number)` | Zoom changed. |
| `PPTX_FIRST_PAGE_LOADED` | None | First page loaded. |
| `PPTX_START_LOADING` | None | Loading started. |

`exportPdf(...)` requires a secure context (normally HTTPS or localhost), `window.queryLocalFonts`, and permission to access local fonts. If these requirements are not met, the current implementation does not perform the PDF export.

## Paragraph

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `setFontName` | `(value: string): void` | `void` | Sets font family. |
| `setFontColor` | `(value: string \| { hex: string; [key: string]: unknown }): void` | `void` | Sets font color. Prefer an object containing `hex`; the current string parser has a known limitation when any color channel is `0`. |
| `setFontSize` | `(value: number \| string): void` | `void` | Sets font size. |
| `setBold` | `(value: boolean): void` | `void` | Sets bold. |
| `setItalic` | `(value: boolean): void` | `void` | Sets italic. |
| `setUnderline` | `(value: boolean): void` | `void` | Sets underline. |
| `setStrikeThrough` | `(value: boolean): void` | `void` | Sets strikethrough. |
| `setAlignment` | `(value: 0 \| 1 \| 2 \| 3 \| 4): void` | `void` | Sets horizontal paragraph alignment. |
| `decreaseFontSize` | `(): void` | `void` | Decreases font size. |
| `increaseFontSize` | `(): void` | `void` | Increases font size. |

`setAlignment(value)` enum:

| Value | Description |
| --- | --- |
| `0` | Right |
| `1` | Left |
| `2` | Center |
| `3` | Justified |
| `4` | Distributed |

Paragraph example:

```ts
app.Paragraph.setFontName("Microsoft YaHei");
app.Paragraph.setFontColor({ hex: "#4472C4" });
app.Paragraph.setFontSize(18);
app.Paragraph.setBold(true);
app.Paragraph.setItalic(false);
app.Paragraph.setUnderline(true);
app.Paragraph.setStrikeThrough(false);
app.Paragraph.setAlignment(2);
app.Paragraph.increaseFontSize();
```

## TextBox

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `setVerticalAlignment` | `(value: 0 \| 1 \| 2 \| 3 \| 4): void` | `void` | Sets text box vertical alignment. |

`setVerticalAlignment(value)` enum:

| Value | Description |
| --- | --- |
| `0` | Top |
| `1` | Center |
| `2` | Bottom |
| `3` | Justified distribution |
| `4` | Distributed |

Example:

```ts
app.TextBox.setVerticalAlignment(1);
```

## Player

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `playFirst` | `(): void` | `void` | Plays from the first slide. |
| `playLast` | `(): void` | `void` | Plays the last slide. |
| `play` | `(fromType: 1 \| 2): void` | `void` | Starts slide playback. |
| `playPrevious` | `(): void` | `void` | Plays the previous slide. |
| `playNext` | `(): void` | `void` | Plays the next slide. |
| `enterFullScreen` | `(fromType: 1 \| 2): void` | `void` | Enters full-screen playback. |
| `exitFullScreen` | `(): void` | `void` | Exits full screen. |

`fromType`:

| Value | Description |
| --- | --- |
| `1` | From beginning |
| `2` | From current slide |

Example:

```ts
app.Player.play(2);
app.Player.enterFullScreen(1);
app.Player.exitFullScreen();
```

## Selection

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `isTextSelected` | `(): boolean` | `boolean` | Whether text is currently selected. |
| `isTableSelected` | `(): boolean` | `boolean` | Whether a table is currently selected. |
| `isShapeSelected` | `(): boolean` | `boolean` | Whether a shape is currently selected. |
| `isSmartArtSelected` | `(): boolean` | `boolean` | Whether SmartArt is currently selected. |
| `isChartSelected` | `(): boolean` | `boolean` | Whether a chart is currently selected. |
| `isUnderline` | `(): boolean` | `boolean` | Whether the current text has single underline. |
| `isStrikeThrough` | `(): boolean` | `boolean` | Whether the current text has single strikethrough. |
| `getFontSize` | `(): string` | `string` | Gets current font size. For mixed font sizes, returns the minimum font size plus `+`. |
| `getFontName` | `(): string \| null` | `string \| null` | Gets current font family. For mixed fonts, returns an empty string. |
| `isBold` | `(): boolean \| 0 \| null` | `boolean \| 0 \| null` | Gets bold state. Returns `0` for mixed states. |
| `isItalic` | `(): boolean \| 0 \| null` | `boolean \| 0 \| null` | Gets italic state. Returns `0` for mixed states. |
| `getFontColor` | `(): string` | `string` | Gets font color as an `rgba(...)` string. The alpha value comes from underlying data and must not be assumed to be CSS-normalized to `0` through `1`. |
| `getAlignment` | `(): "default" \| "right" \| "left" \| "center" \| "justify" \| "distribute" \| "nil"` | `string` | Gets horizontal paragraph alignment. |
| `getVerticalAlignment` | `(): "top" \| "center" \| "bottom" \| "default" \| "NIL" \| undefined` | `string \| undefined` | Gets text box vertical alignment. |

Selection example:

```ts
if (app.Selection.isTextSelected()) {
  console.log(app.Selection.getFontName());
  console.log(app.Selection.getFontColor());
}
```

`getAlignment()` return values:

| Value | Description |
| --- | --- |
| `"default"` | Default alignment. |
| `"right"` | Right. |
| `"left"` | Left. |
| `"center"` | Center. |
| `"justify"` | Justified. |
| `"distribute"` | Distributed. |
| `"nil"` | Multiple selected contents do not share one horizontal alignment value. |

`getVerticalAlignment()` return values:

| Value | Description |
| --- | --- |
| `"top"` | Top. |
| `"center"` | Center. |
| `"bottom"` | Bottom. |
| `"default"` | Default vertical alignment. |
| `"NIL"` | Multiple selected contents do not share one vertical alignment value. |
| `undefined` | No recognizable vertical alignment value currently. |

Selection component events:

| Event Name | Payload |
| --- | --- |
| `SELECTION_CHANGE` | `PptxSelectionChange` |

```ts
type PptxSelectionChange = {
  selectType: number;
  bold?: boolean | 0 | null;
  italic?: boolean | 0 | null;
  fontName?: string | null;
  fontSize?: string;
  fontColor?: string;
  underline?: boolean;
  strikeout?: boolean;
  alignHorizontal?: string;
  alignVertical?: string;
  canCopy: boolean;
};
```

`selectType` is a bit flag and can be combined with bitwise OR:

| Value | Description |
| --- | --- |
| `0` | No stable selection |
| `1` | Table |
| `2` | Shape |
| `4` | Text |
| `6` | Shape + text |
| `8` | SmartArt |
| `16` | Chart |
| `32` | Image |

Common combined values:

| Value | Description |
| --- | --- |
| `6` | Shape + text |

## Viewer

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `getActiveZoom` | `(): null \| "" \| "Thumbnail" \| "ThumbnailGapLine"` | `string \| null` | Gets the current active target in the thumbnail area. Returns `null` before the first active-target event. |

Return values:

| Value | Description |
| --- | --- |
| `null` | No active-target event has been received yet. |
| `""` | No stable target currently. |
| `"Thumbnail"` | Thumbnail. |
| `"ThumbnailGapLine"` | Gap line between thumbnails. |

## UndoRedo

| Method | Signature | Returns | Description |
| --- | --- | --- | --- |
| `undo` | `(): void` | `void` | Undo. |
| `redo` | `(): void` | `void` | Redo. |
| `canUndo` | `(): boolean` | `boolean` | Whether undo is available. |
| `canRedo` | `(): boolean` | `boolean` | Whether redo is available. |

UndoRedo component events:

| Event Name | Payload |
| --- | --- |
| `UNDO_REDO_STATE_CHANGE` | Raw event parameters |

Example:

```ts
if (app.UndoRedo.canUndo()) {
  app.UndoRedo.undo();
}
```
