# XLSX API

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

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

## Components#

Component | Description
--- | ---
`Document` | Export, zoom, editing state, and loading events
`Workbook` | Worksheets, palette, number formats, and protection state
`Worksheet` | Rows, columns, freeze panes, row height, and column width
`Selection` | Current selection content, font, borders, fill, alignment, and number format
`Finder` | Search, previous/next result, and search status
`Cursor` | Current mouse/cursor target area
`UndoRedo` | Undo, redo, and availability state

## Quick Example#

    app.Document.setZoom(125);
    app.Selection.setBold(true);
    app.Selection.setFillColor({ r: 255, g: 242, b: 204 });
    await app.Worksheet.insertRows();

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

Event example:

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

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

## Document#

Method | Signature | Returns | Description
--- | --- | --- | ---
`isEditing` | `(): boolean` | `boolean` | Whether a cell is currently being edited.
`setZoom` | `(value: number, redraw?: boolean): boolean` | `boolean` | Sets zoom percentage. `redraw` defaults to `true`; returns the underlying zoom operation result.
`getZoom` | `(): number` | `number` | Gets zoom percentage.
`focusEditor` | `(): void` | `void` | Currently a no-op in the XLSX implementation.
`updateVisibleArea` | `(): void` | `void` | Redraws the visible area of the current active worksheet.
`exportDocument` | `(): Promise<void>` | `Promise<void>` | Exports the original workbook.
`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.
`startReadOnly` | `(): void` | `void` | Enters read-only state.
`endReadOnly` | `(): void` | `void` | Exits read-only state.
`isReadOnly` | `(): boolean` | `boolean` | Gets the current read-only state.

Example:

    if (!app.Document.isEditing()) {
      app.Document.setZoom(110);
    }

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

Document component events:

Event Name | Payload | Description
--- | --- | ---
`XLSX_WORKSHEET_LOADED` | None | Worksheet loaded.
`XLSX_END_LOADING` | None | Document loading completed.
`DOCUMENT_EXPORT_READY` | None | Export completed.
`DOCUMENT_EDITING_ENABLED` | None | The document entered editable state.
`DOCUMENT_EDITING_DISABLED` | None | The document exited editable state.
`XLSX_EDITING_STATUS_CHANGE` | `(status: boolean)` | Cell editing state changed.
`XLSX_ZOOM_CHANGE` | None | Zoom changed.
`XLSX_WORKSHEET_LOADING_RATIO` | `(ratio: number)` | Worksheet loading progress.
`XLSX_FIRST_PART_LOADING` | None | First batch content loaded.
`XLSX_WORKSHEET_CHANGE` | `({ sheetProtected?: boolean })` | Current worksheet changed.

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

## Workbook#

Method | Signature | Returns | Description
--- | --- | --- | ---
`addWorksheet` | `(): void` | `void` | Adds a worksheet.
`setWorksheetName` | `(name: string, index?: number): boolean \| number` | `boolean \| number` | Sets worksheet name. If `index` is omitted, the active worksheet is used. Returns success or a name-validation status code.
`deleteWorksheet` | `(index?: number): void` | `void` | Deletes a worksheet. If `index` is omitted, the active worksheet is deleted.
`getWorksheetName` | `(index?: number): string` | `string` | Gets worksheet name. If `index` is omitted, the active worksheet is read.
`getColorPalette` | `(): { theme: unknown[]; standard: unknown[] }` | `{ theme; standard }` | Gets the color palette.
`getCellNumberFormats` | `(): string[]` | `string[]` | Gets number format category list.
`getNumberFormatExample` | `(format: string, value?: unknown, lcid?: unknown): unknown` | `unknown` | Gets a number format example.
`getNumberFormatExamples` | `(formats: string[], value?: unknown, lcid?: unknown): unknown` | `unknown` | Gets number format examples in batch.
`isWorksheetProtected` | `(index?: number): boolean` | `boolean` | Checks whether a worksheet is protected. If `index` is omitted, the active worksheet is checked.

Example:

    app.Workbook.addWorksheet();
    app.Workbook.setWorksheetName("Summary");

    const name = app.Workbook.getWorksheetName();
    const protectedSheet = app.Workbook.isWorksheetProtected();

    const formats = app.Workbook.getCellNumberFormats();
    const examples = app.Workbook.getNumberFormatExamples(["0.00", "0%"], 1234.56, "en-US");

## Worksheet#

Method | Signature | Returns | Description
--- | --- | --- | ---
`isFrozenPane` | `(): boolean` | `boolean` | Whether panes are currently frozen.
`toggleFreezePanes` | `(): void` | `void` | Toggles freeze/unfreeze panes.
`setRowHeight` | `(heightPt: number): Promise<unknown>` | `Promise<unknown>` | Sets current row height. Empty values are ignored.
`insertRows` | `(): Promise<unknown>` | `Promise<unknown>` | Inserts rows.
`hideRows` | `(): Promise<unknown>` | `Promise<unknown>` | Hides rows.
`unhideRows` | `(): Promise<unknown>` | `Promise<unknown>` | Unhides rows.
`deleteRows` | `(): Promise<unknown>` | `Promise<unknown>` | Deletes rows.
`insertColumns` | `(): Promise<unknown>` | `Promise<unknown>` | Inserts columns.
`setColumnWidth` | `(nChars: number): void` | `void` | Sets current column width in character width units. Empty values are ignored.
`hideColumns` | `(): Promise<unknown>` | `Promise<unknown>` | Hides columns.
`unhideColumns` | `(): Promise<unknown>` | `Promise<unknown>` | Unhides columns.
`deleteColumns` | `(): Promise<unknown>` | `Promise<unknown>` | Deletes columns.
`getRowHeight` | `(row?: number \| null, wsIdx?: number \| null): number` | `number` | Gets row height. If omitted or `null`, the current context is used.
`getColumnWidth` | `(col?: number \| null, wsIdx?: number \| null): number` | `number` | Gets column width. If omitted or `null`, the current context is used.

Example:

    if (!app.Worksheet.isFrozenPane()) {
      app.Worksheet.toggleFreezePanes();
    }

    await app.Worksheet.setRowHeight(24);
    app.Worksheet.setColumnWidth(12);

    const rowHeight = app.Worksheet.getRowHeight();
    const colWidth = app.Worksheet.getColumnWidth();

## Selection#

Selection methods operate on the current active cell or selection.

Method | Signature | Returns | Description
--- | --- | --- | ---
`clearContents` | `(): void` | `void` | Clears content in the current selection.
`setAccountingFormat` | `(value: AccountingFormat): Promise<unknown> \| false` | `Promise<unknown> \| false` | Sets accounting format. Returns `false` for invalid format values.
`setUnderline` | `(value: string): void` | `void` | Sets underline.
`setBorder` | `(value: BorderValue): void` | `void` | Sets borders.
`setStrikeThrough` | `(value: boolean): void` | `void` | Sets strikethrough.
`setBold` | `(value: boolean): void` | `void` | Sets bold.
`setItalic` | `(value: boolean): void` | `void` | Sets italic.
`setFontSize` | `(value: string \| number): void` | `void` | Sets font size. Must satisfy `0 < value <= 409`.
`setHorizontalAlignment` | `(value: string): void` | `void` | Sets horizontal alignment.
`setVerticalAlignment` | `(value: string \| number): void` | `void` | Sets vertical alignment. Prefer string values.
`setFontColor` | `(value: XlsxColor): void` | `void` | Sets font color.
`setFillColor` | `(value: XlsxColor): void` | `void` | Sets fill color.
`setFontName` | `(value: string): void` | `void` | Sets font family.
`setCellStyle` | `(value: string): Promise<unknown>` | `Promise<unknown>` | Sets cell style.
`setPercentFormat` | `(): Promise<unknown>` | `Promise<unknown>` | Sets percent format.
`setNumberFormat` | `(value: unknown): Promise<unknown>` | `Promise<unknown>` | Sets number format.
`increaseDecimalPlaces` | `(): void` | `void` | Increases decimal places.
`decreaseDecimalPlaces` | `(): void` | `void` | Decreases decimal places.

    type AccountingFormat = "RMB" | "Dollar" | "EUR" | "GBP" | "JPY" | "none";

    type XlsxColor =
      | { r: number; g: number; b: number }
      | { theme: number; tint?: number }
      | { indexed: number }
      | { rgbHex: string };

    type BorderValue = {
      color: XlsxColor;
      position: string;
      style: string;
    };

`rgbHex` supports 6-digit `RRGGBB` or 8-digit `AARRGGBB`. The 8-digit form can carry alpha; the `{ r, g, b }` RGB object itself does not support transparency.

While cell text is being edited, `setBold`, `setItalic`, `setUnderline`, and `setStrikeThrough` toggle the current state and ignore the supplied boolean value. `setHorizontalAlignment` and `setVerticalAlignment` currently have no effect in that editing state.

Common enums:

Parameter | Common Values
--- | ---
`setUnderline(value)` | `"single"`, `"none"`
`setHorizontalAlignment(value)` | `"left"`, `"center"`, `"right"`, `"justify"`, `"distributed"`
`setVerticalAlignment(value)` | `"top"`, `"center"`, `"bottom"`, `"justify"`, `"distributed"`; runtime numeric values are accepted for compatibility
`setAccountingFormat(value)` | `"RMB"`, `"Dollar"`, `"EUR"`, `"GBP"`, `"JPY"`, `"none"`
`BorderValue.position` | `"all"`, `"none"`, `"inner"`, `"outer"`, `"left"`, `"right"`, `"top"`, `"bottom"`, `"verticalInner"`, `"horizontalInner"`, `"diagonalUp"`, `"diagonalDown"`
`BorderValue.style` | `"hair"`, `"dotted"`, `"dashed"`, `"thin"`, `"medium"`, `"thick"`, `"double"`, `"dashDot"`, `"dashDotDot"`, `"mediumDashed"`, `"mediumDashDot"`, `"mediumDashDotDot"`, `"slantDashDot"`; when clearing borders, use `position: "none"`

Example:

    app.Selection.clearContents();

    app.Selection.setFontName("Arial");
    app.Selection.setFontSize(12);
    app.Selection.setBold(true);
    await app.Selection.setAccountingFormat("RMB");
    app.Selection.setFontColor({ r: 192, g: 0, b: 0 });
    app.Selection.setFillColor({ r: 255, g: 242, b: 204 });

    app.Selection.setBorder({
      color: { r: 0, g: 0, b: 0 },
      position: "all",
      style: "thin"
    });

    await app.Selection.setNumberFormat("0.00");
    app.Selection.increaseDecimalPlaces();

Selection component events:

Event Name | Payload
--- | ---
`SELECTION_CHANGE` | `XlsxSelectionChange` or the raw event object

    type XlsxSelectionChange = {
      bold: boolean;
      italic: boolean;
      fontName: string;
      fontSize: number | string;
      fontColor: unknown;
      underline: string;
      strikeout: boolean;
      fillColor: unknown;
      alignHorizontal: string;
      alignVertical: string;
      numFormat: string;
      numFormatType: string;
      canCopy?: boolean;
      bSelectAll?: boolean;
      isText?: boolean;
    };

## Finder#

Method | Signature | Returns | Description
--- | --- | --- | ---
`search` | `(text: string, callback?: (...args: unknown[]) => void): void` | `void` | Starts searching for a keyword. Optional callback supported.
`selectFirst` | `(): void` | `void` | Moves to the first search result.
`selectNext` | `(): void` | `void` | Moves to the next search result.
`selectPrevious` | `(): void` | `void` | Moves to the previous search result.
`getSearchStatus` | `(): unknown` | `unknown` | Gets search status.

Finder component events:

Event Name | Payload | Description
--- | --- | ---
`XLSX_OPEN_FIND_UI` | None | The document requests opening the find UI.

Example:

    app.Finder.search("Q1");
    app.Finder.selectFirst();
    app.Finder.selectNext();

    console.log(app.Finder.getSearchStatus());

## Cursor#

Method | Signature | Returns | Description
--- | --- | --- | ---
`getTargetType` | `(): "" \| "columnHeader" \| "rowHeader" \| "cells" \| "navBar"` | `string` | Gets the current mouse/cursor target area.

Return values:

Value | Description
--- | ---
`""` | No stable target currently.
`"cells"` | Cell area.
`"rowHeader"` | Row header.
`"columnHeader"` | Column header.
`"navBar"` | Bottom worksheet tab area.

Example:

    const targetType = app.Cursor.getTargetType();
    if (targetType === "cells") {
      app.Selection.setBold(true);
    }

## UndoRedo#

Method | Signature | Returns | Description
--- | --- | --- | ---
`undo` | `(callback?: (value: unknown) => void): void` | `void` | Undo. Optional callback supported.
`redo` | `(callback?: (value: unknown) => void): void` | `void` | Redo. Optional callback supported.
`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.canRedo()) {
      app.UndoRedo.redo();
    }