pdfOptions 与 printOptions 详解
两阶段：先排版成 PDF，再投递打印机
await webPrintPdf.printHtml(…);同名字段对比（最容易配错的地方）
下列字段在两边名称相同，但作用阶段不同。建议成对填写且语义一致，否则容易出现「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 = …怎么配对
// pdf side…默认规则
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: 'Default printer',
scaleMode: 'shrink'
};
await webPrintPdf.printHtml(html, pdfOptions, printOptions);100×60mm 标签（自定义尺寸）
const pdfOptions = { width…A4 横向（宽表、甘特图）
const pdfOptions = { landscape…双面合同 + 预览对比缩放
// preview first…batchPrint 参数合并规则
await webPrintPdf.batchPrint(…