pdfOptions 与 printOptions 详解
两阶段：先排版成 PDF，再投递打印机
await webPrintPdf.printHtml(
html,
pdfOptions, // 第 2 参：HTML → PDF 版式
printOptions, // 第 3 参：PDF → 物理打印机
extraOptions // 第 4 参：preview/print、超时、Cookie 等
);同名字段对比（最容易配错的地方）
下列字段在两边名称相同，但作用阶段不同。建议成对填写且语义一致，否则容易出现「PDF 预览正常、出纸被裁切」或「空白边距异常」。
| 字段 | pdfOptions | printOptions | 技巧 / 踩坑 |
|---|---|---|---|
paperFormat |
固定尺寸枚举（A4、Letter…），优先于 width/height | 须为该打印机驱动支持的名称；不支持则回退默认纸 | 两边都设时请保持一致。热敏/标签纸名称各异，用 getPrinterPapers 查 print 侧可用值 |
landscape |
控制生成的 PDF 页面方向（纵向/横向） | 控制内容排版方向，不旋转物理纸盒 | 横向须两边同时设 landscape: true，并与 paperFormat 成对一致；只设 pdfOptions 或只设 printOptions 往往不生效 |
pageRanges |
生成 PDF 时裁剪页码区间 | 打印时再次裁剪页码区间 | 通常两边设相同区间；只在一侧设置可能导致预览与出纸张数不一致 |
paperFormat 专讲（同名字段）
pdfOptions.paperFormat — 排版阶段
可选值
Letter、Legal、Tabloid、Ledger、A0、A1、A2、A3、A4、A5、A6（默认 A4）。
printOptions.paperFormat — 出纸阶段
可选值
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));怎么配对
// 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('热敏打印机');
const printOptions = {
printerName: '热敏打印机',
paperFormat: papers.find(p => p.name.includes('80'))?.name ?? papers[0].name
// 一般知道具体的纸张名称时，直接填写名称即可，例如 paperFormat: '80mm Series'
};默认规则
pdfOptions 全字段（HTML → PDF）
| 字段 | 类型 / 默认 | 说明与技巧 |
|---|---|---|
paperFormat | string · A4 | |
width / height | string|number | |
margin | object · 0 | |
landscape | boolean · false | false 纵向，true 横向。须与 printOptions.landscape 同时为 true 才生效。 |
printBackground | boolean · false | |
preferCSSPageSize | boolean · false | |
displayHeaderFooter | boolean · false | |
headerTemplate / footerTemplate | string | |
watermark | object | |
pageNumber | object | |
pageRanges | Array · [] | 如 [{from:1,to:3}]；空数组表示全部页。 |
printOptions 全字段（PDF → 打印机）
| 字段 | 类型 / 默认 | 说明与技巧 |
|---|---|---|
printerName | string | |
paperFormat | string | |
colorful | boolean · false | false 黑白，true 彩色。驱动不支持彩色时会降级。 |
landscape | boolean · false | false 纵向，true 横向。须与 pdfOptions.landscape 同时为 true；控制投递方向，不替代驱动纸盒旋转。 |
copies | number | 打印份数。 |
duplexMode | string · simplex | |
scaleMode | string · shrink | |
bin | number|string | 纸盘/进纸托盘，依驱动支持。 |
pageRanges | Array · [] | 格式同 pdfOptions。 |
常见踩坑清单
实战配方（可直接套用）
A4 办公文档（带背景色）
const pdfOptions = {
paperFormat: 'A4',
margin: { top: '15mm', bottom: '15mm', left: '12mm', right: '12mm' },
printBackground: true
};
const printOptions = {
paperFormat: 'A4',
printerName: '默认打印机',
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);双面合同 + 预览对比缩放
// 先用 preview 对比 scaleMode，再改为 print
await webPrintPdf.printHtml(html,
{ paperFormat: 'A4', printBackground: true },
{ paperFormat: 'A4', duplexMode: 'duplexlong', scaleMode: 'fit' },
{ action: 'preview' }
);batchPrint 参数合并规则
await webPrintPdf.batchPrint(
[
{ type: 'printHtml', data: html1, pdfOptions: { width: '80mm', height: '200mm' } },
{ type: 'printHtml', data: html2 }
],
{ margin: { top: '2mm' } }, // 批量默认 pdfOptions
{ printerName: '热敏打印机' }, // 批量默认 printOptions
{ requestTimeout: 20 }
);
// 单条任务内的 pdfOptions / printOptions 会覆盖批量默认值