Skip to content

DOCX API ​

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

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

Components ​

ComponentDescription
DocumentExport, zoom, page view, page navigation, page setup, copy/cut/paste, paragraph marks, page break display, and section break display
ParagraphFont, text style, paragraph alignment, line spacing, bullets, and numbering
TableTable insertion, deletion, row/column operations, merge, and unmerge
SelectionSelection, cursor, break insertion, and selection change events
FinderSearch, previous/next result, and search status
UndoRedoUndo, redo, and availability state

Quick Example ​

ts
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:

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

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

Document ​

MethodSignatureReturnsDescription
exportDocument(): Promise<void>Promise<void>Exports the original document.
exportPdf(printOptions?: unknown): Promise<void>Promise<void>Exports PDF with print options.
setZoom(value: number): voidvoidSets zoom percentage. Common values include 80, 100, and 120.
getZoom(): numbernumberGets the current zoom percentage.
focusEditor(): voidvoidMoves focus back to the editor area.
updateVisibleArea(): voidvoidRecalculates the visible area.
setPageView(mode: "single" | "multi" | "wide"): voidvoidSwitches between single-page, multi-page, and page-width views.
goToPage(pageNum: number): voidvoidGoes 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"): voidvoidSets portrait or landscape orientation. Only exact "Portrait" and "Landscape" values are supported.
setPageSize(width: number, height: number): voidvoidSets page width and height in centimeters. width and height must be finite positive numbers.
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(): voidvoidEnters read-only state.
endReadOnly(): voidvoidExits read-only state.
isReadOnly(): booleanbooleanGets the current read-only state.
setShowParagraphMarks(value: boolean): voidvoidSets whether paragraph marks are visible.
getShowParagraphMarks(): booleanbooleanGets paragraph mark visibility.
setShowPageBreak(value: boolean): voidvoidSets whether page break marks are visible.
getShowPageBreak(): booleanbooleanGets page break mark visibility.
setShowSectionBreak(value: boolean): voidvoidSets whether section break marks are visible.
getShowSectionBreak(): booleanbooleanGets section break mark visibility.

PagePosition:

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

Document example:

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

Page setup parameter notes:

  • setPageOrientation(...) does not accept empty strings, custom strings, or aliases. Passing unsupported values is undefined behavior.
  • setPageSize(...) does not normalize 0, negative values, empty arguments, or extremely small page sizes. Validate values before calling this API.

Document component events:

Event NamePayloadDescription
DOCX_PAGE_POSITION_CHANGENoneCurrent 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_READYNoneExport completed.
DOCUMENT_EDITING_ENABLEDNoneThe document entered editable state.
DOCUMENT_EDITING_DISABLEDNoneThe document exited editable state.
DOCX_ZOOM_CHANGENoneZoom changed.
DOCX_PART_LOADING(pageIndex: number, ratio: number)Chunk loading progress. ratio is usually 0 to 1.

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 ​

MethodSignatureReturnsDescription
setBold(value?: boolean): voidvoidSets or toggles bold. If omitted, toggles based on the current selection state.
setItalic(value?: boolean): voidvoidSets or toggles italic. If omitted, toggles based on the current selection state.
setUnderline(lineType?: string): voidvoidSets or clears underline. The default line type is "thick".
setStrikeThrough(value?: boolean): voidvoidSets or toggles strikethrough.
setFontSize(value: string | number): voidvoidSets font size. Empty or non-numeric values are ignored.
setFontName(value: string): voidvoidSets font family. The API currently does not validate whether the font is installed or present in the font list.
setFontColor(value: DocxColor): voidvoidSets font color. Supports RGB or theme color objects. Theme colors must come from getColorPalette() results.
getColorPalette(): { theme: unknown[]; standard: unknown[] }{ theme; standard }Gets theme colors and standard colors.
setAlignment(value: ParagraphAlignment): booleanbooleanSets horizontal paragraph alignment.
getAlignment(): ParagraphAlignment | undefinedParagraphAlignment | undefinedGets current horizontal paragraph alignment.
setLineSpacing(value: number): voidvoidSets line spacing multiplier. Common values include 1, 1.15, 1.5, and 2.
setBulletList(index?: number): boolean | undefinedboolean | undefinedSets or clears bullet list. Default index = -1.
setNumberedList(index?: number): boolean | undefinedboolean | undefinedSets or clears numbering. Default index = -1.

Color and alignment parameters:

ts
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.

Theme color calls must include both name and theme. Passing only { theme, tint } cannot identify the theme color name and is not a supported parameter shape.

Paragraph example:

ts
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 ​

MethodSignatureReturnsDescription
insertTable(rows?: number, columns?: number): voidvoidInserts a table. Default is 3 x 4.
delete(): voidvoidDeletes the current table.
addRows(insertLocation?: InsertLocation | number, rowCount?: number): voidvoidInserts 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): voidvoidInserts 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): voidvoidDeletes current rows. Defaults to 1 row.
deleteColumns(columnCount?: number): voidvoidDeletes current columns. Defaults to 1 column.
mergeCells(): voidvoidMerges the currently selected cells.
unmergeCells(): voidvoidUnmerges cells.
isInTable(): booleanbooleanWhether the current selection is inside a table.
ts
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:

ts
app.Table.insertTable(3, 5);

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

Selection ​

MethodSignatureReturnsDescription
getSelectedText(options?: unknown): stringstringGets text from the current selection. Returns an empty string when there is no valid selection.
getParagraphInfo(pageIndex?: number): ParagraphInfoParagraphInfoGets row, column, and selection ID information for the paragraph.
clearSelection(): voidvoidClears selection highlights on the page.
hideCursor(): voidvoidHides the cursor.
insertBreak(type?: BreakType): voidvoidInserts a page break, section break, or column break. Only the BreakType enum below is supported.
ts
type ParagraphInfo = {
  row: number;
  col: number;
  selection: {
    startPosId?: string;
    endPosId?: string;
  };
};

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

insertBreak(...) parameter notes:

  • "SectionNext", "SectionContinuous", "SectionEven", and "SectionOdd" insert next-page, continuous, even-page, and odd-page section breaks.
  • Aliases such as "SectionNextPage", "SectionEvenPage", "SectionOddPage", and "Line" are not supported. Soft line breaks are currently outside this API's scope.
  • Omitting the parameter inserts a page break. Fallback behavior for unsupported values is not a public contract, so pass only the documented enum values.

Selection example:

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

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

Selection component events:

Event NamePayload
SELECTION_CHANGEDocxSelectionChange
ts
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 ​

MethodSignatureReturnsDescription
search(text: string, callback?: (...args: unknown[]) => void): voidvoidStarts searching for a keyword. The optional callback receives runtime-provided search arguments.
getSelectText(): string | undefinedstring | undefinedGets the currently selected text. Only returns when selected text length is greater than 0 and less than 256.
selectNext(): voidvoidMoves to the next search result.
selectPrevious(): voidvoidMoves to the previous search result.
selectByIndex(index: number): unknown | null | undefinedunknown | null | undefinedSelects a search result by ordinal index. index starts from 1; out-of-range values return null.
getSearchStatus(): FinderStatusFinderStatusGets current search status.
ts
type FinderStatus = {
  keyword: string;
  allFounds: unknown[];
  currentIndex: number;
  totalCount: number;
  loop: boolean;
  currentSelect: unknown;
  countNum?: number;
};

Finder component events:

Event NamePayloadDescription
DOCX_OPEN_FIND_UINoneThe document requests opening the find UI.

DOCX_OPEN_FIND_UI means the editor requested that the find panel be opened. It is not emitted for every Finder.search(...) call; use getSearchStatus() for search result state.

Finder example:

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

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

UndoRedo ​

MethodSignatureReturnsDescription
undo(): voidvoidUndo.
redo(): voidvoidRedo.
canUndo(): booleanbooleanWhether undo is available.
canRedo(): booleanbooleanWhether redo is available.

UndoRedo component events:

Event NamePayload
UNDO_REDO_STATE_CHANGENone

Example:

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