# Print

- Human documentation: [https://docs.univer.ai/guides/sheets/features/print](https://docs.univer.ai/guides/sheets/features/print)

- Agent Markdown: [https://docs.univer.ai/guides/sheets/features/print.md](https://docs.univer.ai/guides/sheets/features/print.md)

- Requested language: `en-US`

- Content language: `en-US`

- Documentation version: `1.0.0-rc.0`

- Source: [sheets/features/print.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/print.mdx)

---

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/en-US",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/sheets-print",
      "facade": "@univerjs-pro/sheets-print/facade",
      "locale": "@univerjs-pro/sheets-print/locale/en-US",
      "style": "@univerjs-pro/sheets-print/lib/index.css"
    }
  ],
  "license": true,
  "server": false
}
```

Print functionality allows users to print spreadsheet content as physical documents or export it to PDF format for offline viewing and sharing.

> Interactive example: [Open the playground](/playground/sheets/print)

## Preset Mode

The print functionality is included in the `@univerjs/preset-sheets-advanced` preset.

### Installation

> [!NOTE]
> The `UniverSheetsAdvancedPreset` preset from `@univerjs/preset-sheets-advanced` depends on the
> `UniverSheetsDrawingPreset` preset at runtime. Please install `@univerjs/preset-sheets-drawing` first.

#### npm

```bash
npm install @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### pnpm

```bash
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### yarn

```bash
yarn add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

#### bun

```bash
bun add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced
```

### Usage

```typescript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced' // [!code ++]
import UniverPresetSheetsAdvancedEnUS from '@univerjs/preset-sheets-advanced/locales/en-US' // [!code ++]
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing' // [!code ++]
import UniverPresetSheetsDrawingEnUS from '@univerjs/preset-sheets-drawing/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-drawing/lib/index.css' // [!code ++]
import '@univerjs/preset-sheets-advanced/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsDrawingEnUS, // [!code ++]
      UniverPresetSheetsAdvancedEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsDrawingPreset(), // [!code ++]
    UniverSheetsAdvancedPreset(), // [!code ++]
  ],
})
```

If you have a commercial license for Univer, please refer to [Using License in Client](https://docs.univer.ai/guides/license.md#in-preset-mode) for configuration.

### Presets and Configuration

```typescript
interface IUniverSheetsAdvancedPresetConfig {
  print?: Partial<IUniverSheetsPrintConfig>
}

interface IUniverSheetsPrintConfig {
  /**
   * Whether to force the watermark to be displayed when printing
   * @default false
   */
  enforceWatermark?: boolean
}
```

## Plugin Mode

### Installation

#### npm

```bash
npm install @univerjs-pro/sheets-print
```

#### pnpm

```bash
pnpm add @univerjs-pro/sheets-print
```

#### yarn

```bash
yarn add @univerjs-pro/sheets-print
```

#### bun

```bash
bun add @univerjs-pro/sheets-print
```

### Usage

```typescript
import { UniverSheetsPrintPlugin } from '@univerjs-pro/sheets-print' // [!code ++]
import SheetsPrintPluginEnUS from '@univerjs-pro/sheets-print/locale/en-US' // [!code ++]
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'

import '@univerjs-pro/sheets-print/lib/index.css' // [!code ++]

const univer = new Univer({
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: mergeLocales(
      SheetsPrintPluginEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsPrintPlugin) // [!code ++]
```

If you have a commercial license for Univer, please refer to [Using License in Client](https://docs.univer.ai/guides/license.md#in-plugin-mode) for configuration.

### Plugins and Configuration

```typescript
interface IUniverSheetsPrintConfig {
  /**
   * Whether to force the watermark to be displayed when printing
   * @default false
   */
  enforceWatermark?: boolean
}
```

## Facade API

### Importing

> [!INFO: 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.

```typescript
import '@univerjs-pro/sheets-print/facade'
```

### Open Print Configuration Dialog

Using `FWorkbook.openPrintDialog` can open the print configuration dialog.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()

fWorkbook.openPrintDialog()
```

### Close Print Configuration Dialog

Using `FWorkbook.closePrintDialog` method can close the print configuration dialog.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
fWorkbook.openPrintDialog()

// Close the print configuration dialog after 3 seconds
setTimeout(() => {
  fWorkbook.closePrintDialog()
}, 3000)
```

### Update Print Layout Configuration

Using [`FWorkbook.updatePrintConfig(config: ISheetPrintLayoutConfig)`](https://docs.univer.ai/reference/facade/workbook.md#updateprintconfig) method to update the print layout configuration.

```typescript
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 printing with the updated configuration
fWorkbook.print()
```

#### Here is the complete definition of 

`ISheetPrintLayoutConfig`

:

```typescript
/**
 * 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)`](https://docs.univer.ai/reference/facade/workbook.md#updateprintrenderconfig) method to update the print render configuration.

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

:

```typescript
/**
 * 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
}

```

### Print

Using `FWorkbook.print` method can directly trigger the print dialog.

```typescript
// 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

Using the `FWorkbook.saveScreenshotToClipboard` method allows you to save the print data image to the clipboard.

Only available with a [license](https://docs.univer.ai/guides/license.md), 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`.

```typescript
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](https://docs.univer.ai/guides/license.md), 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.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:D10')
fRange.getScreenshot()
fRange.getScreenshot({ includeHeaders: true }) // Include row and column headers
```

### Event Listeners

The following events are available for the print functionality:

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

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

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

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

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

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

```typescript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintCanceled, (params) => {
  const { renderConfig, layoutConfig } = params
})

// Remove the event listener, use `disposable.dispose()`.
```