Print functionality allows users to print spreadsheet content as physical documents or export it to PDF format for offline viewing and sharing.
Plugin Mode
Installation
pnpm add @univerjs-pro/sheets-printnpm install @univerjs-pro/sheets-printyarn add @univerjs-pro/sheets-printbun add @univerjs-pro/sheets-printUsage
import { UniverSheetsPrintPlugin } from '@univerjs-pro/sheets-print'import SheetsPrintPluginEnUS from '@univerjs-pro/sheets-print/locale/en-US'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import '@univerjs-pro/sheets-print/lib/index.css'const univer = new Univer({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( SheetsPrintPluginEnUS, ), },})univer.registerPlugin(UniverSheetsPrintPlugin)If you have a commercial license for Univer, please refer to Using License in Client for configuration.
Plugins and Configuration
interface IUniverSheetsPrintConfig { /** * Whether to force the watermark to be displayed when printing * @default false */ enforceWatermark?: boolean}Preset Mode
The print functionality is included in the @univerjs/preset-sheets-advanced preset.
Installation
The UniverSheetsAdvancedPreset preset from @univerjs/preset-sheets-advanced depends on the
UniverSheetsDrawingPreset preset at runtime. Please install @univerjs/preset-sheets-drawing first.
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancednpm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedyarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedbun add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advancedUsage
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-drawing/lib/index.css'import '@univerjs/preset-sheets-advanced/lib/index.css'const { univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( UniverPresetSheetsCoreEnUS, UniverPresetSheetsDrawingEnUS, UniverPresetSheetsAdvancedEnUS, ), }, presets: [ UniverSheetsCorePreset(), UniverSheetsDrawingPreset(), UniverSheetsAdvancedPreset(), ],})If you have a commercial license for Univer, please refer to Using License in Client for configuration.
Presets and Configuration
interface IUniverSheetsAdvancedPresetConfig { print?: Partial<IUniverSheetsPrintConfig>}interface IUniverSheetsPrintConfig { /** * Whether to force the watermark to be displayed when printing * @default false */ enforceWatermark?: boolean}Facade API
Importing
Plugin mode note
Only plugin mode requires manually importing the Facade package. Preset mode already includes the corresponding Facade package, so no extra import is needed.
import '@univerjs-pro/sheets-print/facade'Open Print Configuration Dialog
Using FWorkbook.openPrintDialog can open the print configuration dialog.
const fWorkbook = univerAPI.getActiveWorkbook()fWorkbook.openPrintDialog()Close Print Configuration Dialog
Using FWorkbook.closePrintDialog method can close the print configuration dialog.
const fWorkbook = univerAPI.getActiveWorkbook()fWorkbook.openPrintDialog()// Close the print configuration dialog after 3 secondssetTimeout(() => { fWorkbook.closePrintDialog()}, 3000)Update Print Layout Configuration
Using FWorkbook.updatePrintConfig(config: ISheetPrintLayoutConfig) method to update the print layout configuration.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const subUnitId = fWorksheet.getSheetId()// Update print layout configfWorkbook.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 printing with the updated configurationfWorkbook.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 Configuration
Using FWorkbook.updatePrintRenderConfig(config: ISheetPrintRenderConfig) method to update the print render configuration.
const fWorkbook = univerAPI.getActiveWorkbook()// Update print layout config by defaultfWorkbook.updatePrintConfig({})// Update print render configfWorkbook.updatePrintRenderConfig({gridlines: true, // show gridlineshAlign: univerAPI.Enum.PrintAlign.Middle, // horizontal align middlevAlign: univerAPI.Enum.PrintAlign.Middle, // vertical align middleheaderFooter: [ // 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 printfWorkbook.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}Using FWorkbook.print method can directly trigger the print dialog.
// Using the default configuration you can pass in an empty objectworkbook.updatePrintConfig({// ... Print layout configuration})workbook.updatePrintRenderConfig({// ... Print render configuration})workbook.print()Save Screenshot to Clipboard
Using the FWorkbook.saveScreenshotToClipboard method allows you to save the print data image to the clipboard.
Only available with a license, users without a license will face usage restrictions, and the save operation will return false.
We use the Clipboard API to save the image to the clipboard, which may fail in non-secure network environments or unsupported browsers. A successful save will return true.
const fWorkbook = univerAPI.getActiveWorkbook()const result = await fWorkbook.saveScreenshotToClipboard()Get Screenshot of Selected Range
Using the FRange.getScreenshot method allows you to get a screenshot of the selected print data.
Only available with a license, users without a license will face usage restrictions, and the save operation will return false on failure, or a base64 string of the image on success.
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:D10')fRange.getScreenshot()fRange.getScreenshot({ includeHeaders: true }) // Include row and column headersEvent Listeners
The following events are available for the print functionality:
univerAPI.Event.BeforeSheetPrintOpen event is triggered before the print configuration dialog is opened.
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintOpen, (params) => { const { workbook, worksheet } = params // Cancel open print configuration dialog operation params.cancel = true})// Remove the event listener, use `disposable.dispose()`.univerAPI.Event.SheetPrintOpen event is triggered after the print configuration dialog is opened.
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintOpen, (params) => { const { workbook, worksheet } = params})// Remove the event listener, use `disposable.dispose()`.univerAPI.Event.BeforeSheetPrintConfirm event is triggered before the print confirmation dialog is opened.
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintConfirm, (params) => { const { renderConfig, layoutConfig } = params // Cancel the print confirmation operation params.cancel = true})// Remove the event listener, use `disposable.dispose()`.univerAPI.Event.SheetPrintConfirmed event is triggered after the print confirmation dialog is opened.
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintConfirmed, (params) => { const { renderConfig, layoutConfig } = params})// Remove the event listener, use `disposable.dispose()`.univerAPI.Event.BeforeSheetPrintCanceled event is triggered before the print cancellation operation.
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintCanceled, (params) => { const { renderConfig, layoutConfig } = params // Cancel the print cancel operation params.cancel = true})// Remove the event listener, use `disposable.dispose()`.univerAPI.Event.SheetPrintCanceled event is triggered after the print cancellation operation.
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintCanceled, (params) => { const { renderConfig, layoutConfig } = params})// Remove the event listener, use `disposable.dispose()`.How is this guide?