DOCX API

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

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

Components

Component	Description
Document	Export, zoom, page view, page navigation, page setup, copy/cut/paste, paragraph marks, page break display, and section break display
Paragraph	Font, text style, paragraph alignment, line spacing, bullets, and numbering
Table	Table insertion, deletion, row/column operations, merge, and unmerge
Selection	Selection, cursor, break insertion, and selection change events
Finder	Search, previous/next result, and search status
UndoRedo	Undo, redo, and availability state

Quick Example

app.Document.setZoom(120);
app.Paragraph.setFontName("Arial");
app.Paragraph.setFontSize(14);
app.Paragraph.setFontColor({ r: 68, g: 114, b: 196 });

if (app.Table.isInTable()) {
  app.Table.addRows("End", 1);
}

app.Finder.search("contract");
app.Finder.selectNext();

Event example:

function onSelectionChange(info) {
  console.log("selection", info);
}

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

Document

Method	Signature	Returns	Description
exportDocument	(): Promise<void>	Promise<void>	Exports the original document.
exportPdf	(printOptions?: unknown): Promise<void>	Promise<void>	Exports PDF with print options.
setZoom	(value: number): void	void	Sets zoom percentage. Common values include 80, 100, and 120.
getZoom	(): number	number	Gets the current zoom percentage.
focusEditor	(): void	void	Moves focus back to the editor area.
updateVisibleArea	(): void	void	Recalculates the visible area.
setPageView	(mode: "single" | "multi" | "wide"): void	void	Switches between single-page, multi-page, and page-width views.
goToPage	(pageNum: number): void	void	Goes to a page. pageNum starts from 1.
getCurrentPagePosition	(pageIndex?: number): PagePosition | {}	PagePosition | {}	Gets page information. pageIndex is zero-based; if omitted, the current page is used. The current implementation does not reliably distinguish an explicit 0 from an omitted value.
setPageOrientation	(value: "Portrait" | "Landscape"): void	void	Sets portrait or landscape orientation.
setPageSize	(width: number, height: number): void	void	Sets page width and height. Built-in UI passes centimeter values.
copy	(): Promise<void>	Promise<void>	Triggers copy in the editor area.
cut	(): Promise<void>	Promise<void>	Triggers cut in the editor area.
paste	(): Promise<void>	Promise<void>	Triggers paste in the editor area.
startReadOnly	(): void	void	Enters read-only state.
endReadOnly	(): void	void	Exits read-only state.
isReadOnly	(): boolean	boolean	Gets the current read-only state.
setShowParagraphMarks	(value: boolean): void	void	Sets whether paragraph marks are visible.
getShowParagraphMarks	(): boolean	boolean	Gets paragraph mark visibility.
setShowPageBreak	(value: boolean): void	void	Sets whether page break marks are visible.
getShowPageBreak	(): boolean	boolean	Gets page break mark visibility.
setShowSectionBreak	(value: boolean): void	void	Sets whether section break marks are visible.
getShowSectionBreak	(): boolean	boolean	Gets section break mark visibility.

PagePosition:

type PagePosition = {
  pageNum: number;
  pageCnt: number;
  total: number;
};

Document example:

await app.Document.exportPdf();

app.Document.setPageView("wide");
app.Document.goToPage(3);

const page = app.Document.getCurrentPagePosition();
console.log(page.pageNum, page.pageCnt, page.total);

app.Document.setPageOrientation("Portrait");
app.Document.setPageSize(21, 29.7);
await app.Document.cut();
app.Document.setShowParagraphMarks(true);
app.Document.setShowPageBreak(true);
app.Document.setShowSectionBreak(true);

Document component events:

Event Name	Payload	Description
DOCX_PAGE_POSITION_CHANGE	None	Current page position changed.
DOCX_FIRST_PART_LOADING	(isLoading: boolean)	First batch page loading state.
DOCX_END_LOADING	(count: number)	All pages finished loading.
DOCUMENT_EXPORT_READY	None	Export completed.
DOCUMENT_EDITING_ENABLED	None	The document entered editable state.
DOCUMENT_EDITING_DISABLED	None	The document exited editable state.
DOCX_ZOOM_CHANGE	None	Zoom changed.
DOCX_PART_LOADING	(pageIndex: number, ratio: number)	Chunk loading progress. ratio is in the 0 to 1 range.

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
setBold	(value?: boolean): void	void	Sets or toggles bold. If omitted, toggles based on the current selection state.
setItalic	(value?: boolean): void	void	Sets or toggles italic. If omitted, toggles based on the current selection state.
setUnderline	(lineType?: string): void	void	Sets or clears underline. The default line type is "thick".
setStrikeThrough	(value?: boolean): void	void	Sets or toggles strikethrough.
setFontSize	(value: string | number): void	void	Sets font size. Empty or non-numeric values are ignored.
setFontName	(value: string): void	void	Sets font family.
setFontColor	(value: DocxColor): void	void	Sets font color. Supports RGB or theme color objects.
getColorPalette	(): { theme: unknown[]; standard: unknown[] }	{ theme; standard }	Gets theme colors and standard colors.
setAlignment	(value: ParagraphAlignment): boolean	boolean	Sets horizontal paragraph alignment.
getAlignment	(): ParagraphAlignment | undefined	ParagraphAlignment | undefined	Gets current horizontal paragraph alignment.
setLineSpacing	(value: number): void	void	Sets line spacing multiplier. Common values include 1, 1.15, 1.5, and 2.
setBulletList	(index?: number): boolean | undefined	boolean | undefined	Sets or clears bullet list. Default index = -1.
setNumberedList	(index?: number): boolean | undefined	boolean | undefined	Sets or clears numbering. Default index = -1.

Color and alignment parameters:

type DocxColor =
  | { r: number; g: number; b: number }
  | { name: string; theme: number; tint?: number; shade?: number };

type ParagraphAlignment =
  | "Left"
  | "Centered"
  | "Right"
  | "Justified"
  | "Distributed"
  | 0
  | 1
  | 2
  | 3
  | 4;

ParagraphAlignment numeric values match the PPTX alignment enum: 0 right, 1 left, 2 center, 3 justified, 4 distributed.

Paragraph example:

app.Paragraph.setBold(true);
app.Paragraph.setItalic(false);
app.Paragraph.setUnderline("single");
app.Paragraph.setStrikeThrough(false);

app.Paragraph.setFontName("Microsoft YaHei");
app.Paragraph.setFontSize(16);
app.Paragraph.setFontColor({ r: 192, g: 0, b: 0 });

app.Paragraph.setAlignment("Centered");
app.Paragraph.setLineSpacing(1.5);
app.Paragraph.setBulletList(0);

Table

Method	Signature	Returns	Description
insertTable	(rows?: number, columns?: number): void	void	Inserts a table. Default is 3 x 4.
delete	(): void	void	Deletes the current table.
addRows	(insertLocation?: InsertLocation | number, rowCount?: number): void	void	Inserts rows at the current position. Defaults to inserting 1 row after; if the first argument is a number, it is treated as row count.
addColumns	(insertLocation?: InsertLocation | number, columnCount?: number): void	void	Inserts columns at the current position. Defaults to inserting 1 column to the right; if the first argument is a number, it is treated as column count.
deleteRows	(rowCount?: number): void	void	Deletes current rows. Defaults to 1 row.
deleteColumns	(columnCount?: number): void	void	Deletes current columns. Defaults to 1 column.
mergeCells	(): void	void	Merges the currently selected cells.
unmergeCells	(): void	void	Unmerges cells.
isInTable	(): boolean	boolean	Whether the current selection is inside a table.

type InsertLocation =
  | "Start"
  | "Before"
  | "Left"
  | "start"
  | "before"
  | "left"
  | "End"
  | "After"
  | "Right"
  | "end"
  | "after"
  | "right";

"Start", "Before", "Left", and their lowercase forms insert before or to the left. Other values use the default "End" behavior, inserting after or to the right.

Table example:

app.Table.insertTable(3, 5);

if (app.Table.isInTable()) {
  app.Table.addColumns("End", 1);
  app.Table.addRows(2);
  app.Table.mergeCells();
}

Selection

Method	Signature	Returns	Description
getSelectedText	(options?: unknown): string	string	Gets text from the current selection. Returns an empty string when there is no valid selection.
getParagraphInfo	(pageIndex?: number): ParagraphInfo	ParagraphInfo	Gets row, column, and selection ID information for the paragraph.
clearSelection	(): void	void	Clears selection highlights on the page.
hideCursor	(): void	void	Hides the cursor.
insertBreak	(type?: BreakType): void	void	Inserts a page break, section break, or column break.

type ParagraphInfo = {
  row: number;
  col: number;
  selection: {
    startPosId?: string;
    endPosId?: string;
  };
};

type BreakType =
  | "Page"
  | "SectionNext"
  | "SectionContinuous"
  | "SectionEven"
  | "SectionOdd"
  | "Column";

Selection example:

app.Selection.insertBreak("Page");
app.Selection.insertBreak("SectionNext");

const info = app.Selection.getParagraphInfo();
console.log(info.row, info.col);

Selection component events:

Event Name	Payload
SELECTION_CHANGE	DocxSelectionChange

type DocxSelectionChange = {
  bold: boolean;
  italic: boolean;
  fontName: string;
  fontSize: number | string;
  fontColor: unknown;
  underline: boolean;
  strikeout: boolean;
  paraAlignHorizontal:
    | "left"
    | "center"
    | "right"
    | "justify"
    | "distribute"
    | undefined;
  canCopy: boolean;
};

Finder

Method	Signature	Returns	Description
search	(text: string, callback?: (...args: unknown[]) => void): void	void	Starts searching for a keyword. Optional callback receives runtime-provided search arguments.
getSelectText	(): string | undefined	string | undefined	Gets the currently selected text. Only returns when selected text length is greater than 0 and less than 256.
selectNext	(): void	void	Moves to the next search result.
selectPrevious	(): void	void	Moves to the previous search result.
getSearchStatus	(): FinderStatus	FinderStatus	Gets current search status.

type FinderStatus = {
  keyword: string;
  allFounds: unknown[];
  currentIndex: number;
  totalCount: number;
  loop: boolean;
  currentSelect: unknown;
  countNum?: number;
};

Finder component events:

Event Name	Payload	Description
DOCX_OPEN_FIND_UI	None	The document requests opening the find UI.

Finder example:

const selectedWord = app.Finder.getSelectText();
app.Finder.search(selectedWord || "contract");
app.Finder.selectNext();

const status = app.Finder.getSearchStatus();
console.log(status.currentIndex, status.totalCount);

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	None

Example:

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