远程打印配置指南

适用场景

• 仓库、门店 PC 只负责出纸，任务由 ERP/WMS 在服务端统一调度。
• 多工位共享同一套任务接口，前端不必重复集成远程逻辑。

工作原理

客户端连接你暴露的打印任务接口（WebSocket 或 HTTP 轮询），收到固定格式的 JSON 后由客户端本地排版、转 PDF 并出纸——不打开浏览器，与前端是否集成 npm 无关。

服务端你需要做什么

npm API（printHtml 等）与远程打印的关系

远程打印不需要在 ERP/WMS 或工位业务代码中调用 webPrintPdf.printHtml、batchPrint 等 npm API。这些 API 服务于浏览器本地打印；远程场景下它们仅作格式对照——帮助理解 printHtml(html, pdfOptions, printOptions, extraOptions) 四参如何映射为任务 JSON 的各字段。

正确链路：服务端按固定格式组装任务 → 提交到自建任务接收/存储服务 → 暴露 WebSocket/HTTP 消费接口 → 工位客户端「远程打印配置」填写该 URL → 客户端收到 JSON 后在本地执行打印（不经过浏览器 npm）。

字段含义可对照 printHtml API、batchPrint API 与 打印参数专题；本地 PoC 时可调 npm 验证版式，上线远程链路则改为服务端入队。

标准消息格式（固定，不可改结构）

下列 JSON 结构由产品规定，与客户端「测试任务」一致。入队时填入 content、pdfOptions、printOptions 等即可——由你的服务端提交，不是由网页调 npm API 生成：不要自行增删顶层字段或改字段含义。

{
  "id": "uuid",
  "timestamp": 1710000000000,
  "type": "printHtml",
  "content": "<div>Shipping label #10086</div>",
  "pdfOptions": {
    "paperFormat": "A4",
    "margin": { "top": "20px", "bottom": "20px", "left": "20px", "right": "20px" },
    "printBackground": false
  },
  "printOptions": { "paperFormat": "A4", "printerName": "Default printer" },
  "extraOptions": { "requestTimeout": 15 }
}

上面示例为 printHtml 类型的结构示意，仅列出常用字段；实际消息还包含更多字段与子项（如 extraOptions 完整配置、水印参数等）。完整清单请以客户端「测试任务」实际 JSON，或本地调用对应 npm API 时的真实输出为准，并对照 printHtml API、batchPrint API 等文档（不同 type 字段集合不同）。

type 为固定取值（如 printHtml、printHtmlByUrl、printPdfByUrl、batchPrint），表示任务载荷类型；与 npm 方法名对应，但远程出纸不调用这些方法，只下发同结构 JSON。

客户端配置（填写你暴露的接口）

在客户端 UI「远程打印配置」中选择 WebSocket 或 HTTP 轮询，并填入你在服务端暴露的 URL：

保存后，客户端连接你的接口，收到符合固定格式的 JSON 即本地打印；与浏览器页面是否打开无关。

WebSocket 模式

客户端连接你暴露的 WS 地址，收到固定格式 JSON 后本地打印；断线后按策略重连。

服务端推送示例（Node.js，需自行部署；消息体须符合固定格式）：

const WebSocket = require('ws');
const wss = new WebSocket.Server({ port: 9000 });

function buildTask() {
  return {
    id: crypto.randomUUID(),
    timestamp: Date.now(),
    type: 'printHtml',
    content: '<div>WMS label</div>',
    pdfOptions: { paperFormat: 'A4' },
    printOptions: { paperFormat: 'A4' },
    extraOptions: { requestTimeout: 15 }
  };
}

wss.on('connection', (ws) => {
  ws.send(JSON.stringify(buildTask()));
});

客户端 URL 填 ws://your-server:9000 等你实际暴露的地址。无任务时不要推送空消息。

HTTP 轮询模式

客户端定时请求你暴露的 HTTP 地址，解析统一响应格式：

// 无任务
{ "success": true, "data": null }

// 有任务（data 为完整打印消息）
{
  "success": true,
  "data": {
    "id": "...",
    "timestamp": 1710000000000,
    "type": "printHtml",
    "content": "<div>...</div>",
    "pdfOptions": { ... },
    "printOptions": { ... },
    "extraOptions": { ... }
  }
}

仅当 data 为符合固定格式的完整任务对象（含 id、timestamp、type 等）时才执行打印。

服务端拉取示例（Express，需自行部署）：

const express = require('express');
const app = express();
const queue = [];

app.get('/api/print/pull', (req, res) => {
  const task = queue.shift();
  res.json({ success: true, data: task || null });
});

// 业务系统入队
app.post('/api/print/push', express.json(), (req, res) => {
  queue.push(req.body);
  res.json({ success: true });
});

app.listen(8080);

客户端 URL 填 http://your-server:8080/api/print/pull 等你实际暴露的地址。

远程打印 vs 本地 npm API

• 远程打印：固定格式 JSON → 自建接收/存储服务 → 暴露消费接口 → 客户端填 URL 出纸（不调 npm API）
• 本地打印：Vue/React 集成 npm，用户点击后浏览器调用 webPrintPdf.printHtml（可用来对照 JSON 字段，但不是远程链路）
• 可并存：无人值守走远程入队 + 客户端消费接口；仓管补打等手动场景仍可用 npm 本地打印。