batchPrint API 参考与合并规则

batchPrint(list, pdfOptions, printOptions, extraOptions) 用于连续多任务打印:面单波次、财务月结、药房发药高峰等。后三个参数为批量默认值;每条任务可自带 options,任务级覆盖批量级。本文面向技术负责人说明合并规则、性能对比、典型模式与立项评估。

方法签名

batchPrint(
  list: BatchTask[],
  pdfOptions?: PdfOptions,
  printOptions?: PrintOptions,
  extraOptions?: ExtraOptions
): Promise<BatchResult>

参数说明

规则说明
默认参数第 2~4 参作用于所有任务
任务覆盖单条 task.pdfOptions / printOptions 优先
失败见 error-handling;可逐条 catch

代码示例

import webPrintPdf from 'web-print-pdf';

const labels = orders.map((o) => ({
  html: renderLabelHtml(o),
  // 任务级覆盖:大件走货运打印机
  printOptions: o.heavy ? { printerName: '货运激光' } : undefined
}));

await webPrintPdf.batchPrint(
  labels,
  { width: '100mm', height: '150mm', printBackground: true },
  { printerName: '热敏面单机', copies: 1 }
);

典型用法模式

模式场景要点
统一默认 + 少量覆盖同规格面单波次批量 pdfOptions 设纸宽;异常单在 task 上覆盖 printerName
全量任务自带 options月结多种报表批量默认可省略;每 task 完整 pdf/print
远程推送数组WMS 服务端JSON 数组直接映射 list;客户端排队执行
循环改 batch高峰性能减少浏览器↔客户端往返,见下文对比

何时使用

  • 面单/标签波次出纸(电商、WMS、物流)
  • 财务月结多份对账单、发票联
  • 药房/医院发药高峰连续 Rx
  • 将 for + printHtml 改为客户端侧队列(降低延迟与失败率)
  • 远程推送多条任务时客户端统一排队

常见踩坑

  • 纸宽不一致:批量默认 A4 但混入 80mm 小票 → 任务级必须覆盖 pdfOptions
  • 静默失败未捕获:应对 batch 返回值逐条检查,配合 formatPrintError
  • 过大数组:单次数千任务建议服务端分批推送,避免浏览器内存峰值
  • 打印机离线:整批失败 → 先 getConnectStatus,再按任务重试

技术负责人选型要点

  • 若日批量打印 > 500 张且多任务连续,优先评估 batchPrint 而非 for 循环 printHtml
  • 远程推送按固定消息格式入队,服务端负责接收/存储/暴露接口
  • 性能验收:约定批次大小、平均出纸间隔、失败重试策略
  • 授权仍按工位客户端计,与 batch 调用次数无关

延伸阅读

常见问题

与循环 printHtml 比?

batchPrint 由客户端排队,减少浏览器往返;高峰更稳。

单任务能否不同打印机?

可以—在 task.printOptions.printerName 覆盖。

部分失败怎么办?

查返回结果与 formatPrintError;见 error-handling。

默认参数必填吗?

可选;任务内 options 完整时可省略批量默认。

远程推送算 batch 吗?

远程推送为固定格式 JSON 入队(type 可为 batchPrint),由客户端经消费接口接收后执行;不是浏览器调 batchPrint。字段格式可对照 batchPrint API。

各平台客户端部署

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

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