pdfOptions 与 printOptions 详解

调用 printHtml 等方法时,第 2 参 pdfOptions 决定 HTML 如何排版成 PDF,第 3 参 printOptions 决定 PDF 如何投递到物理打印机。两者有同名字段但作用阶段不同——对照配置能避免大量「预览正常、出纸裁切」类问题。

两阶段:先排版成 PDF,再投递打印机

完整链路:HTML 渲染 → PDF 文件 → 系统打印队列。pdfOptions 作用于前两步的版式;printOptions 只作用于最后投递阶段。

await webPrintPdf.printHtml(
  html,
  pdfOptions,    // 第 2 参:HTML → PDF 版式
  printOptions,  // 第 3 参:PDF → 物理打印机
  extraOptions   // 第 4 参:preview/print、超时、Cookie 等
);
extraOptions(第 4 参)不属于版式:如 action: "preview" 只生成 PDF 不出纸;requestTimeout 影响 URL 加载。调试版式时建议先用 preview 看 PDF,再改 printOptions 出纸。

同名字段对比(最容易配错的地方)

下列字段在两边名称相同,但作用阶段不同。建议成对填写且语义一致,否则容易出现「PDF 预览正常、出纸被裁切」或「空白边距异常」。

字段 pdfOptions printOptions 技巧 / 踩坑
paperFormat 内置 12 种国际标准/北美常用名(见下方专章);设后优先于 width/height 两类取值:① 内置 10 种通用名;② getPrinterPapers 返回的 name(须与该台打印机匹配,不可自拟)。不认识则回退默认纸 办公纸两边通常都应写同名枚举(A4/Letter 等)。热敏/标签:pdf 用 width/height,print 用 getPrinterPapers 匹配尺寸 — paperFormat 专讲
landscape 控制生成的 PDF 页面方向(纵向/横向) 控制内容排版方向,不旋转物理纸盒 横向须两边同时设 landscape: true,并与 paperFormat 成对一致;只设 pdfOptions 或只设 printOptions 往往不生效
pageRanges 生成 PDF 时裁剪页码区间 打印时再次裁剪页码区间 通常两边设相同区间;只在一侧设置可能导致预览与出纸张数不一致

paperFormat 专讲(同名字段)

paperFormat 在 pdf 与 print 里同名、各管一阶段:pdf 决定 HTML 排成多大的页面,print 决定打印机用哪张纸。通常两边都应显式填写(不写则走默认规则),且不会互相继承。先看清各自能填什么,再按下文两种场景配对。

pdfOptions.paperFormat — 排版阶段

可选值

Letter、Legal、Tabloid、Ledger、A0、A1、A2、A3、A4、A5、A6(默认 A4)。

改用 width + height(px / in / cm / mm),与 paperFormat 互斥。80mm 小票、100×60mm 标签等走这条路。

printOptions.paperFormat — 出纸阶段

可选值

内置:A2、A3、A4、A5、A6、Letter、Legal、Tabloid、Ledger、Statement(默认打印机的缺省纸张)。表中没有的纸(热敏、标签等)见下文场景二,用 getPrinterPapers 查该打印机的 name 填入,不可自拟。

const printers = await webPrintPdf.utils.getPrinterList();
const target = printers.find(p => p.isDefault) || printers[0];
const papers = await webPrintPdf.utils.getPrinterPapers(target);
// papers[].name → printOptions.paperFormat
console.log(papers.map(p => p.name));

怎么配对

pdfOptions 与 printOptions 通常都必须填写(不写则走默认规则,见下文「默认规则」)。漏写任一侧在非标纸、多纸盒环境下易出现裁切、留白或按错误尺寸排版。

场景一:办公用纸。下列名称两边枚举里都有,写同一个字符串即可:A2、A3、A4、A5、A6、Letter、Legal、Tabloid、Ledger。例:pdfOptions.paperFormat: 'A4',printOptions.paperFormat: 'A4'(北美常用 Letter 同理)。切勿 pdf 写 A4、print 写 Letter——物理尺寸不同会裁切。

场景二:小票、标签等非标纸。pdf 用 width + height(如 80mm),不设 pdfOptions.paperFormat。print 侧通常也应写 paperFormat:对目标打印机调 getPrinterPapers,选物理尺寸与 pdf 一致(或最接近)的那一项 name(如 80mm Series);两边字符串可以不同。热敏小票若出纸边缘锯齿,在 printOptions 加 sharp: true(仅热敏打印机)。可先 action: 'preview' 核对再打印。

// pdf 侧:80mm 小票,不设 paperFormat
const pdfOptions = { width: '80mm', height: '200mm', margin: { top: '0', bottom: '0', left: '0', right: '0' } };

// print 侧:非标纸通常应指定 paperFormat — 从驱动列表里选物理尺寸匹配的一项
const papers = await webPrintPdf.utils.getPrinterPapers('Thermal printer');
const printOptions = {
  printerName: 'Thermal printer',
  paperFormat: papers.find(p => p.name.includes('80'))?.name ?? papers[0].name,
  sharp: true  // 热敏打印机:开启 sharp 抗锯齿(仅热敏机需要)
  // 一般知道具体的纸张名称时,直接填写名称即可,例如 paperFormat: '80mm Series'
};

其他注意:pdf 独有 A0、A1,print 侧无同名内置项,用 getPrinterPapers 选最接近的纸;print 独有 Statement,pdf 侧勿写,改用 Letter 或 width/height。换打印机后请重新查纸名。

默认规则

代码里未填写 paperFormat 时,SDK 按下列规则处理:
  • pdfOptions.paperFormat:未填写,且未设置 width、height → 默认按 A4 排版。
  • printOptions.paperFormat:未填写 → 默认按当前打印机的默认纸张打印。若在客户端打印机列表页为某台打印机设置了首选纸张,则 print 侧未填写 paperFormat 时,使用该打印机所设的首选纸张。

pdfOptions 全字段(HTML → PDF)

字段类型 / 默认说明与技巧
paperFormatstring · A4固定名见上方 paperFormat 专讲。与 width/height 互斥;标签/热敏用毫米宽高并省略 paperFormat。
width / heightstring|number自定义纸张,单位 px/in/cm/mm。与 paperFormat 二选一。技巧:标签纸四边 margin 常设 0,避免多出空白边。
marginobject · 0四边边距,默认 0。开 displayHeaderFooter 时务必预留 top/bottom(如 18mm),否则页眉页脚与正文重叠。
landscapeboolean · falsefalse 纵向,true 横向。须与 printOptions.landscape 同时为 true 才生效。
printBackgroundboolean · false默认 false,背景色/背景图会丢失。票据、带色块表格务必设 true。
preferCSSPageSizeboolean · false为 true 时 HTML 里 @page { size: ... } 优先于 paperFormat。多页模板混排时有用;与固定 A4 混用易出意外尺寸。
displayHeaderFooterboolean · false为 true 时启用 headerTemplate/footerTemplate。模板内用 class:date、title、url、pageNumber、totalPages。
headerTemplate / footerTemplatestringHTML 片段,样式尽量内联。页眉页脚区域不计入正文 margin,需单独留空。
watermarkobject文本:text, color, size, rows, cols, angle, opacity。踩坑:color 必须用 rgb(r,g,b);angle 须 ≥ 0。图片水印用 base64 字段。
pageNumberobject叠加页码,format: '{{page}}/{{totalPage}}'。踩坑:color 同样要 rgb 格式;与 headerTemplate 里的 class pageNumber 是两套机制。
pageRangesArray · []如 [{from:1,to:3}];空数组表示全部页。

printOptions 全字段(PDF → 打印机)

字段类型 / 默认说明与技巧
printerNamestring与 utils.getPrinterList() 返回的 name 一致。省略则用系统默认打印机;不要写死其他机器上的中文名,应运行时查询。
paperFormatstring内置枚举 + 驱动纸名,详见 paperFormat 专讲。务必对目标打印机调用 utils.getPrinterPapers(printer),用返回的 name。
colorfulboolean · falsefalse 黑白,true 彩色。驱动不支持彩色时会降级。
landscapeboolean · falsefalse 纵向,true 横向。须与 pdfOptions.landscape 同时为 true;控制投递方向,不替代驱动纸盒旋转。
copiesnumber打印份数。
duplexModestring · simplexsimplex 单面;duplex / duplexshort / duplexlong 双面。打印机不支持双面时会失败或降级单面。
scaleModestring · shrinknoscale 原尺寸;shrink 缩小进可打区域(默认);fit 铺满。拿不准时用 extraOptions.action: "preview" 对比。
binnumber|string纸盘/进纸托盘,依驱动支持。
sharpboolean · false热敏打印机锯齿优化开关(仅 printOptions,仅热敏打印机需要开启)。false(默认)PDF 直接送印;true 时客户端先把 PDF 光栅化并二值化成 1-bit 临时 PDF 后送印,消除热敏机把抗锯齿边缘抖成锯齿、麻点的问题。激光/喷墨/A4 办公机请保持默认关闭。须为 boolean,勿传字符串。
pageRangesArray · []格式同 pdfOptions。

sharp 热敏清晰模式(仅热敏打印机)

sharp 是专供热敏打印机的客户端打印增强,不属于 pdfOptions。Chromium 生成的 PDF 含灰阶抗锯齿边缘,热敏头只能打纯黑白,会把这些灰像素抖成锯齿、虚边或麻点。仅在热敏打印机上开启 sharp: true,客户端会在送印前把 PDF 二值化为黑白点阵。激光、喷墨等非热敏设备无需也请勿开启。

什么时候该开 sharp?

  • 需要开启(仅热敏打印机):80mm/58mm 热敏小票、快递面单、标签条码等热敏纸输出;预览 PDF 清晰但热敏出纸边缘有锯齿、噪点或虚边。
  • 保持关闭(默认):激光/喷墨/A4 办公机、带照片或渐变色的文档——非热敏设备不需要也不应开启 sharp。

客户端内部做了什么

  1. 读取业务 PDF(HTML 转 PDF 后的文件,或 URL/Base64 打印链路中的 PDF)。
  2. 按 pageRanges(若有)确定要处理的页码。
  3. 用内置 pdfjs 在隐藏窗口中把每一页渲染到 canvas。
  4. 对像素做二值化处理,生成 1-bit 黑白 PNG,再嵌入新的临时 mono PDF(页尺寸保持与原 PDF 一致)。
  5. 把临时 PDF 交给打印引擎出纸;任务结束后自动删除临时文件。
不会改变你在 printOptions 里设置的 scaleMode、colorful、duplexMode 等——sharp 只替换送印的 PDF 内容。mono 化完成后,pageRanges 不再重复传给打印引擎(页已在光栅化阶段裁好)。

如何使用

确认目标打印机为热敏打印机后,在 printOptions 中设置 sharp: true(boolean)。其余参数(打印机名称、纸张、缩放等)按平时配置即可,无需额外字段。

使用建议

  • 仅在热敏打印机上开启 sharp: true,实打一联对比关闭时的锯齿/虚边效果。
  • 若仍不理想,可配合 extraOptions.action: "preview" 先看 PDF,再排查 pdf 侧边距、纸宽是否与热敏纸匹配。
  • pdf 侧仍建议热敏用 width/height + margin: 0,与 paperFormat 专讲 一致。

联调与排障

开启 sharp 后单次打印会比直打略慢(需渲染与二值化)。客户端会在本地 pdfs 目录保留一份 last_sharp_output.pdf 便于核对 mono 结果。若报错 sharpRaster: pdfjs viewer not ready,请确认客户端版本较新并重试;仍失败可先 sharp: false 排除链路问题,再升级客户端。

常见踩坑清单

  • paperFormat 与 width/height 同时设置 — paperFormat 优先,自定义尺寸失效。
  • pdf 与 print 的 paperFormat 不一致 — PDF 是 A4、打印机选 Letter 时易裁切或留白。更详细的配对说明见 paperFormat 专讲。
  • watermark / pageNumber 的 color 用了 #hex 或命名色 — 须写 rgb(102,102,102) 等形式。
  • 横向只设了一边 landscape — pdfOptions 与 printOptions 须同时设 landscape: true;只设一侧可能预览正常、出纸仍纵向或裁切。
  • 热敏/标签纸未 margin:0 — 默认边距会让 80mm 小票两侧被缩进。
  • printBackground: false — 表头底色、斑马纹表格打印成白纸黑字。
  • displayHeaderFooter 未加大 margin — 页眉页脚压住正文第一行。
  • batchPrint 以为批量默认会覆盖单条 — 实际是单条任务内的选项覆盖批量默认值,不是反过来。
  • 热敏锯齿却只调 scaleMode — 热敏机的锯齿/虚边来自抗锯齿灰阶,应开 printOptions.sharp: true(仅热敏打印机);shrink/fit 只改缩放。激光/喷墨/A4 误开 sharp 会丢失灰度与照片细节。

实战配方(可直接套用)

A4 办公文档(带背景色)

const pdfOptions = {
  paperFormat: 'A4',
  margin: { top: '15mm', bottom: '15mm', left: '12mm', right: '12mm' },
  printBackground: true
};
const printOptions = {
  paperFormat: 'A4',
  printerName: 'Default printer',
  scaleMode: 'shrink'
};
await webPrintPdf.printHtml(html, pdfOptions, printOptions);

100×60mm 标签(自定义尺寸)

const pdfOptions = {
  width: '100mm',
  height: '60mm',
  margin: { top: '0', bottom: '0', left: '0', right: '0' }
  // 不要同时设置 paperFormat
};
const printOptions = {
  printerName: '标签打印机',
  paperFormat: '100x60' // 名称以 getPrinterPapers 返回为准
};
await webPrintPdf.printHtml(labelHtml, pdfOptions, printOptions);

A4 横向(宽表、甘特图)

const pdfOptions = {
  paperFormat: 'A4',
  landscape: true,
  margin: { top: '10mm', bottom: '10mm', left: '8mm', right: '8mm' },
  printBackground: true
};
const printOptions = {
  paperFormat: 'A4',
  landscape: true   // pdfOptions 与 printOptions 须同时为 true
};
await webPrintPdf.printHtml(html, pdfOptions, printOptions);

80mm 热敏小票(热敏机开启 sharp 抗锯齿)

const pdfOptions = {
  width: '80mm',
  height: '200mm',
  margin: { top: '0', bottom: '0', left: '0', right: '0' },
  printBackground: true
};
const printOptions = {
  printerName: 'Thermal printer',
  paperFormat: '80mm Series',
  scaleMode: 'shrink',
  sharp: true  // 热敏打印机:抗锯齿优化
};
await webPrintPdf.printHtml(receiptHtml, pdfOptions, printOptions);

双面合同 + 预览对比缩放

// 先用 preview 对比 scaleMode,再改为 print
await webPrintPdf.printHtml(html,
  { paperFormat: 'A4', printBackground: true },
  { paperFormat: 'A4', duplexMode: 'duplexlong', scaleMode: 'fit' },
  { action: 'preview' }
);

batchPrint 参数合并规则

batchPrint(printTaskList, pdfOptions, printOptions, extraOptions) 后三个参数为批量默认值。每个任务对象可自带 pdfOptions / printOptions,任务级覆盖批量级。

await webPrintPdf.batchPrint(
  [
    { type: 'printHtml', data: html1, pdfOptions: { width: '80mm', height: '200mm' } },
    { type: 'printHtml', data: html2 }
  ],
  { margin: { top: '2mm' } },           // 批量默认 pdfOptions
  { printerName: 'Thermal printer', sharp: true },  // 热敏机批量小票:sharp 抗锯齿
  { requestTimeout: 20 }
);
// 单条任务内的 pdfOptions / printOptions 会覆盖批量默认值
免费下载客户端 打开在线样例