Web SDK

打印

打印功能允许用户将表格内容打印为纸质文档或导出为 PDF 格式，便于离线查看和分享。

预览

预设模式

打印功能被包含在 @univerjs/preset-sheets-advanced 预设中。

安装

@univerjs/preset-sheets-advanced 的 UniverSheetsAdvancedPreset 预设在运行时依赖 UniverSheetsDrawingPreset 预设，请先安装 @univerjs/preset-sheets-drawing。

Shell
pnpm add @univerjs/preset-sheets-drawing @univerjs/preset-sheets-advanced

使用

TypeScript
import { UniverSheetsAdvancedPreset } from '@univerjs/preset-sheets-advanced'import UniverPresetSheetsAdvancedZhCN from '@univerjs/preset-sheets-advanced/locales/zh-CN'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { UniverSheetsDrawingPreset } from '@univerjs/preset-sheets-drawing'import UniverPresetSheetsDrawingZhCN from '@univerjs/preset-sheets-drawing/locales/zh-CN'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.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      UniverPresetSheetsCoreZhCN,      UniverPresetSheetsDrawingZhCN,       UniverPresetSheetsAdvancedZhCN,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsDrawingPreset(),     UniverSheetsAdvancedPreset(),   ],})

如果你拥有 Univer 的商业许可证，请参考在客户端使用许可证进行配置。

预设与配置

TypeScript
interface IUniverSheetsAdvancedPresetConfig {  print?: Partial<IUniverSheetsPrintConfig>}interface IUniverSheetsPrintConfig {  /**   * 是否强制打印时显示水印   * @default false   */  enforceWatermark?: boolean}

插件模式

安装

Shell
pnpm add @univerjs-pro/sheets-print

使用

TypeScript
import { UniverSheetsPrintPlugin } from '@univerjs-pro/sheets-print'import SheetsPrintPluginZhCN from '@univerjs-pro/sheets-print/locale/zh-CN'import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import '@univerjs-pro/sheets-print/lib/index.css'const univer = new Univer({  locale: LocaleType.ZH_CN,  locales: {    [LocaleType.ZH_CN]: mergeLocales(      SheetsPrintPluginZhCN,     ),  },})univer.registerPlugin(UniverSheetsPrintPlugin)

如果你拥有 Univer 的商业许可证，请参考在客户端使用许可证进行配置。

插件与配置

TypeScript
interface IUniverSheetsPrintConfig {  /**   * 是否强制打印时显示水印   * @default false   */  enforceWatermark?: boolean}

引入

TypeScript
import '@univerjs-pro/sheets-print/facade'

打开打印配置对话框

使用 FWorkbook.openPrintDialog 可以打开打印配置对话框。

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

关闭打印配置对话框

使用 FWorkbook.closePrintDialog 方法可以关闭打印配置对话框。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()fWorkbook.openPrintDialog()// 3 秒后关闭打印配置对话框setTimeout(() => {  fWorkbook.closePrintDialog()}, 3000)

更新打印布局配置

使用 FWorkbook.updatePrintConfig(config: ISheetPrintLayoutConfig) 方法更新打印布局配置。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const subUnitId = fWorksheet.getSheetId()// 更新打印布局配置fWorkbook.updatePrintConfig({  area: univerAPI.Enum.PrintArea.CurrentSheet, // 打印当前工作表  subUnitIds: [subUnitId],  paperSize: univerAPI.Enum.PrintPaperSize.A4, // A4 纸张大小  scale: univerAPI.Enum.PrintScale.FitPage, // 使内容适应页面  freeze: [univerAPI.Enum.PrintFreeze.Row], // 冻结行标题  margin: univerAPI.Enum.PrintPaperMargin.Normal, // 正常边距  // ... 其他设置})// 开始打印fWorkbook.print()
以下是 ISheetPrintLayoutConfig 的完整定义：
TypeScript
/** * 打印布局设置的配置接口 */export interface ISheetPrintLayoutConfig {  /**   * 指定要打印的工作表区域（例如，当前工作表，选区）   */  area: PrintArea  /**   * 要打印的工作簿的工作表 ID 集合，或者包含工作表 ID 和范围的对象集合   */  subUnitIds: (string | { id: string, range: IRange })[]  /**   * 打印纸张大小设置（例如，A4，信纸）   */  paperSize: PrintPaperSize  /**   * 打印页面方向（纵向或横向）   */  direction: PrintDirection  /**   * 打印缩放类型   */  scale: PrintScale  /**   * 自定义缩放百分比   */  customScale: number  /**   * 冻结行和列的设置数组   */  freeze: PrintFreeze[]  /**   * 打印页面的边距预设   */  margin: PrintPaperMargin  /**   * 使用自定义纸张尺寸时的自定义页面尺寸   */  pageSizeCustom?: { w: number, h: number }  /**   * 每页打印的最大行数   */  maxRowsEachPage: number  /**   * 每页打印的最大列数   */  maxColumnsEachPage: number}/\*\*- 定义要打印的电子表格区域_/export enum PrintArea {/\*\* 只打印当前活动工作表 _/CurrentSheet = 'CurrentSheet',/** 打印整个工作簿 \*/workbook = 'Workbook',/** 只打印当前选定的范围 _/CurrentSelection = 'CurrentSelection',/\*\* 打印所有选定的范围 _/AllSelection = 'AllSelection',}/\*\*- 定义打印纸张大小_/export enum PrintPaperSize {/\*\* 使用信纸大小 _/Letter = 'Letter',/** 使用小报纸大小 \*/Tabloid = 'Tabloid',/** 使用法律纸张大小 _/Legal = 'Legal',/\*\* 使用报表纸张大小 _/Statement = 'Statement',/** 使用行政公文纸张大小 \*/Executive = 'Executive',/** 使用对折纸张大小 _/Folio = 'Folio',/\*\* 使用A3纸张大小 _/A3 = 'A3',/** 使用A4纸张大小 \*/A4 = 'A4',/** 使用A5纸张大小 _/A5 = 'A5',/\*\* 使用B4纸张大小 _/B4 = 'B4',/\*_ 使用B5纸张大小 _/B5 = 'B5',}/\*\*- 定义打印页面的方向_/export enum PrintDirection {/\*\* 纵向方向 _/Portrait = 'Portrait',/\*_ 横向方向 _/Landscape = 'Landscape',}/\*\*- 定义打印的缩放类型_/export enum PrintScale {/\*\* 正常缩放 _/Origin = 'Origin',/** 适合宽度 \*/FitWidth = 'FitWidth',/** 适合高度 _/FitHeight = 'FitHeight',/\*\* 适合页面大小 _/FitPage = 'FitPage',/\*_ 自定义缩放 _/Custom = 'Custom',}/\*\*- 定义打印时应保持冻结的元素_/export enum PrintFreeze {/\*\* 打印时保持行标题冻结 _/Row = 'Row',/\*_ 打印时保持列标题冻结 _/Column = 'Column',}/\*\*- 定义打印页面的边距预设_/export enum PrintPaperMargin {/\*\* 使用正常边距 _/Normal = 'Normal',/** 使用窄边距 \*/Narrow = 'Narrow',/** 使用宽边距 _/Wide = 'Wide',/\*\* 没有边距 _/None = 'None',}

更新打印渲染配置

使用 FWorkbook.updatePrintRenderConfig(config: ISheetPrintRenderConfig) 方法更新打印渲染配置。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()// 更新默认打印布局配置fWorkbook.updatePrintConfig({})// 更新打印渲染配置fWorkbook.updatePrintRenderConfig({gridlines: true, // 显示网格线hAlign: univerAPI.Enum.PrintAlign.Middle, // 水平居中对齐vAlign: univerAPI.Enum.PrintAlign.Middle, // 垂直居中对齐headerFooter: [ // 要包含的页眉和页脚元素数组，这里是页码和工作表名称  univerAPI.Enum.PrintHeaderFooter.PageSize,  univerAPI.Enum.PrintHeaderFooter.WorksheetTitle,],// ... 其他设置})// 开始打印fWorkbook.print()
以下是 ISheetPrintRenderConfig 的完整定义：
TypeScript
/** * 打印渲染选项的配置接口 */export interface ISheetPrintRenderConfig {  /**   * 是否在打印输出中显示网格线   */  gridlines: boolean  /**   * 水平对齐设置   */  hAlign: PrintAlign  /**   * 垂直对齐设置   */  vAlign: PrintAlign  /**   * 包含的页眉和页脚元素数组   */  headerFooter: PrintHeaderFooter[]  /**   * 页眉和页脚的详细设置   */  headerFooterSetting: IPrintHeaderFooter  /**   * 是否使用自定义页眉和页脚而不是预设   */  isCustomHeaderFooter?: boolean  watermark?: Nullable<IWatermarkConfigWithType>}/\*\*- 定义打印内容的可用对齐选项_/export enum PrintAlign {/\*\* 水平方向左对齐，垂直方向顶部对齐 _/Start = 'Start',/** 水平方向右对齐，垂直方向底部对齐 \*/End = 'End',/** 水平方向居中对齐，垂直方向居中对齐 \*/Middle = 'Middle',}/\*\*- 定义页眉和页脚内容的可用占位符_/export enum PrintHeaderFooter {/\*\* 插入当前页码信息 _/PageSize = 'PageSize',/** 插入工作簿名称 \*/WorkbookTitle = 'WorkbookTitle',/** 插入工作表名称 _/WorksheetTitle = 'WorksheetTitle',/\*\* 插入当前日期 _/Date = 'Date',/\*_ 插入当前时间 _/Time = 'Time',}/\*\*- 页眉和页脚内容定位的配置接口_/export interface IPrintHeaderFooter {/\*\* 左上角显示的内容 _/topLeft: string/** 顶部中心显示的内容 \*/topCenter: string/** 右上角显示的内容 _/topRight: string/\*\* 左下角显示的内容 _/bottomLeft: string/** 底部中心显示的内容 \*/bottomCenter: string/** 右下角显示的内容 \*/bottomRight: string}

调起打印

使用 FWorkbook.print 方法可以直接调起打印。

TypeScript
// 使用默认配置可以传入空对象workbook.updatePrintConfig({// ... 打印布局配置})workbook.updatePrintRenderConfig({// ... 打印渲染配置})workbook.print()

保存截图至剪贴板

使用 FWorkbook.saveScreenshotToClipboard 方法可以保存打印数据图片到剪切板。

该 API 仅在拥有 许可证 的情况下可用，未持有许可证时将受到使用限制，保存操作将返回 false。

我们使用 Clipboard API 保存图片到剪贴板，在非安全网络环境或某些不支持的浏览器可能会保存失败。保存成功会返回 true。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const result = await fWorkbook.saveScreenshotToClipboard()

获取选区截图

使用 FRange.getScreenshot 方法可以获取选区打印数据图片。

该 API 仅在持有 许可证 时可用，未持证用户将受到使用限制，保存失败时返回 false，成功时返回图片的 base64 字符串。

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getActiveSheet()const fRange = fWorksheet.getRange('A1:D10')fRange.getScreenshot()fRange.getScreenshot({ includeHeaders: true }) // 包含行列标题

事件监听

完整事件类型定义，请查看 Events。

univerAPI.Event.BeforeSheetPrintOpen 事件在打开打印配置对话框之前触发。

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintOpen, (params) => {  const { workbook, worksheet } = params  // 取消打开打印配置对话框操作  params.cancel = true})// 移除事件监听器，使用 `disposable.dispose()`

univerAPI.Event.SheetPrintOpen 事件在打开打印配置对话框之后触发。

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintOpen, (params) => {  const { workbook, worksheet } = params})// 移除事件监听器，使用 `disposable.dispose()`

univerAPI.Event.BeforeSheetPrintConfirm 事件在确认打印之前触发。

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintConfirm, (params) => {  const { renderConfig, layoutConfig } = params  // 取消打印确认操作  params.cancel = true})// 移除事件监听器，使用 `disposable.dispose()`

univerAPI.Event.SheetPrintConfirmed 事件在确认打印之后触发。

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintConfirmed, (params) => {  const { renderConfig, layoutConfig } = params})// 移除事件监听器，使用 `disposable.dispose()`

univerAPI.Event.BeforeSheetPrintCanceled 事件在取消打印之前触发。

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetPrintCanceled, (params) => {  const { renderConfig, layoutConfig } = params  // 取消打印取消操作  params.cancel = true})// 移除事件监听器，使用 `disposable.dispose()`

univerAPI.Event.SheetPrintCanceled 事件在取消打印之后触发。

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.SheetPrintCanceled, (params) => {  const { renderConfig, layoutConfig } = params})// 移除事件监听器，使用 `disposable.dispose()`

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.