Next.js 静默打印集成指南

在 Next.js 14/15(App Router 或 Pages Router)中,打印逻辑必须在浏览器端执行:通过客户端组件调用 web-print-pdf 的 printHtml,由本机客户端完成 HTML→PDF→静默出纸。架构与 React 专题、Vue 专题 相同。

准备工作

  • 终端安装并启动 Web打印专家客户端(Windows / macOS / Linux 均可)
  • 项目根目录执行 npm install web-print-pdf
  • App Router 项目:打印组件文件顶部加 "use client";Pages Router 可直接在页面组件中 import(勿在 Server Component 中调用 printHtml)

App Router 示例(推荐)

新建客户端组件 SilentPrintButton.tsx,在按钮点击时传入打印区域 HTML:

'use client';

import { useState } from 'react';
import webPrintPdf from 'web-print-pdf';

export function SilentPrintButton({ html }: { html: string }) {
  const [loading, setLoading] = useState(false);
  return (
    <button
      disabled={loading}
      onClick={async () => {
        setLoading(true);
        try {
          await webPrintPdf.printHtml(html, { paperFormat: 'A4' }, { printerName: 'Default printer' });
        } finally {
          setLoading(false);
        }
      }}
    >
      {loading ? 'Printing…' : 'Silent print'}
    </button>
  );
}

在 Server Component 页面中引入该客户端组件即可;不要在 layout.tsx / page.tsx 的服务端部分直接 import web-print-pdf。

Pages Router 示例

在 pages/**/*.tsx 中与普通 React 项目相同,可直接 import webPrintPdf from "web-print-pdf" 并在事件里调用 printHtml。动态路由、getServerSideProps 页面同样只在浏览器事件里触发打印。

实践建议

  • Next.js 生产构建后打印 API 行为与开发环境一致;关键是客户端边界,而非 next dev / next start 差异。
  • Ant Design Pro / Umi 迁移到 Next 时,可复用 React 专题中的 Hook 思路,仅增加 "use client"。
  • 打印前调用 webPrintPdf.utils.getConnectStatus(),客户端离线时给出友好提示。
  • SSR 页面可把打印 HTML 放在客户端 state 或 ref,避免把敏感业务数据打进服务端日志。

常见问题

Next.js 能在 Server Action 里静默打印吗?

不能。静默打印依赖浏览器 + 本地客户端 WebSocket;Server Action / Route Handler 运行在服务端,无法驱动用户打印机。

App Router 报 window is not defined 怎么办?

说明在 Server Component 中 import 了 web-print-pdf。把打印逻辑移到带 use client 的组件,并仅在点击等浏览器事件中调用 printHtml。

和 React 专题有什么区别?

npm API 完全相同;Next.js 额外需要注意 Server/Client 组件边界与 use client 声明。

Mac 或信创 Linux 也能用吗?

可以。Next 前端代码跨平台;只需在对应 OS 安装官方客户端,printHtml 调用方式不变。

各平台客户端部署

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

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