Vue / React 项目 10 分钟接入网页静默打印

B/S 项目接到「不要弹浏览器打印框」的需求，很多团队的第一反应是搜 window.print 插件------往往白忙一场。正确路径是：前端装 npm 包，终端装本地客户端，十分钟左右能跑通第一张静默出纸。

本文给出 Vue 3 / React 接入 web-print-pdf + Web打印专家 的最短路径。

资源	链接
官网	http://webprintpdf.com/
客户端下载	http://webprintpdf.com/downloadApp/
npm 包	https://www.npmjs.com/package/web-print-pdf
GitHub	https://github.com/weixiaoyi/web-print-pdf

0. 架构一图流

复制代码

┌──────────────┐  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 分钟）

bash 复制代码

npm install web-print-pdf
# 或
yarn add web-print-pdf

3. 第三步：复制最小可运行代码（约 3 分钟）

3.1 原生 JS / Vue / React 通用

javascript 复制代码

import webPrintPdf from "web-print-pdf";

export async function silentPrint(html) {
  const pdfOptions = {
    paperFormat: "A4",
    margin: { top: "20px", bottom: "20px", left: "20px", right: "20px" },
    printBackground: true,
  };

  const printOptions = {
    // printerName: "HP-XXX",  // 可选；省略则用默认打印机
    paperFormat: "A4",
    copies: 1,
  };

  const extraOptions = {
    action: "print", // 静默打印；联调版式用 "preview"
  };

  await webPrintPdf.printHtml(html, pdfOptions, printOptions, extraOptions);
}

3.2 Vue 3 组件示例

vue 复制代码

<template>
  <button :loading="loading" @click="handlePrint">静默打印</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;
  }
};
</script>

3.3 React 示例

jsx 复制代码

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 / 19235，npm 包会探测。

4.2 打印机名（推荐动态获取）

javascript 复制代码

const list = await webPrintPdf.getPrinterList();
console.log(list); // 选 default: true 或指定 name

不要把开发机打印机名写死提交到生产。

4.3 先 preview 再 print

联调版式时：

javascript 复制代码

const extraOptions = { action: "preview" };
const res = await webPrintPdf.printHtml(html, pdfOptions, printOptions, extraOptions);
// res.printPreviewUrl 在客户端或新窗口打开

版式 OK 后再改回 action: "print"。

5. 常用 API 速查

方法	用途
`printHtml(html, ...)`	HTML 片段静默打印（最常用）
`printHtmlByUrl(url, ...)`	整页报表 URL
`printPdfByUrl(url, ...)`	已有 PDF
`batchPrint(taskList, ...)`	批量连打
`getPrinterList()`	打印机列表
`getPrinterPapers(printer)`	纸张列表

内网 URL 需登录时，在 extraOptions 传：

javascript 复制代码

{
  requestTimeout: 30,
  cookies: { JSESSIONID: "..." },
  httpHeaders: { Authorization: "Bearer ..." },
}

6. 封装建议（可选，+5 分钟）

6.1 统一 print 工具模块

javascript 复制代码

// utils/print.js
import webPrintPdf from "web-print-pdf";

const defaultPdfOptions = { paperFormat: "A4", printBackground: true };
const defaultPrintOptions = { paperFormat: "A4", copies: 1 };

export async function printReceipt(html, overrides = {}) {
  return webPrintPdf.printHtml(
    html,
    { ...defaultPdfOptions, ...overrides.pdfOptions },
    { ...defaultPrintOptions, ...overrides.printOptions },
    { action: "print", ...overrides.extraOptions }
  );
}

6.2 环境检测（UX 友好）

javascript 复制代码

export async function ensurePrintClient() {
  try {
    await webPrintPdf.getPrinterList();
    return true;
  } catch {
    window.open("http://webprintpdf.com/downloadApp/", "_blank");
    return false;
  }
}

按钮点击前先 ensurePrintClient()，可显著减少「为什么打不了」的工单。

7. 十分钟 checklist

分钟	动作
0～2	安装并启动 Web打印专家，打印测试通过
2～3	`npm install web-print-pdf`
3～6	复制 `printHtml` 示例，绑到按钮
6～8	`getPrinterList` 确认打印机
8～10	`preview` 看版式 → 改 `print` 验收

8. 小结

Vue / React 接入网页静默打印，不需要 改后端、不需要浏览器插件：

终端 Web打印专家
前端 web-print-pdf
一个 printHtml 调用

客户端内置完整 运行示例 与 CodeMirror 可编辑 Demo，可直接对照调试。遇到问题见《打印机连上了却不出纸？Web 静默打印故障排查手册》。