[特殊字符] 开源好物：web-print-pdf，让 Web 打印像调用接口一样简单！

引言：那些年我们踩过的打印坑

在 Web 应用开发中，打印功能一直是个让人头疼的问题。你是否也遇到过这些场景：

· 电商后台需要批量打印发货单，每点一次打印，浏览器就弹一次窗口，员工得守在电脑前不断点击"确认打印"；

· 企业 ERP 系统要输出上百页的财务报表，结果样式错乱、表格分页断裂；

· 连锁门店需要远程打印小票，却被告知"Web 应用没法直接指定远程打印机"......

这些问题的根源在于浏览器为了安全限制了 Web 应用对打印硬件的直接控制。而今天要介绍的 web-print-pdf，正是为解决这些专业打印需求而生的解决方案。

官网：http://webprintpdf.com

什么是 web-print-pdf？

web-print-pdf 是一个基于 Playwright 内核的跨平台 Web 打印解决方案，以 npm 包形式提供。它的核心理念是：让 Web 前端像调用本地打印一样，轻松实现静默打印、远程打印、PDF 生成等企业级功能。

你不需要改造现有系统，不需要让用户安装额外的浏览器插件，只需要几行代码，就能让 Web 应用拥有桌面软件般的打印控制能力。

传统方案 vs web-print-pdf

方案类型问题

浏览器原生 window.print() 必然弹出打印对话框，用户必须手动点击；样式在不同浏览器差异巨大；无法精确控制打印机、纸张规格、边距等参数

Lodop 类控件需要客户端安装与授权，浏览器兼容适配麻烦，部署相对复杂

纯前端 PDF 库功能有限，样式控制困难，无法满足企业级批量打印需求

web-print-pdf 的核心优势：

✅ 简单：API 极简，常见打印需求一步到位

✅ 可靠：通过本地服务与无头内核协作，规避浏览器安全限制与差异

✅ 可控：纸张大小、方向、边距、份数、目标打印机、队列、并发都可配置

✅ 可移植：前端 npm 生态集成方便，后端、桌面端、混合架构都能无缝接入

✅ 零安装部署：无需插件、无需控件注册表操作，直接引入即可

5 分钟快速上手

① 安装

bash 复制代码

npm i web-print-pdf

确保运行时已部署本地打印服务（项目提供 Electron 打包与一键安装能力），前端仅调用 API 即可。

② 打印 PDF

javascript 复制代码

import { printPdfByUrl } from 'web-print-pdf';

async function quickPrint() {
  await printPdfByUrl({
    url: 'https://example.com/order.pdf',
    printer: 'HP-LaserJet',
    copies: 1,
    duplex: false,
    paper: 'A4',
    silent: true,      // 静默打印，无弹窗
  });
}

③ 打印 HTML

javascript 复制代码

import { printHtmlByUrl, printHtmlByBase64 } from 'web-print-pdf';

// 远程 URL
await printHtmlByUrl({
  url: 'https://example.com/preview.html',
  silent: true
});

// Base64 字符串（适合前端动态生成的 DOM + 样式）
await printHtmlByBase64({
  base64: btoa('<html>...</html>'),
  silent: true
});

④ 打印图片

javascript 复制代码

import { printImageByUrl } from 'web-print-pdf';

await printImageByUrl({
  url: 'https://example.com/ticket.png',
  silent: true
});

以上代码示例来源于官方文档及相关实践文章。

核心 API 一览

📌 下文方法来自官方 API 介绍及社区相关文章。

基础打印方法

API 功能描述

printHtml(content, pdfOptions, printOptions) 打印 HTML 字符串，支持 HTML 片段和完整页面

printHtmlByUrl({ url }) 打印在线 HTML 地址，支持设置 cookies、headers、超时

printHtmlByBase64({ base64 }) 打印 Base64 格式的 HTML

printPdfByUrl({ url }) 打印在线 PDF 地址，快速下载打印

printPdfByBase64({ base64 }) 打印 Base64 格式的 PDF

printImageByUrl({ url }) 打印在线图片，支持批量打印

printImageByBase64({ base64 }) 打印 Base64 格式的图片

batchPrint(tasks) 批量打印 API，支持高并发场景

丰富打印配置

javascript 复制代码

const pdfOptions = {
  paperFormat: 'A4',           // 纸张格式：A0-A6、Letter、Legal 等
  margin: { top: '20px', bottom: '20px', left: '20px', right: '20px' },
  landscape: false,            // 横向/纵向
  printBackground: true,       // 打印背景
  watermark: {                 // 水印功能
    text: "机密文件",
    color: 'rgb(255,0,0)',
    opacity: 0.3
  },
  pageNumber: {                // 页码设置
    format: '第{{page}}页/共{{totalPage}}页',
    y: 'alignBottom'
  },
  pageRanges: [{ from: 1, to: 5 }]  // 页面范围
};

const printOptions = {
  printerName: 'HP LaserJet Pro',  // 指定打印机
  copies: 2,                       // 打印份数
  duplexMode: 'duplex',            // 双面打印模式
  colorful: true                   // 彩色/黑白
};

以上代码参考了相关技术文章中的配置示例。

高级特性

静默打印 ------ 真正的无感体验

传统的 window.print() 必然会弹出系统打印对话框，用户必须手动点击"打印"才能继续。而在 web-print-pdf 中，只需一个参数 silent: true，就能实现全程无弹窗打印。

javascript 复制代码

await printHtml({
  content: document.getElementById('receipt').innerHTML,
  silent: true,           // 无弹窗，无预览
  printer: 'Receipt_Printer',
  copies: 2
});

精确控制打印机和纸张

你可以从系统中获取已安装的打印机列表，并动态指定目标打印机，支持 A4、A5、80mm 热敏纸、自定义尺寸等，完全满足电商面单、医疗标签、财务凭证等不同场景。

高质量 PDF 生成与预览

不是截图式的 PDF，而是真正可复制、可搜索的矢量 PDF，并且支持生成预览链接，用户可以先确认预览效果再打印，所见即所得。

批量打印 + 队列管理

内置轻量级打印队列，支持并发控制和延时排队，高并发场景下稳定可控。

javascript 复制代码

import { createPrintQueue } from 'web-print-pdf';

const queue = createPrintQueue({
  concurrency: 2,          // 同时最多2个打印任务
  delay: 300,              // 每个任务间隔300ms
  onProgress: (done, total) => {
    console.log(`已打印: ${done}/${total}`);
  }
});

orders.forEach(order => {
  queue.add(() => printHtml({ content: generateOrderHtml(order), silent: true }));
});

await queue.start();

以下方法参考了相关技术社区文章中展示的队列管理实现。

典型应用场景

行业应用场景

电商/仓配批量面单、拣货单、出库单静默打印；支持队列与并发控制，防止卡顿

连锁零售小票、价签、标签快速打印，指定门店默认打印机自动落盘

医院/政务表单、回执、凭证批量打印；纸张与边距严格可控，满足合规要求

制造/物流工艺卡/条码标签打印；支持图片、PDF 混合任务一并下发

与其他方案的对比

对比项 web-print-pdf Lodop 浏览器原生 print hiprint

需要安装插件 ❌ ✅ ❌ ❌（需引入脚本）

静默打印 ✅ ✅ ❌ ❌

指定打印机 ✅ ✅ ❌ ❌

批量打印 ✅ ✅ ❌ ✅

队列并发控制 ✅ 部分支持 ❌ ❌

学习成本低中中较高

Vue/React 友好 ✅ 一般 N/A ✅

对比分析参考了多篇技术文章的对比内容。

最佳实践建议

· 模板与内容分离：在前端或服务端产出 HTML/PDF，打印层只负责传递与落盘，系统职责更清晰

· 队列化与幂等：开启任务队列与重试，保证高峰期不丢单、不重复

· 配置校验：实际可用参数会因驱动与机型差异有所不同，建议先通过打印机列表与纸型查询接口进行校验

结语

前端打印从来都不是一件简单的事，但有了 web-print-pdf，确实能省下大量调试时间。如果你正在做报表打印、PDF 合同生成、批量单据打印等需求，真心推荐试一下。

最后附上官网和 npm 地址：

· 🌐 官网：http://webprintpdf.com

· 📦 npm：web-print-pdf

· 👨‍💻 开发者：10,000+ 开发者使用，99.9% 稳定性保障

希望这个库，能帮你少加班，多睡觉。💤

本文相关代码示例及配置项参考自官方文档和技术社区的文章，实际使用时请以最新版 npm 包的 API 为准。