B/S 项目接到「不要弹浏览器打印框」的需求很多团队的第一反应是搜window.print插件——往往白忙一场。正确路径是前端装 npm 包终端装本地客户端十分钟左右能跑通第一张静默出纸。本文给出Vue 3 / React接入web-print-pdfWeb打印专家的最短路径。资源链接官网http://webprintpdf.com/客户端下载http://webprintpdf.com/downloadApp/npm 包https://www.npmjs.com/package/web-print-pdfGitHubhttps://github.com/weixiaoyi/web-print-pdf0. 架构一图流┌──────────────┐ WebSocket ┌─────────────────┐ 系统打印栈 ┌──────────┐ │ Vue / React │ ──────────► │ Web打印专家 │ ──────────► │ 打印机 │ │ web-print-pdf│ 127.0.0.1 │ HTML→PDF→出纸 │ │ │ └──────────────┘ └─────────────────┘ └──────────┘浏览器只负责业务 调 API本机客户端必须安装、常驻运行无需为打印单独部署 Java / Node 打印服务1. 第一步终端安装客户端约 2 分钟打开 http://webprintpdf.com/downloadApp/下载对应系统版本Windows / macOS / 统信 UOS / 银河麒麟等安装并启动Web打印专家在客户端「打印机」页执行打印测试确认能出纸客户端未运行时前端所有打印 API 都会连接失败。2. 第二步项目安装 npm 包约 1 分钟npminstallweb-print-pdf# 或yarnaddweb-print-pdf3. 第三步复制最小可运行代码约 3 分钟3.1 原生 JS / Vue / React 通用importwebPrintPdffromweb-print-pdf;exportasyncfunctionsilentPrint(html){constpdfOptions{paperFormat:A4,margin:{top:20px,bottom:20px,left:20px,right:20px},printBackground:true,};constprintOptions{// printerName: HP-XXX, // 可选省略则用默认打印机paperFormat:A4,copies:1,};constextraOptions{action:print,// 静默打印联调版式用 preview};awaitwebPrintPdf.printHtml(html,pdfOptions,printOptions,extraOptions);}3.2 Vue 3 组件示例template button :loadingloading clickhandlePrint静默打印/button /template script setup import { ref } from vue; import webPrintPdf from web-print-pdf; const loading ref(false); const handlePrint async () { loading.value true; try { await webPrintPdf.printHtml( document.getElementById(print-area).innerHTML, { paperFormat: A4, printBackground: true }, { paperFormat: A4, copies: 1 }, { action: print } ); } catch (e) { console.error(e); alert(打印失败请确认 Web打印专家 已启动); } finally { loading.value false; } }; /script3.3 React 示例import { useState } from react; import webPrintPdf from web-print-pdf; export function PrintButton({ html }) { const [loading, setLoading] useState(false); const handlePrint async () { setLoading(true); try { await webPrintPdf.printHtml( html, { paperFormat: A4, printBackground: true }, { paperFormat: A4 }, { action: print } ); } catch (e) { alert(打印失败 (e?.message || e)); } finally { setLoading(false); } }; return ( button disabled{loading} onClick{handlePrint} {loading ? 打印中… : 静默打印} /button ); }4. 第四步联调三项检查约 4 分钟4.1 客户端是否在跑浏览器控制台不应出现 WebSocket 连127.0.0.1:16794或备选端口失败。默认端口被占用时客户端会自动换16805 / 19235npm 包会探测。4.2 打印机名推荐动态获取constlistawaitwebPrintPdf.getPrinterList();console.log(list);// 选 default: true 或指定 name不要把开发机打印机名写死提交到生产。4.3 先 preview 再 print联调版式时constextraOptions{action:preview};constresawaitwebPrintPdf.printHtml(html,pdfOptions,printOptions,extraOptions);// res.printPreviewUrl 在客户端或新窗口打开版式 OK 后再改回action: print。5. 常用 API 速查方法用途printHtml(html, …)HTML 片段静默打印最常用printHtmlByUrl(url, …)整页报表 URLprintPdfByUrl(url, …)已有 PDFbatchPrint(taskList, …)批量连打getPrinterList()打印机列表getPrinterPapers(printer)纸张列表内网 URL 需登录时在extraOptions传{requestTimeout:30,cookies:{JSESSIONID:...},httpHeaders:{Authorization:Bearer ...},}6. 封装建议可选5 分钟6.1 统一 print 工具模块// utils/print.jsimportwebPrintPdffromweb-print-pdf;constdefaultPdfOptions{paperFormat:A4,printBackground:true};constdefaultPrintOptions{paperFormat:A4,copies:1};exportasyncfunctionprintReceipt(html,overrides{}){returnwebPrintPdf.printHtml(html,{...defaultPdfOptions,...overrides.pdfOptions},{...defaultPrintOptions,...overrides.printOptions},{action:print,...overrides.extraOptions});}6.2 环境检测UX 友好exportasyncfunctionensurePrintClient(){try{awaitwebPrintPdf.getPrinterList();returntrue;}catch{window.open(http://webprintpdf.com/downloadApp/,_blank);returnfalse;}}按钮点击前先ensurePrintClient()可显著减少「为什么打不了」的工单。7. 十分钟 checklist分钟动作02安装并启动 Web打印专家打印测试通过23npm install web-print-pdf36复制printHtml示例绑到按钮68getPrinterList确认打印机810preview看版式 → 改print验收8. 小结Vue / React 接入网页静默打印不需要改后端、不需要浏览器插件终端Web打印专家前端web-print-pdf一个printHtml调用客户端内置完整运行示例与 CodeMirror 可编辑 Demo可直接对照调试。遇到问题见《打印机连上了却不出纸Web 静默打印故障排查手册》。