PPTX API

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

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

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:

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.

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:

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:

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:

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:

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:

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

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:

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