# PPTX API

PPTX API 通过 `widget.render()` 返回的 `app` 调用：

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

## 组件#

Component | 说明
--- | ---
`Document` | 页码、缩放、布局、导出、只读状态
`Paragraph` | 文本字体、颜色、字号、加粗、斜体、下划线、删除线、段落水平对齐
`TextBox` | 文本框垂直对齐
`Player` | 幻灯片播放、全屏播放
`Selection` | 选区类型、文本样式查询、选区变化事件
`Viewer` | 获取缩略图区域当前活动目标。
`UndoRedo` | 撤销、重做和可用状态

## 快速示例#

    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);

事件示例：

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

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

## Document#

方法 | 签名 | 返回 | 说明
--- | --- | --- | ---
`getSlideInfo` | `(): { total: number; current: number }` | `{ total; current }` | 获取总页数与当前页，页码从 `1` 开始。
`getCurrentSlideIndex` | `(): number` | `number` | 获取当前页码，页码从 `1` 开始。
`getSlideCount` | `(): number` | `number` | 获取总页数。
`getZoom` | `(): number` | `number` | 获取缩放比例。
`setZoom` | `(value: number): void` | `void` | 设置缩放比例，常用值如 `80`、`100`、`120`。
`autoZoom` | `(): void` | `void` | 自动缩放。
`focusEditor` | `(): void` | `void` | 当前 PPTX 实现为空操作。
`updateVisibleArea` | `(): void` | `void` | 重新计算可视区域。
`goToSlide` | `(slideNum: number): void` | `void` | 跳转到幻灯片，`slideNum` 从 `1` 开始。
`deleteSlides` | `(slides?: number[]): void` | `void` | 删除指定幻灯片索引；不传时删除当前选中的幻灯片。`slides` 使用从 `0` 开始的索引。
`addSlide` | `(layout?: SlideLayoutRef, position?: number): void` | `void` | 插入新幻灯片；`layout` 使用布局索引，`position` 是从 `0` 开始的插入位置。不传 `layout` 时沿用当前选区附近的布局。
`getSlideLayouts` | `(force?: boolean): SlideLayoutItem[][]` | `SlideLayoutItem[][]` | 按母版分组获取布局列表；`force = true` 时刷新缓存。
`exportDocument` | `(): Promise<void>` | `Promise<void>` | 导出 PPTX 原文件。
`exportPdf` | `(printOptions?: unknown): Promise<void>` | `Promise<void>` | 按打印配置导出 PDF。
`copy` | `(): Promise<void>` | `Promise<void>` | 复制当前选区。
`cut` | `(): Promise<void>` | `Promise<void>` | 剪切当前选区。
`paste` | `(): Promise<void>` | `Promise<void>` | 粘贴到当前选区。
`getColorPalette` | `(): { theme: unknown[]; standard: unknown[] }` | `{ theme; standard }` | 获取主题色和标准色。
`startReadOnly` | `(): void` | `void` | 进入只读状态。
`endReadOnly` | `(): void` | `void` | 退出只读状态。
`isReadOnly` | `(): boolean` | `boolean` | 当前是否只读。
`isDisable` | `(): boolean` | `boolean` | 当前编辑器是否处于禁用状态。

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

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

`goToSlide(slideNum)` 使用从 `1` 开始的展示页码；`deleteSlides(slides)` 和 `addSlide(layout, position)` 使用从 `0` 开始的底层索引。

Document 示例：

    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 支持的组件事件：

事件名 | payload | 说明
--- | --- | ---
`DOCUMENT_READY` | 事件参数透传 | 文档 ready。
`DOCUMENT_EXPORT_READY` | 事件参数透传 | 导出完成。
`DOCUMENT_EDITING_ENABLED` | 无 | 文档进入可编辑状态。
`DOCUMENT_EDITING_DISABLED` | 无 | 文档退出可编辑状态。
`PPTX_SLIDES_CHANGED` | `(currentPage: number, totalPages: number)` | 当前页或页数变化。
`PPTX_ZOOM_CHANGE` | `(zoom: number)` | 缩放变化。
`PPTX_FIRST_PAGE_LOADED` | 无 | 第一页加载完成。
`PPTX_START_LOADING` | 无 | 开始加载。

`exportPdf(...)` 需要安全上下文（例如 HTTPS 或 localhost）、`window.queryLocalFonts` 和本地字体访问权限。不满足条件时当前实现不会执行 PDF 导出。

## Paragraph#

方法 | 签名 | 返回 | 说明
--- | --- | --- | ---
`setFontName` | `(value: string): void` | `void` | 设置字体。
`setFontColor` | `(value: string \| { hex: string; [key: string]: unknown }): void` | `void` | 设置字体颜色。推荐传入包含 `hex` 的对象；字符串形式当前在任一颜色通道为 `0` 时存在解析限制。
`setFontSize` | `(value: number \| string): void` | `void` | 设置字号。
`setBold` | `(value: boolean): void` | `void` | 设置粗体。
`setItalic` | `(value: boolean): void` | `void` | 设置斜体。
`setUnderline` | `(value: boolean): void` | `void` | 设置下划线。
`setStrikeThrough` | `(value: boolean): void` | `void` | 设置删除线。
`setAlignment` | `(value: 0 \| 1 \| 2 \| 3 \| 4): void` | `void` | 设置段落水平对齐。
`decreaseFontSize` | `(): void` | `void` | 减小字号。
`increaseFontSize` | `(): void` | `void` | 增大字号。

`setAlignment(value)` 枚举：

值 | 说明
--- | ---
`0` | 右对齐
`1` | 左对齐
`2` | 居中
`3` | 两端对齐
`4` | 分散对齐

Paragraph 示例：

    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#

方法 | 签名 | 返回 | 说明
--- | --- | --- | ---
`setVerticalAlignment` | `(value: 0 \| 1 \| 2 \| 3 \| 4): void` | `void` | 设置文本框垂直对齐。

`setVerticalAlignment(value)` 枚举：

值 | 说明
--- | ---
`0` | 顶部
`1` | 居中
`2` | 底部
`3` | 两端分布
`4` | 分散分布

示例：

    app.TextBox.setVerticalAlignment(1);

## Player#

方法 | 签名 | 返回 | 说明
--- | --- | --- | ---
`playFirst` | `(): void` | `void` | 播放第一页。
`playLast` | `(): void` | `void` | 播放最后一页。
`play` | `(fromType: 1 \| 2): void` | `void` | 播放幻灯片。
`playPrevious` | `(): void` | `void` | 播放上一页。
`playNext` | `(): void` | `void` | 播放下一页。
`enterFullScreen` | `(fromType: 1 \| 2): void` | `void` | 进入全屏。
`exitFullScreen` | `(): void` | `void` | 退出全屏。

`fromType`：

值 | 说明
--- | ---
`1` | 从头开始
`2` | 从当前页开始

示例：

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

## Selection#

方法 | 签名 | 返回 | 说明
--- | --- | --- | ---
`isTextSelected` | `(): boolean` | `boolean` | 当前是否选中文本。
`isTableSelected` | `(): boolean` | `boolean` | 当前是否选中表格。
`isShapeSelected` | `(): boolean` | `boolean` | 当前是否选中图形。
`isSmartArtSelected` | `(): boolean` | `boolean` | 当前是否选中 SmartArt。
`isChartSelected` | `(): boolean` | `boolean` | 当前是否选中图表。
`isUnderline` | `(): boolean` | `boolean` | 当前文本是否为单下划线。
`isStrikeThrough` | `(): boolean` | `boolean` | 当前文本是否为单删除线。
`getFontSize` | `(): string` | `string` | 获取当前字号；混合字号时返回最小字号加 `+`。
`getFontName` | `(): string \| null` | `string \| null` | 获取当前字体；混合字体时返回空字符串。
`isBold` | `(): boolean \| 0 \| null` | `boolean \| 0 \| null` | 获取粗体状态；混合状态时返回 `0`。
`isItalic` | `(): boolean \| 0 \| null` | `boolean \| 0 \| null` | 获取斜体状态；混合状态时返回 `0`。
`getFontColor` | `(): string` | `string` | 获取字体颜色，当前返回 `rgba(...)` 字符串；alpha 值来自底层数据，不能假定已归一化到 CSS 的 `0` 到 `1`。
`getAlignment` | `(): "default" \| "right" \| "left" \| "center" \| "justify" \| "distribute" \| "nil"` | `string` | 获取段落水平对齐。
`getVerticalAlignment` | `(): "top" \| "center" \| "bottom" \| "default" \| "NIL" \| undefined` | `string \| undefined` | 获取文本框垂直对齐。

Selection 示例：

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

`getAlignment()` 返回值：

值 | 说明
--- | ---
`"default"` | 默认对齐。
`"right"` | 右对齐。
`"left"` | 左对齐。
`"center"` | 居中。
`"justify"` | 两端对齐。
`"distribute"` | 分散对齐。
`"nil"` | 多选内容没有统一水平对齐值。

`getVerticalAlignment()` 返回值：

值 | 说明
--- | ---
`"top"` | 顶部。
`"center"` | 居中。
`"bottom"` | 底部。
`"default"` | 默认垂直对齐。
`"NIL"` | 多选内容没有统一垂直对齐值。
`undefined` | 当前没有可识别的垂直对齐值。

Selection 支持的组件事件：

事件名 | payload
--- | ---
`SELECTION_CHANGE` | `PptxSelectionChange`

    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` 是位标记，可通过按位或组合：

值 | 说明
--- | ---
`0` | 无稳定选区
`1` | 表格
`2` | 图形
`4` | 文本
`6` | 图形 + 文本
`8` | SmartArt
`16` | 图表
`32` | 图片

常见组合值：

值 | 说明
--- | ---
`6` | 图形 + 文本

## Viewer#

方法 | 签名 | 返回 | 说明
--- | --- | --- | ---
`getActiveZoom` | `(): null \| "" \| "Thumbnail" \| "ThumbnailGapLine"` | `string \| null` | 获取缩略图区域当前活动目标；首次收到活动目标事件前返回 `null`。

返回值：

值 | 说明
--- | ---
`null` | 尚未收到活动目标事件。
`""` | 当前没有稳定目标。
`"Thumbnail"` | 缩略图。
`"ThumbnailGapLine"` | 缩略图间隔线。

## UndoRedo#

方法 | 签名 | 返回 | 说明
--- | --- | --- | ---
`undo` | `(): void` | `void` | 撤销。
`redo` | `(): void` | `void` | 重做。
`canUndo` | `(): boolean` | `boolean` | 是否可撤销。
`canRedo` | `(): boolean` | `boolean` | 是否可重做。

UndoRedo 支持的组件事件：

事件名 | payload
--- | ---
`UNDO_REDO_STATE_CHANGE` | 事件参数透传

示例：

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