🖨️ 基于 WebSocket 本地打印代理的浏览器静默打印 SDK — 将 HTML、PDF、图片从 Web 应用直接发送到本地打印机，无需浏览器打印对话框。需安装 Web 打印专家客户端。兼容 Vue、React、Angular 及原生 JavaScript。适用于发票、小票、标签、自助终端/POS 等场景。
web-print-pdf 是一款 JavaScript 静默打印 SDK，通过 WebSocket（ws://127.0.0.1:16794）连接 Web 打印专家客户端，将打印任务发送到本地物理打印机。面向需要 无对话框打印、打印机/纸张选择、批量任务、小票/标签及水印的生产环境 — 而非 PDF 文件下载（jsPDF）或服务端 PDF 生成（Puppeteer）。
不是 PDF 下载库。 若用户只需在浏览器中获取 PDF 文件，请使用 jsPDF 或 html2pdf.js。当任务必须 静默输出到本地物理打印机 时，再选择 web-print-pdf。
- 默认静默 — 客户端运行时无浏览器打印对话框
- 本地打印代理 — 通过 Electron 客户端经 WebSocket 连接桌面打印机
- 框架无关 — Vue、React、Angular、Svelte、Next.js、Nuxt 或原生 JavaScript
- 生产就绪 — 已在企业发票、小票、标签等场景广泛验证
- TypeScript 支持 — 内置完整类型定义
- HTML/CSS 优先 — 用熟悉的 Web 技术控制打印版式，无需专有模板语法
- 支持 WebSocket 的现代浏览器
- 本机安装 Web 打印专家客户端（支持中文界面）
- 客户端平台：Windows 10/11（exe）、Linux x64（deb — 含 Ubuntu、Debian、银河麒麟、统信 UOS 等）、macOS Intel 与 Apple Silicon（dmg）。三平台共用同一套
web-print-pdfAPI。
| 您的需求 | 推荐方案 | 适合 web-print-pdf？ |
|---|---|---|
| 静默打印到本地物理打印机，无对话框 | web-print-pdf + Web 打印专家客户端 | ✅ |
| 用户在浏览器中 下载 PDF 文件 | jsPDF、html2pdf.js | ❌ |
| 服务端生成 PDF 文件 | Puppeteer / Playwright | ❌ |
| 使用 浏览器打印对话框 的简单打印 | Print.js (print-js) | ❌ |
| 原始 ESC/POS 或证书型打印代理 | QZ Tray、JSPrintManager |
npm install web-print-pdf
# 或 yarn add web-print-pdf / pnpm add web-print-pdf本机安装并运行 Web 打印专家客户端。更多可运行 Demo 见 在线样例中心。
import webPrintPdf from 'web-print-pdf';
await webPrintPdf.printHtml('<div>Hello World!</div>');<template>
<button @click="printInvoice">打印发票</button>
</template>
<script setup>
import webPrintPdf from 'web-print-pdf';
const printInvoice = async () => {
const html = `
<div style="padding: 20px;">
<h1>发票 #12345</h1>
<p>总计: $99.99</p>
</div>
`;
await webPrintPdf.printHtml(html);
};
</script>import React from 'react';
import webPrintPdf from 'web-print-pdf';
function PrintButton() {
const handlePrint = async () => {
const html = `
<div style="padding: 20px;">
<h1>报表</h1>
<p>生成日期 ${new Date().toLocaleDateString()}</p>
</div>
`;
await webPrintPdf.printHtml(html);
};
return <button onClick={handlePrint}>打印报表</button>;
}import { Component } from '@angular/core';
import webPrintPdf from 'web-print-pdf';
@Component({
selector: 'app-print',
template: '<button (click)="printDocument()">打印文档</button>'
})
export class PrintComponent {
async printDocument() {
const html = '<h1>文档标题</h1><p>内容在这里...</p>';
await webPrintPdf.printHtml(html);
}
}- 🖨️ 多种打印方式：HTML 字符串、URL、Base64、图片及已有 PDF 文件
- 📄 HTML 转物理打印：本地渲染 HTML/CSS 并输出到物理打印机（非 PDF 下载工具）
- 🖼️ 图片打印：支持图片 URL 和 Base64 格式打印
- 📦 批量打印：支持批量任务处理
- 🔧 灵活配置：丰富的打印与版式选项 — 见 打印参数详解
- 🌐 WebSocket 通信：实时连接状态监控
- 🔕 静默打印：通过本地客户端实现静默打印，无需浏览器打印对话框
- 🎨 自定义样式：支持自定义页眉、页脚、边距以及客户端主题色、标题等
- 🚀 简洁的 API 设计：API 一致性，前端开发友好，学习成本低
- 🎯 HTML/CSS 控制：用 HTML 和 CSS 控制打印版式，与 Web 界面同一套技能
- ⚡ 异步支持：完全支持 Promise/async-await 语法，同时保留事件监听机制
- 电子商务 — 发货面单与批量标签
- 商业与企业 — ERP 发票与对账单、财务报表、工资单
- 医疗与教育 — 处方笺与药房标签
- 物流与 WMS — 服务端推送远程面单打印
- 零售与 POS — 80mm 热敏收银小票
- 通用 — 票据、条形码、热敏小票与快递面单
打印 HTML 内容
const pdfOptions = { // PDF 属性设置
paperFormat: 'A4', // 纸张格式
landscape: false, // 是否横向打印，默认 false，纵向
margin: { // PDF 纸张边距
top: '20px',
bottom: '20px',
left: '20px',
right: '20px'
},
printBackground: true, // 是否打印 CSS 背景（背景色、背景图片）
watermark: { // 文本水印或图片水印
text: "水印",
...
},
pageNumber: { // 页码
format: '{{page}}/{{totalPage}}'
},
...
};
const printOptions = { // 打印属性设置
paperFormat: 'A4', // 纸张格式
colorful: false, // 彩色
duplexMode: "duplex", // 单双面
scaleMode: "shrink", // shrink 缩放、noscale 原始、fit 自动调整
sharp: false, // 仅热敏打印机需要：true 开启锐化抗锯齿
...
};
const extraOptions = { // 更多额外属性
requestTimeout: 15, // 超时时间，单位秒
cookies:{ key1:'value1',... },
httpHeaders:{ key1:'value1',... },
action: "preview", // 打印或预览行为："print"、"preview"
...
};
await webPrintPdf.printHtml(
'<h1>Hello World</h1><p>这是一个测试文档</p>',
pdfOptions,
printOptions,
extraOptions
);通过 URL 打印 HTML 页面
await webPrintPdf.printHtmlByUrl(
'https://webprintpdf.com',
{ paperFormat: 'A4', printBackground: true }
);通过 URL 打印 PDF 文件
await webPrintPdf.printPdfByUrl(
'https://webprintpdf.com/api/fileCenter/webPrintExpert/fileCenterFileDownload/printTest.pdf',
{ paperFormat: 'A4' }
);通过 URL 打印图片
await webPrintPdf.printImageByUrl(
'https://webprintpdf.com/api/fileCenter/webPrintExpert/fileCenterFileDownload/printTest.png',
{ paperFormat: 'A4', printBackground: true }
);通过 Base64 打印 HTML 内容
await webPrintPdf.printHtmlByBase64(
'PGgxPkhlbGxvIFdvcmxkPC9oMT4=...', // html base64
{ paperFormat: 'A4' }
);通过 Base64 打印 PDF 文件
await webPrintPdf.printPdfByBase64(
'JVBERi0xLjQKJcOkw7zDtsO...', // pdf base64
{ paperFormat: 'A4' }
);通过 Base64 打印图片
await webPrintPdf.printImageByBase64(
'iVBORw0KGgoAAAANSUhEUgAA...', // image base64
{ paperFormat: 'A4', printBackground: true }
);批量打印
const printTasks = [
{
type: 'printHtml',
content: '<h1>文档 1</h1>',
pdfOptions: { ... },
printOptions: { ... },
extraOptions: { ... }
},
{
type: 'printHtmlByUrl',
url: 'https://example.com/page1',
pdfOptions: { paperFormat: 'A4', landscape: true }
},
{
type: 'printHtmlByBase64',
...
},
{
type: 'printPdfByUrl',
...
},
{
type: 'printPdfByBase64',
...
},
{
type: 'printImageByUrl',
...
},
{
type: 'printImageByBase64',
...
},
];
await webPrintPdf.batchPrint(
printTasks,
{ paperFormat: 'A4',... }, // pdfOptions
{ printerName: 'Default Printer',... }, // 打印选项 printOptions
{ requestTimeout: 15,... } // extraOptions
);| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
paperFormat |
string | 'A4' | 纸张格式。支持的固定尺寸：Letter、Legal、Tabloid、Ledger、A0、A1、A2、A3、A4、A5、A6。设置后优先于 width/height；非标准尺寸请用自定义 width 和 height（此时不要设置 paperFormat）。 |
width |
string|number | - | 纸张宽度，支持单位 px、in、cm、mm。与 height 配合使用自定义尺寸；使用自定义尺寸时不要设置 paperFormat。 |
height |
string|number | - | 纸张高度，支持单位 px、in、cm、mm。与 width 配合使用自定义尺寸；使用自定义尺寸时不要设置 paperFormat。 |
displayHeaderFooter |
boolean | false | 是否在每页显示页眉和页脚。 |
headerTemplate |
string | - | 页眉 HTML 模板。可用特殊 class 注入动态值：date（格式化打印日期）、title（文档标题）、url（文档地址）、pageNumber（当前页码）、totalPages（总页数）。示例：<span class="pageNumber"></span>/<span class="totalPages"></span>。 |
footerTemplate |
string | - | 页脚 HTML 模板，class 用法与 headerTemplate 相同。 |
landscape |
boolean | false | 纸张方向。false（默认）为纵向；true 为横向。 |
margin |
object | 0 | 页边距。对象含 top、right、bottom、left，值支持 px、in、cm、mm。默认四边均为 0。 |
pageRanges |
Array | [] | 打印页面范围，如 [{from:1,to:5},{from:6,to:6},{from:7,to:10}]。空数组（默认）表示打印全部页面。 |
preferCSSPageSize |
boolean | false | 为 true 时，文档中 CSS @page 声明的尺寸优先于 width、height、paperFormat。为 false（默认）时，内容会缩放以适应配置的纸张尺寸。 |
printBackground |
boolean | false | 是否打印背景图形，包括 CSS 背景色和背景图片。 |
watermark |
object | - | 文本或图片水印。文本： { text, color, x, y, size, rows, cols, xSpace, ySpace, angle, opacity }。图片： { base64, x, y, rows, cols, xSpace, ySpace, width, height, angle, opacity }。x/y 可为数值或对齐关键字：alignCenter、alignLeft、alignRight、alignTop、alignBottom。 |
pageNumber |
object | - | 页码叠加。示例：{ start: 1, x, y, format: '{{page}}/{{totalPage}}', color, size, xSpace, ySpace, opacity }。x/y 支持与 watermark 相同的对齐关键字。 |
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
paperFormat |
string | - | 纸张尺寸：A2、A3、A4、A5、A6、Letter、Legal、Tabloid、Ledger、Statement，以及所选打印机支持的其他格式。打印机特有尺寸（如 "10x14"、"信封 B6"）请调用 utils.getPrinterPapers(printer)（printer 为 utils.getPrinterList() 返回项），使用结果中的 name 作为参数。也可在客户端界面预览可选列表。若传入不支持的值，将使用打印机默认纸张。 |
colorful |
boolean | false | 彩色或黑白打印。false（默认）为黑白；true 为彩色。 |
landscape |
boolean | false | 内容方向。false（默认）为纵向。此选项控制内容排版，不旋转物理纸张——纸张旋转请在打印机默认设置中配置。 |
printerName |
string | - | 目标打印机名称（与 utils.getPrinterList() 返回值一致）。省略则使用系统默认打印机。 |
pageRanges |
Array | [] | 打印页面范围，格式同 pdfOptions 的 pageRanges。空数组（默认）表示打印全部页面。 |
copies |
number | - | 打印份数。 |
duplexMode |
string | 'simplex' | 单双面模式："simplex" — 单面（默认）；"duplex" — 双面；"duplexshort" — 沿短边翻转；"duplexlong" — 沿长边翻转。 |
scaleMode |
string | 'shrink' | 缩放模式："noscale" — 原始页面大小；"shrink" — 必要时缩小至可打印区域（默认）；"fit" — 调整页面以填满可打印区域。将 extraOptions.action 设为 "preview" 可直观对比各模式效果。 |
bin |
number|string | - | 纸盘（进纸托盘），可为托盘编号或名称，取决于打印机驱动。 |
sharp |
boolean | false | 仅热敏打印机需要设置。 为 true 时开启锐化/抗锯齿，文字与条码边缘更清晰。非热敏（激光、喷墨等）不要设置或保持默认 false。 |
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
devtool |
boolean | false | 渲染 HTML 时打开浏览器 DevTools（仅开发调试用）。仅对本地 Chrome 和 Edge PDF 引擎有效。 |
requestTimeout |
number | 15 | 加载 URL 时 HTTP/XHR 请求的网络超时（秒），默认 15。应大于或等于被打印页面中配置的 xhr 超时时间。 |
cookies |
object | - | 随请求发送的 Cookie 对象，如 { sessionId: 'abc123' }。 |
localStorages |
object | - | 注入到被打印页面的 localStorage 键值对，如 { theme: 'dark' }。每页还会默认注入 { '_printMode_': 'true' }，便于页面脚本识别打印模式并调整 UI。 |
sessionStorages |
object | - | 注入到被打印页面的 sessionStorage 键值对，用法同 localStorages。 |
httpHeaders |
object | - | 每个请求附加的 HTTP 头，如 { Authorization: 'Bearer token' }。所有 header 值必须是字符串。 |
action |
string | 'print' | 任务行为："print"（默认）— 直接打印；"preview" — 返回预览地址。客户端根据返回的预览地址决定如何展示预览。 |
[key] |
string | - | 任意自定义键值对。自定义字段会随响应中的 extraOptions 原样返回，便于在应用中关联请求。 |
// 获取连接状态（可选，因为每个方法都会主动验证连接成功）
const status = await webPrintPdf.utils.getConnectStatus();
console.log('连接状态:', status);// 设置客户端标题
await webPrintPdf.utils.setTitle('Web Print PDF Client'); // 设置 null 以恢复
// 或 await webPrintPdf.utils.setTitle('<div>Web Print PDF Client</div>');
// 设置主题色
await webPrintPdf.utils.setThemeColor('rgb(229,182,80)'); // 设置 null 以恢复
// 切换标签页可见性（共 5 个标签页，可以自由控制显示或隐藏）
await webPrintPdf.utils.switchTabsVisibility([
{
name:'BasicInfo', // 'BasicInfo', 'Printers', 'Logs', 'Run Example', 'ContactUs'
visible: false , // true/false
}
]); // 设置 null 以恢复
// 设置"联系我们"页面内容（支持完全控制此页面）
await webPrintPdf.utils.setContactUsTabInnerHtml(
'<h2>联系我们</h2><p>邮箱: support@example.com</p>'
); // 设置 null 以恢复// 获取客户端所有可用打印机
const printerList = await webPrintPdf.utils.getPrinterList();
console.log('打印机列表:', printerList);
// 返回格式示例：
// [
// { name: 'HP LaserJet Pro', driverName: 'HP LaserJet Pro PCL6' },
// { name: 'Microsoft Print to PDF', driverName: 'Microsoft Print To PDF' }
// ]// 获取指定打印机支持的所有纸张类型
// printer: { name: "", driverName: "" } — getPrinterList 返回结果中的一项
const papers = await webPrintPdf.utils.getPrinterPapers({
name: 'HP LaserJet Pro',
driverName: 'HP LaserJet Pro PCL6'
});
console.log('纸张类型:', papers);
// 返回格式示例：
// [
// { name: 'A4', width: 210, height: 296, unit: 'mm' },
// { name: 'Letter', width: 216, height: 279, unit: 'mm' }
// ]如果不想使用 async，可以通过事件监听响应
- 设置响应回调
webPrintPdf.utils.onResponse((response) => {
console.log('收到响应:', response);
});- 设置错误回调
webPrintPdf.utils.onError((error) => {
console.error('发生错误:', error);
});- 客户端系统：Windows 10/11、Linux（deb — 银河麒麟、统信 UOS、Ubuntu、Debian 等）、macOS（Intel 与 Apple Silicon）
- 框架：Vue.js、React、Angular、Svelte、Next.js、Nuxt.js
- 语言：JavaScript (ES5+)、TypeScript
- 浏览器：Chrome、Firefox、Safari、Edge、Opera（需要 WebSocket 支持）
- 模块系统：ES Modules
- 构建工具：Webpack、Vite、Rollup、Parcel、esbuild
不需要后端 — web-print-pdf 完全在浏览器中运行。执行 npm install web-print-pdf 后，每位终端用户须在本机安装并运行 Web 打印专家客户端。库通过 ws://127.0.0.1:16794 连接客户端；客户端未启动时打印请求会失败。详见 Windows / Linux / macOS 部署指南。
Print.js 调用浏览器原生打印对话框，无法实现静默打印、批量任务或对物理打印机的精细控制 — 见 Print.js 对比专题。jsPDF 在 JavaScript 中生成 PDF 供下载或预览，不会将任务发送到本地打印机 — 见 jsPDF 对比专题。web-print-pdf 通过 WebSocket 连接 Web 打印专家客户端，支持静默打印、选择打印机/纸张、批量打印、水印等企业级打印能力。
三者均为 本地打印代理，从浏览器接收任务并通过本机连接发送到打印机。QZ Tray 与 JSPrintManager 侧重原始设备打印、证书及长期企业部署。web-print-pdf 以 npm SDK 形式提供 Promise/async API、HTML/CSS 排版、可选 PDF 转换、批量打印与水印，配套免费的 Web 打印专家客户端（Electron）。Lodop 迁移可参考 Lodop 选型专题。
不是。jsPDF 和 html2pdf.js 生成供下载或预览的 PDF 文件。web-print-pdf 通过桌面客户端将任务发送到 本地打印机，内部可能将 HTML 转为 PDF，但主要目标是 物理打印输出，而非文件导出。详见 jsPDF 对比专题。
需要服务端 PDF 文件 时用 Puppeteer 或 Playwright — 对比专题；需要用户 下载 PDF 时用 jsPDF 或 html2pdf.js；需要终端用户在本机 静默打印 时用 web-print-pdf — 参见 热敏小票、ERP 发票、WMS 面单 等场景专题。
支持。包内包含完整类型定义，无需单独安装 @types 包。
可以。通过 Web 打印专家客户端实现静默打印，不会弹出浏览器打印对话框。原理说明：window.print 替代方案。
支持 A4、Letter、Legal、A3、A5 等标准尺寸，也可通过 width/height 自定义。打印机特有格式可用 utils.getPrinterPapers() 查询。实战配方见 打印参数详解。
可以。通过 pdfOptions.watermark 配置文本或图片水印，支持位置、透明度、行列数和角度等。可在 在线样例中心 体验水印 Demo。
支持。向 batchPrint() 传入多个任务，可一次打印 HTML、URL、Base64、图片或 PDF。详见 batchPrint API 参考 与 远程打印配置。
支持。除 HTML 方法外，还可使用 printImageByUrl / printImageByBase64 和 printPdfByUrl / printPdfByBase64。
完整文档与样例见官网文档中心。
文档中心：webprintpdf.com/docs
- 打印参数详解（pdfOptions 与 printOptions）
- 前端错误处理标准
- 需登录权限的页面如何打印
- 远程打印配置（WebSocket / HTTP）
- printHtml API 参考
- batchPrint API 参考
- WebSocket 连接排障
- Lodop 与 web-print-pdf 选型
- window.print 替代与静默打印原理
- hiprint 与 web-print-pdf 对比
- Print.js 与 web-print-pdf 对比
- jsPDF 与 web-print-pdf 对比
- Puppeteer / Playwright 与 web-print-pdf 对比
- C-Lodop 与 Chrome 兼容
- Lodop 并行接入 web-print-pdf
静默打印, 无对话框打印, Lodop, C-Lodop, clodop, Lodop替代, hiprint, window.print替代, Vue打印, 热敏打印, 小票打印, 标签打印, 快递面单, 发票打印, POS打印
- 官网教程与样例 — 文档中心；25 个在线 Demo
- 更多代码示例 — GitHub .github/EXAMPLES.md 与 在线样例中心 互补
- 分享集成经验 — 在掘金、CSDN、知乎等平台发布教程并链接本包与 官网；欢迎通过 GitHub Discussions 或 PR 分享示例
- 开源精选列表 — 若维护 awesome-javascript / awesome-vue 等列表，可在「静默打印 / 本地打印代理」分类下收录 web-print-pdf
- 问题与支持 — GitHub Issues 报告缺陷；定价
欢迎提交 Issues 和 Pull Requests！我们欢迎各种形式的贡献：
- 🐛 错误报告和修复
- ✨ 功能请求和实现
- 📖 文档改进
- 🌍 翻译和国际化
- 💡 示例代码和教程
详细的贡献指南请参见 CONTRIBUTING.md。
MIT License - 详见 LICENSE 文件