printHtml API 参考与最佳实践

printHtml(html, pdfOptions, printOptions, extraOptions) 是 web-print-pdf 的主入口:将 HTML 字符串经本地客户端渲染为 PDF 并投递打印机。本文汇总四参分工、典型集成模式、踩坑与立项评估,面向前端负责人与架构师。

方法签名

printHtml(
  html: string,
  pdfOptions?: PdfOptions,
  printOptions?: PrintOptions,
  extraOptions?: ExtraOptions
): Promise<PrintResult>

参数说明

参数作用详见
html完整 HTML 字符串demos/full-html
pdfOptions排版成 PDF(纸宽、边距、背景)打印参数
printOptions投递打印机(名称、份数、纸盒)打印参数
extraOptionspreview、timeout 等行为打印参数

代码示例

import webPrintPdf from 'web-print-pdf';

const ok = await webPrintPdf.getConnectStatus();
if (!ok) throw new Error('请先启动打印客户端');

await webPrintPdf.printHtml(
  reportHtml,
  { paperFormat: 'A4', printBackground: true, margin: { top: '10mm', bottom: '10mm' } },
  { printerName: '财务室激光', copies: 1, duplex: 'longEdge' }
);

典型用法模式

模式用法
DOM 提取Vue/React ref 取 innerHTML → printHtml
后端 HTML 字符串API 返回完整 HTML 文档
仅预览extraOptions.action: "preview"
鉴权 URL改用 printHtmlByUrl + extraOptions

何时使用

  • 页面已有 HTML/DOM 报表
  • 需静默、指定打印机
  • Vue/React/Angular 事件里触发
  • 不适合:仅下载 PDF 文件(可用 preview)

常见踩坑

  • pdfOptions 与 printOptions 同名参数需成对一致(纸宽/纸盒)
  • 未连客户端直接调 → 先 getConnectStatus
  • SSR/Node 中 import 调用 → 仅浏览器事件内执行
  • 宽表裁切 → CSS page-break + preview 核对

技术负责人选型要点

  • 评估日打印量与是否必须静默/指定机——是则采购客户端授权
  • 与 Lodop/Print.js 并行 PoC:选 1 张代表性报表
  • 验收:preview 与物理样张一致、错误提示统一

延伸阅读

常见问题

必须先连接客户端吗?

是。未连接会抛错;可用 getConnectStatus 预检,见 error-handling。

pdf 与 print 同名参数怎么配?

成对填写且语义一致,尤其 paperFormat/width/height。

只预览不出纸?

extraOptions.action = "preview"。

SSR 环境能调用吗?

仅浏览器事件/client 组件;Node SSR 中不要 import 后直接调。

和 printHtmlByUrl 区别?

ByUrl 由客户端抓 URL;printHtml 直接传 HTML 字符串。

各平台客户端部署

同一套 web-print-pdf 前端代码可在 Windows、macOS、Linux/信创混合环境运行;请按终端操作系统安装对应客户端。

免费下载客户端 查看 npm 包 开发文档