Electron 中 PrintToPDFMargins 对象详解：用 webContents.printToPDF() 精确控制 PDF 页边距

Electron 中 PrintToPDFMargins 对象详解用 webContents.printToPDF() 精确控制 PDF 页边距【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electronPrintToPDFMargins是 ElectronwebContents.printToPDF()选项中的边距配置对象用于以英寸为单位指定生成 PDF 的上、下、左、右页边距。本文以该结构文档为主体结合 Electron 仓库中的选项解析源码与测试用例完整讲清它的字段定义、默认值、取值约束以及与pageSize的联动校验规则帮助你在主进程中可靠地生成边距可控的 PDF 文件。PrintToPDFMargins 对象定义PrintToPDFMargins对象共包含 4 个可选字段全部为number类型单位为英寸inches。完整定义见 print-to-pdf-margins.md字段类型必填说明默认值topnumber可选上边距单位英寸1cm约 0.4 英寸bottomnumber可选下边距单位英寸1cm约 0.4 英寸leftnumber可选左边距单位英寸1cm约 0.4 英寸rightnumber可选右边距单位英寸1cm约 0.4 英寸四个字段相互独立可以只设置其中任意一个。未显式提供的边距会落到默认值 0.4 英寸即文档中所说的约 1cm。该对象作为PrintToPDFOptions的margins字段被消费完整选项定义见 print-to-pdf-options.md入口 API 为contents.printToPDF(options)见 web-contents.md 中的#### contents.printToPDF(options)小节。在 webContents.printToPDF() 中使用printToPDF在主进程调用返回一个包含 PDF 数据的Buffer。边距通常与pageSize配合使用const { BrowserWindow } require(electron); async function generatePDF() { const win new BrowserWindow({ show: false }); await win.loadFile(main.html); // 生成 A4 纵向 PDF四边各 0.5 英寸边距 const data await win.webContents.printToPDF({ pageSize: A4, margins: { top: 0.5, // 英寸非 cm bottom: 0.5, left: 0.5, right: 0.5 } }); require(fs).writeFileSync(output.pdf, data); }使用要点单位是英寸。文档明确写为 in inches如果你习惯用厘米计算请先自行换算1cm ≈ 0.3937 英寸。部分覆盖margins: { top: 0 }表示仅上边距为 0其余三边仍取默认 0.4 英寸要完全无边距需四边都显式设为 0。pageSize的缺省值是Letter8.5 x 11 英寸支持的纸型字符串还包括A0A6、Legal、Tabloid、Ledger或自定义{ width, height }对象单位同样是英寸。注意区分webContents.print()的边距选项采用marginType: custom等不同结构与printToPDF的PrintToPDFMargins不通用。源码级实现类型检查、默认值与 pageSize 联动校验printToPDF的选项翻译逻辑集中在主进程的 print-to-pdf.ts该模块被webContents.printToPDF与webFrameMain.printToPDF共用。边距的处理分三步1. 对象类型检查// lib/browser/print-to-pdf.ts const margins checkType(options.margins ?? {}, object, margins);margins允许缺省按空对象处理但必须是对象若传入字符串等非对象值如margins: terrible会抛出TypeError。2. 默认值填充四个边距统一通过checkType做数值类型检查未设置时回退到 0.4 英寸然后映射为内部设置项// lib/browser/print-to-pdf.ts marginTop: checkType(margins.top ?? 0.4, number, margins.top), marginBottom: checkType(margins.bottom ?? 0.4, number, margins.bottom), marginLeft: checkType(margins.left ?? 0.4, number, margins.left), marginRight: checkType(margins.right ?? 0.4, number, margins.right),这与文档中 Defaults to 1cm (~0.4 inches) 的默认值描述一一对应。3. 与 pageSize 的约束校验边距不能大于纸张物理尺寸。源码先将pageSize解析为英寸尺寸纸型表paperFormats中letter为 8.5 x 11a4为 8.27 x 11.7再逐边比较// lib/browser/print-to-pdf.ts const { top, bottom, left, right } margins; const validHeight [top, bottom].every((u) u undefined || u pageSize.paperHeight); const validWidth [left, right].every((u) u undefined || u pageSize.paperWidth); if (!validHeight || !validWidth) { throw new Error(margins must be less than or equal to pageSize); }规则要点垂直方向top、bottom各自不得超过纸高水平方向left、right各自不得超过纸宽这里是单边比较不要求top bottom之和小于纸高未设置的边undefined直接跳过校验因为稍后会用默认值 0.4 英寸填充而常见纸型的默认边距都在物理尺寸之内校验失败时 Promise 以margins must be less than or equal to pageSize错误拒绝。4. 并发作业排队同一 frame tree 内的并发 PDF 打印任务在渲染进程中会互相冲突源码用printToPDFQueues按顶层 frame 的frameTreeNodeId为键的 Map将同一 frame tree 的作业串行化其他webContents的作业仍可并行。这意味着在循环中批量调用printToPDF时任务会按提交顺序逐个完成而不是交错执行。5. 通往原生层校验通过后组装好的printSettings含marginTop等 4 个边距字段与paperWidth/paperHeight被传入内部绑定方法_printToPDF。从 electron_api_web_contents.cc 可见PrintToPDF原生实现注册在_printToPDF方法上SetMethod(_printToPDF, WebContents::PrintToPDF)最终交给 Chromium 的 PDF 打印管线若打印特性被禁用target._printToPDF不存在会抛出Printing feature is disabled。测试用例佐证的行为边界仓库测试 api-web-contents-spec.ts 中的printToPDF用例对上述行为有直接验证类型错误一律拒绝用例rejects on incorrectly typed parameters逐项验证了margins: terrible等错误取值会让printToPDF的 Promise 被拒绝——注释说明这些错误若不做类型检查会在 Chromium 层直接硬崩溃见该文件约 L4443-L4466超过纸面尺寸被拒绝用例rejects when margins exceed physical page size在Letter8.5 x 11 英寸纸型下传入top: 100, bottom: 100断言 Promise 以margins must be less than or equal to pageSize拒绝见该文件约 L4468-L4482。这两组用例与print-to-pdf.ts中的校验逻辑互为印证可视为PrintToPDFMargins的权威行为边界。小结PrintToPDFMargins的top/bottom/left/right均为可选number单位英寸缺省 0.4 英寸约 1cm类型必须为对象/数值非法取值会被主进程选项层直接拒绝避免底层崩溃每条边距独立校验不得超过pageSize对应的纸高/纸宽越界时得到margins must be less than or equal to pageSize错误完整链路为webContents.printToPDF(options)→ print-to-pdf.ts 选项翻译与校验 → 原生WebContents::PrintToPDFelectron_api_web_contents.cc。【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考