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));
怎么配对
场景一:办公用纸。下列名称两边枚举里都有,写同一个字符串即可: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)
| 字段 | 类型 / 默认 | 说明与技巧 |
|---|---|---|
paperFormat | string · A4 | 固定名见上方 paperFormat 专讲。与 width/height 互斥;标签/热敏用毫米宽高并省略 paperFormat。 |
width / height | string|number | 自定义纸张,单位 px/in/cm/mm。与 paperFormat 二选一。技巧:标签纸四边 margin 常设 0,避免多出空白边。 |
margin | object · 0 | 四边边距,默认 0。开 displayHeaderFooter 时务必预留 top/bottom(如 18mm),否则页眉页脚与正文重叠。 |
landscape | boolean · false | false 纵向,true 横向。须与 printOptions.landscape 同时为 true 才生效。 |
printBackground | boolean · false | 默认 false,背景色/背景图会丢失。票据、带色块表格务必设 true。 |
preferCSSPageSize | boolean · false | 为 true 时 HTML 里 @page { size: ... } 优先于 paperFormat。多页模板混排时有用;与固定 A4 混用易出意外尺寸。 |
displayHeaderFooter | boolean · false | 为 true 时启用 headerTemplate/footerTemplate。模板内用 class:date、title、url、pageNumber、totalPages。 |
headerTemplate / footerTemplate | string | HTML 片段,样式尽量内联。页眉页脚区域不计入正文 margin,需单独留空。 |
watermark | object | 文本:text, color, size, rows, cols, angle, opacity。踩坑:color 必须用 rgb(r,g,b);angle 须 ≥ 0。图片水印用 base64 字段。 |
pageNumber | object | 叠加页码,format: '{{page}}/{{totalPage}}'。踩坑:color 同样要 rgb 格式;与 headerTemplate 里的 class pageNumber 是两套机制。 |
pageRanges | Array · [] | 如 [{from:1,to:3}];空数组表示全部页。 |
printOptions 全字段(PDF → 打印机)
| 字段 | 类型 / 默认 | 说明与技巧 |
|---|---|---|
printerName | string | 与 utils.getPrinterList() 返回的 name 一致。省略则用系统默认打印机;不要写死其他机器上的中文名,应运行时查询。 |
paperFormat | string | 内置枚举 + 驱动纸名,详见 paperFormat 专讲。务必对目标打印机调用 utils.getPrinterPapers(printer),用返回的 name。 |
colorful | boolean · false | false 黑白,true 彩色。驱动不支持彩色时会降级。 |
landscape | boolean · false | false 纵向,true 横向。须与 pdfOptions.landscape 同时为 true;控制投递方向,不替代驱动纸盒旋转。 |
copies | number | 打印份数。 |
duplexMode | string · simplex | simplex 单面;duplex / duplexshort / duplexlong 双面。打印机不支持双面时会失败或降级单面。 |
scaleMode | string · shrink | noscale 原尺寸;shrink 缩小进可打区域(默认);fit 铺满。拿不准时用 extraOptions.action: "preview" 对比。 |
bin | number|string | 纸盘/进纸托盘,依驱动支持。 |
sharp | boolean · false | 热敏打印机锯齿优化开关(仅 printOptions,仅热敏打印机需要开启)。false(默认)PDF 直接送印;true 时客户端先把 PDF 光栅化并二值化成 1-bit 临时 PDF 后送印,消除热敏机把抗锯齿边缘抖成锯齿、麻点的问题。激光/喷墨/A4 办公机请保持默认关闭。须为 boolean,勿传字符串。 |
pageRanges | Array · [] | 格式同 pdfOptions。 |
sharp 热敏清晰模式(仅热敏打印机)
sharp 是专供热敏打印机的客户端打印增强,不属于 pdfOptions。Chromium 生成的 PDF 含灰阶抗锯齿边缘,热敏头只能打纯黑白,会把这些灰像素抖成锯齿、虚边或麻点。仅在热敏打印机上开启 sharp: true,客户端会在送印前把 PDF 二值化为黑白点阵。激光、喷墨等非热敏设备无需也请勿开启。
什么时候该开 sharp?
- 需要开启(仅热敏打印机):80mm/58mm 热敏小票、快递面单、标签条码等热敏纸输出;预览 PDF 清晰但热敏出纸边缘有锯齿、噪点或虚边。
- 保持关闭(默认):激光/喷墨/A4 办公机、带照片或渐变色的文档——非热敏设备不需要也不应开启 sharp。
客户端内部做了什么
- 读取业务 PDF(HTML 转 PDF 后的文件,或 URL/Base64 打印链路中的 PDF)。
- 按
pageRanges(若有)确定要处理的页码。 - 用内置 pdfjs 在隐藏窗口中把每一页渲染到 canvas。
- 对像素做二值化处理,生成 1-bit 黑白 PNG,再嵌入新的临时 mono PDF(页尺寸保持与原 PDF 一致)。
- 把临时 PDF 交给打印引擎出纸;任务结束后自动删除临时文件。
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 会覆盖批量默认值