Print

Facade API	Has Paid Plan	Univer Server	Univer on Node.js	Preset
✅	✅	-	-	UniverSheetsAdvancedPreset

Univer provides high-precision printing functions, supporting print preview, print settings, and export to PDF.

This feature includes the following plugin packages:

@univerjs-pro/sheets-print Print Plugin

Presets Installation


import { createUniver, defaultTheme, LocaleType, merge } from '@univerjs/presets';
import { UniverSheetsCorePreset } from '@univerjs/presets/preset-sheets-core';
import UniverPresetSheetsCoreEnUS from '@univerjs/presets/preset-sheets-core/locales/en-US';
import { UniverSheetsAdvancedPreset } from '@univerjs/presets/preset-sheets-advanced';
import UniverPresetSheetsAdvancedEnUS from '@univerjs/presets/preset-sheets-advanced/locales/en-US';
import { UniverSheetsDrawingPreset } from '@univerjs/presets/preset-sheets-drawing'
import UniverPresetSheetsDrawingEnUS from '@univerjs/presets/preset-sheets-drawing/locales/en-US'
 
import '@univerjs/presets/lib/styles/preset-sheets-core.css'
import '@univerjs/presets/lib/styles/preset-sheets-drawing.css'
import '@univerjs/presets/lib/styles/preset-sheets-advanced.css'
 
const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: merge(
      {},
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDrawingEnUS,
      UniverPresetSheetsAdvancedEnUS,
    ),
  },
  theme: defaultTheme,
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(),
    UniverSheetsAdvancedPreset(),
  ],
});

Piecemeal Installation


npm install @univerjs-pro/sheets-print


pnpm add @univerjs-pro/sheets-print


yarn add @univerjs-pro/sheets-print


bun add @univerjs-pro/sheets-print


import { LocaleType, merge, Univer } from '@univerjs/core';
import { defaultTheme } from "@univerjs/design";
import { UniverSheetsPrintPlugin } from '@univerjs-pro/sheets-print'
import SheetsPrintPluginEnUS from '@univerjs-pro/sheets-print/locale/en-US';
 
import '@univerjs-pro/sheets-print/facade';
 
import '@univerjs-pro/sheets-print/lib/index.css';
 
const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: merge(
      SheetsPrintPluginEnUS
    ),
  },
});
 
univer.registerPlugin(UniverSheetsPrintPlugin);

Facade API

To get full defination of facade api, please refer to FacadeAPI

Open Print Configuration Dialog

FWorkbook.openPrintDialog() method can open the print configuration dialog.


const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.openPrintDialog();

Close Print Configuration Dialog

FWorkbook.closePrintDialog method can close the print configuration dialog.


const fWorkbook = univerAPI.getActiveWorkbook();
fWorkbook.openPrintDialog();
 
// Close print dialog after 3 seconds
setTimeout(() => {
  fWorkbook.closePrintDialog();
}, 3000);

Update Print Layout Config

FWorkbook.updatePrintConfig(config: ISheetPrintLayoutConfig) method updates the print layout configuration.


const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const subUnitId = fWorksheet.getSheetId();
 
// Update print layout config
fWorkbook.updatePrintConfig({
  area: univerAPI.Enum.PrintArea.CurrentSheet, // print current sheet
  subUnitIds: [subUnitId],
  paperSize: univerAPI.Enum.PrintPaperSize.A4, // A4 paper size
  scale: univerAPI.Enum.PrintScale.FitPage, // fit content to page
  freeze: [univerAPI.Enum.PrintFreeze.Row], // freeze row headers
  margin: univerAPI.Enum.PrintPaperMargin.Normal, // normal margin
  // ... other settings
});
 
// Start print
fWorkbook.print();

Here is the complete definition of `ISheetPrintLayoutConfig`:


/**
 * Configuration interface for sheet print layout settings
 */
export interface ISheetPrintLayoutConfig {
  /**
   * Specifies which area of the sheet to print (e.g., current sheet, selection)
   */
  area: PrintArea;
  /**
   * List of sub-unit IDs to print, can include specific ranges within units
   */
  subUnitIds: (string | { id: string; range: IRange })[];
  /**
   * Paper size setting (e.g., A4, Letter)
   */
  paperSize: PrintPaperSize;
  /**
   * Page orientation (Portrait or Landscape)
   */
  direction: PrintDirection;
  /**
   * Scale type for fitting content to page
   */
  scale: PrintScale;
  /**
   * Custom scale percentage when scale type is custom
   */
  customScale: number;
  /**
   * Array of freeze settings for rows and columns
   */
  freeze: PrintFreeze[];
  /**
   * Margin preset for the printed page
   */
  margin: PrintPaperMargin;
  /**
   * Custom page dimensions when using custom paper size
   */
  pageSizeCustom?: { w: number; h: number };
  /**
   * Maximum number of rows to print per page
   */
  maxRowsEachPage: number;
  /**
   * Maximum number of columns to print per page
   */
  maxColumnsEachPage: number;
}
 
/**
 * Defines the area of the spreadsheet to be printed
 */
export enum PrintArea {
  /** Print only the current active sheet */
  CurrentSheet = 'CurrentSheet',
  /** Print the entire workbook */
  workbook = 'Workbook',
  /** Print only the current selected range */
  CurrentSelection = 'CurrentSelection',
  /** Print all selected ranges across sheets */
  AllSelection = 'AllSelection',
}
 
/**
 * Defines the paper size for printing
 */
export enum PrintPaperSize {
  /** Use the letter paper size */
  Letter = 'Letter',
  /** Use the tabloid paper size */
  Tabloid = 'Tabloid',
  /** Use the legal paper size */
  Legal = 'Legal',
  /** Use the statement paper size */
  Statement = 'Statement',
  /** Use the executive paper size */
  Executive = 'Executive',
  /** Use the folio paper size */
  Folio = 'Folio',
  /** Use the A3 paper size */
  A3 = 'A3',
  /** Use the A4 paper size */
  A4 = 'A4',
  /** Use the A5 paper size */
  A5 = 'A5',
  /** Use the B4 paper size */
  B4 = 'B4',
  /** Use the B5 paper size */
  B5 = 'B5',
}
 
/**
 * Defines the direction of the printed page
 */
export enum PrintDirection {
  /** Portrait orientation */
  Portrait = 'Portrait',
  /** Landscape orientation */
  Landscape = 'Landscape',
}
 
/**
 * Defines the scale type for printing
 */
export enum PrintScale {
  /** normal scale */
  Origin = 'Origin',
  /** Fit to width */
  FitWidth = 'FitWidth',
  /** Fit to height */
  FitHeight = 'FitHeight',
  /** Fit to page */
  FitPage = 'FitPage',
  /** Custom scale */
  Custom = 'Custom',
}
 
/**
 * Defines which elements should remain frozen when printing
 */
export enum PrintFreeze {
  /** Keep row headers frozen when printing */
  Row = 'Row',
  /** Keep column headers frozen when printing */
  Column = 'Column',
}
 
/**
 * Defines the margin preset for the printed page
 */
export enum PrintPaperMargin {
  /** Use the normal margin */
  Normal = 'Normal',
  /** Use the narrow margin */
  Narrow = 'Narrow',
  /** Use the wide margin */
  Wide = 'Wide',
  /** Not set any margin */
  None = 'None',
}

Update Print Render Config

FWorkbook.updatePrintRenderConfig(config: ISheetPrintRenderConfig) method updates the print render configuration.


const fWorkbook = univerAPI.getActiveWorkbook();
 
// Update print layout config by default
fWorkbook.updatePrintConfig({});
 
// Update print render config
fWorkbook.updatePrintRenderConfig({
  gridlines: true, // show gridlines
  hAlign: univerAPI.Enum.PrintAlign.Middle, // horizontal align middle
  vAlign: univerAPI.Enum.PrintAlign.Middle, // vertical align middle
  headerFooter: [ // the array of header and footer elements to include, here is page numbers and worksheet name
    univerAPI.Enum.PrintHeaderFooter.PageSize,
    univerAPI.Enum.PrintHeaderFooter.WorksheetTitle
  ],
  // ... other settings
});
 
// Start print
fWorkbook.print();

Here is the complete definition of `ISheetPrintRenderConfig`:


/**
 * Configuration interface for sheet print rendering options
 */
export interface ISheetPrintRenderConfig {
  /**
   * Whether to show gridlines in the printed output
   */
  gridlines: boolean;
  /**
   * Horizontal alignment setting for content
   */
  hAlign: PrintAlign;
  /**
   * Vertical alignment setting for content
   */
  vAlign: PrintAlign;
  /**
   * Array of header and footer elements to include
   */
  headerFooter: PrintHeaderFooter[];
  /**
   * Detailed settings for header and footer content
   */
  headerFooterSetting: IPrintHeaderFooter;
  /**
   * Whether using custom header/footer instead of presets
   */
  isCustomHeaderFooter?: boolean;
 
  watermark?: Nullable<IWatermarkConfigWithType>;
}
 
/**
 * Defines the available alignment options for printed content
 */
export enum PrintAlign {
  /** horizontally align content to the left, vertically align content to the top */
  Start = 'Start',
  /** horizontally align content to the right, vertically align content to the bottom */
  End = 'End',
  /** horizontally align content to the center, vertically align content to the center */
  Middle = 'Middle',
}
 
/**
 * Defines the available placeholders for header and footer content
 */
export enum PrintHeaderFooter {
  /** Insert current page numbers information */
  PageSize = 'PageSize',
  /** Insert workbook name */
  WorkbookTitle = 'WorkbookTitle',
  /** Insert worksheet name */
  WorksheetTitle = 'WorksheetTitle',
  /** Insert current date */
  Date = 'Date',
  /** Insert current time */
  Time = 'Time',
}
 
/**
 * Configuration interface for header and footer content positioning
 */
export interface IPrintHeaderFooter {
  /** Content to display in the top-left section */
  topLeft: string;
  /** Content to display in the top-center section */
  topCenter: string;
  /** Content to display in the top-right section */
  topRight: string;
  /** Content to display in the bottom-left section */
  bottomLeft: string;
  /** Content to display in the bottom-center section */
  bottomCenter: string;
  /** Content to display in the bottom-right section */
  bottomRight: string;
}

Call Up Print

FWorkbook.print() method can directly call up the print dialog.


// Using the default configuration you can pass in an empty object
workbook.updatePrintConfig({
  // ... Print layout configuration
})
workbook.updatePrintRenderConfig({
  // ... Print render configuration
})
workbook.print();

Save Screenshot to Clipboard

FWorkbook.saveScreenshotToClipboard() method can save the print data image to the clipboard.

This API is only available with a license. Without a license, usage is restricted, and save operations will return false.

We use the Clipboard API to save the image to the clipboard, which may fail in an insecure network environment or in some unsupported browsers. A successful save will return true.


const fWorkbook = univerAPI.getActiveWorkbook();
const result = await fWorkbook.saveScreenshotToClipboard();
console.log(result); // true or false

Get Range Screenshot

FRange.getScreenshot() method can get the range print data image.

This API is only available with a license. Users without a license will face usage restrictions. On failure, it returns false, and on success, it returns the image’s base64 string.


const fWorkbook = univerAPI.getActiveWorkbook();
const fWorksheet = fWorkbook.getActiveSheet();
const fRange = fWorksheet.getRange('A1:D10');
console.log(fRange.getScreenshot());

Event Listening

Full event type definitions, please refer to Events .

univerAPI.Event.BeforeSheetPrintOpen event is triggered before opening the print configuration dialog.


const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintOpen, (params) => {
  const { workbook, worksheet } = params;
  console.log('params', params);
 
  // Cancel open print configuration dialog operation
  params.cancel = true;
});
 
// Remove the event listener, use `disposable.dispose()`.

univerAPI.Event.SheetPrintOpen event is triggered after opening the print configuration dialog.


const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintOpen, (params) => {
  const { workbook, worksheet } = params;
  console.log('params', params);
});
 
// Remove the event listener, use `disposable.dispose()`.

univerAPI.Event.BeforeSheetPrintConfirm event is triggered before confirming the print operation.


const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintConfirm, (params) => {
  const { renderConfig, layoutConfig } = params;
  console.log('params', params);
 
  // Cancel the print confirmation operation
  params.cancel = true;
});
 
// Remove the event listener, use `disposable.dispose()`.

univerAPI.Event.SheetPrintConfirmed event is triggered after confirming the print operation.


const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintConfirmed, (params) => {
  const { renderConfig, layoutConfig } = params;
  console.log('params', params);
});
 
// Remove the event listener, use `disposable.dispose()`.

univerAPI.Event.BeforeSheetPrintCanceled event is triggered before canceling the print operation.


const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintCanceled, (params) => {
  const { renderConfig, layoutConfig } = params;
  console.log('params', params);
 
  // Cancel the print cancel operation
  params.cancel = true;
});
 
// Remove the event listener, use `disposable.dispose()`.

univerAPI.Event.SheetPrintCanceled event is triggered after canceling the print operation.


const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintCanceled, (params) => {
  const { renderConfig, layoutConfig } = params;
  console.log('params', params);
});
 
// Remove the event listener, use `disposable.dispose()`.