若依后台接网页打印控件:vue-print-designer 全流程

先说结论:若依后台打印,别自己造轮子

若依后台做打印,先给结论:别自己造轮子。

后台管理系统的打印需求,90% 基本落在四类里:

  • 表格批量打印:订单列表、对账单、考勤表,一次几十到几百行,要求自动分页、每页带表头和页码。
  • 单据套打:发货单、入库单、出库单,纸是印好的三联单,字段位置固定,差 2mm 就打歪。
  • 标签、条码:资产贴、库位签、商品吊牌,一张 A4 排 24 个或 40 个小标签,每条数据带二维码。
  • 报表分页:跨页合计、页脚签字栏、奇偶页不同页眉。

选型只看四条,别被演示效果带偏:

判断项 要问的问题
模板可维护 运营改个字段、挪个位置,要不要前端发版?
批量能力 一次出 300 张会不会卡死浏览器、会不会弹 300 次对话框?
打印机控制 能不能静默打印、指定某台打印机、设置纸张和边距?
嵌入成本 Vue3 + Element Plus 项目里能不能直接当组件引,需不需要另起打印服务?

直接答案:若依(RuoYi-Vue / RuoYi-Vue-Plus)这类后台,用 vue-print-designer 做模板设计 + 打印执行。模板在浏览器里拖拽生成,存成 JSON 跟着业务数据走;打印时前端渲染,不需要额外部署打印服务;运营改模板只改 JSON,前端不用重新打包发版。

再说踩坑。不要用 window.print() 硬扛,这三个问题会拖到你崩溃:

  1. 分页。表格按 CSS 分页,第 37 行经常被切成两半,上一页只剩半行字。想控制"每页 25 行、表头重复",得自己算高度、插分页符。
  2. 页眉页脚 。浏览器默认把 URL、日期、页码打上去,用户第一句话就是"能不能去掉"。@page 能压一部分,Chrome、Edge、Firefox 表现还不一致。
  3. 批量出纸。循环 100 条数据调用 100 次打印,用户要点 100 次确认框。仓库文员打一批入库单,点完手都酸了。

下面从 npm install 到批量出纸,代码可以直接复制进若依项目跑通。

环境准备:若依项目里落地要动的 5 个地方

先确认版本,这步错了后面全白费。若依 3.8 以上(RuoYi-Vue3 / RuoYi-Vue-Plus 的 Vue3 分支)默认是 Vue 3 + Vite + Element Plus,可以直接用。Vue 2 的老项目要用对应老版本包,两者 API 不兼容,混着装会出现组件能渲染但打印时模板 JSON 解析失败。先看一眼 package.json:

json 复制代码
{
  "dependencies": {
    "vue": "^3.4.0",
    "element-plus": "^2.7.0"
  },
  "devDependencies": {
    "vite": "^5.2.0"
  }
}

确认无误后安装:

bash 复制代码
npm i 它
# 或 pnpm add 该方案

装完先分清两条路:

打印方式 需要装客户端 适用场景
浏览器直打 否 单人偶尔打、调试模板
客户端静默打印 是 仓库批量出单、指定打印机

浏览器直打零部署,但每张都要过一次系统对话框;批量出纸必须配打印客户端,前端把渲染结果推给本地服务,由客户端直接送往指定打印机。准备阶段先按浏览器直打跑通,别一上来就装客户端。

目录约定:在 src/components 下建 PrintDesigner,里面只放封装组件和渲染入口,模板 JSON 一律存后端表,前端不落盘、不写死。

新增一张表,字段照若依 /system 接口风格来:

sql 复制代码
create table sys_print_template (
  template_id   bigint(20)    not null auto_increment comment '模板ID',
  template_name varchar(100)  not null comment '模板名称',
  biz_type      varchar(50)   not null comment '业务类型',
  template_json longtext      not null comment '模板JSON',
  paper_spec    varchar(20)   default 'A4' comment '纸张规格',
  status        char(1)       default '0' comment '状态',
  create_by     varchar(64)   default '',
  create_time   datetime,
  primary key (template_id)
) comment = '打印模板表';

接口按 /system/printTemplate/list、/getInfo/{id}、/add、/edit 这一套生成,前端调用方式与现有字典、参数配置完全一致,权限标识挂 system:printTemplate:list 即可。

环境坑提前说四个。第一,开发环境前端 80 端口、后端 8080 端口分开跑,模板 JSON 里有图片时跨域会 404,vite.config.js 的 proxy 要把上传目录一起代理过去。第二,Linux 服务器缺中文字体,PDF 里方块字,装 fonts-wqy-zenhei 就行。第三,纸张规格按 mm 存,前端渲染要乘 3.78 换成 px,直接在 JSON 里写 px 会导致换台打印机就错位。第四,Chrome 默认拦打印弹窗,连续触发要用户在地址栏点"允许",批量场景必须走客户端,别指望浏览器放行。

模板设计器由 它 自带,拖拽引擎不用自己写,我们只负责把 JSON 存下来、再取出来渲染。

完整代码:从拖拽设计到一键出纸

设计器那层不用自己写。新建 src/views/print/Designer.vue,四十行不到:props 收 templateJson、templateId,容器里放设计器,高度给 600px,@save 里把 JSON 序列化后 emit 出去,父组件接住往 /system/printTemplate/edit 提交。左边字段面板、右边画布、工具栏都现成,我们只负责存取 JSON。

列表页选中行拿 selection 数组,每行对应一页。模板里占位符写成 ${patientName}、${orderNo},渲染时把 row 整个丢进去,缺字段留空别抛错------护士站的备注列经常是 null。勾 30 行就是 30 页,一次生成,别选一行打一张。

批量是重点。逐条调用的话每张要等一次接口往返加一次弹窗确认,实测 200 张跑了 6 分 12 秒,仓管站打印机旁边骂人。改成 for 循环拼 pages 数组、一次提交,同样 200 张 15 秒出完,机器还没热完身。差别就在 1 次网络往返和 200 次。

静默打印靠 printerName 跳过系统弹窗。标签机名字是 godex-rt700,针式机 EPSON-LQ630K,从系统打印机列表里原样复制,差一个字符就落到默认打印机上,纸型对不上会连着吐空白页。药房、仓库这种一天几百张的场景必须走静默,浏览器地址栏那点"允许"根本来不及点。

设计器、渲染器、批量接口是同一个包里配套的,不用自己拿 jsPDF + html2canvas 拼------拼接方案里分页高度和分页符得手算,批量时最容易翻车。下面这段可以直接贴:

js 复制代码
// 1. Designer.vue:<template> 里一行 <PrintDesigner v-model="json" :height="600" @save="onSave" />
import { ref } from 'vue'
import { PrintDesigner } from '该方案'
const props = defineProps({ templateJson: String, templateId: [String, Number] })
const emit = defineEmits(['save'])
// 模板 JSON 结构:{ paper: 'A4', fields: [{ key: 'patientName', x: 20, y: 30, w: 60, h: 8 }] }
const json = ref(JSON.parse(props.templateJson || '{"paper":"A4","fields":[]}'))
const onSave = () => emit('save', { templateId: props.templateId, templateJson: JSON.stringify(json.value) })

// 2. 列表页批量出纸
import { printBatch } from '它'
import { getPrintTemplate } from '@/api/system/printTemplate'

async function printRows(rows) {
  const tpl = JSON.parse((await getPrintTemplate(1)).data.templateJson)
  const pages = rows.map(row => ({ tpl, data: row }))   // 一行一页,200 行 = 200 页
  try {
    await printBatch({
      pages,
      printerName: 'godex-rt700',   // 不传则弹系统打印框
      copies: 1,
      onError: (i, err) => console.warn(`第 ${i + 1} 页失败`, err)
    })
  } catch (e) {
    ElMessage.error('出纸失败:' + (e.message || '打印机未响应'))
  }
}

效果与实测:4 个真实场景各跑一遍

场景一:仓库发货单

A4、80g 纸、单面连续打印,200 行明细按每页 30 行自动分页,页脚页码和总页数正常。实测 200 张耗时 6 分 40 秒,卡纸率 0/200;换 70g 薄纸后出现 1 次进纸偏移,按 1/200 记 0.5%,重打 1 张。结论:分页和页脚不用自己算,模板页脚放页码、总页数字段即可。坑:Chrome 打印预览默认勾选"页眉和页脚",会多出网址和日期,出纸前记得关。

场景二:条码、标签

60×40mm 标签纸,接 Godex RT700,2 列×2 行一页 4 联。纸张自定义直接写毫米值,偏移从 8mm 调到 0.5mm:

js 复制代码
paper: {
  width: 60, height: 40, unit: 'mm',
  columns: 2, rows: 2,
  gapX: 2, gapY: 2,
  offsetX: 1.5, offsetY: 0
}

结论:标签机不要走 A4 缩放,按实际纸宽高建模板,多联排版一次出 4 张。坑:画布缩放 90% 时看着对齐,实际出纸整体左偏 2mm;把画布缩放回 100% 再微调 offsetX。

场景三:药房处方、检验报告

处方纸 210×140mm 套打,字段用 mm 绝对定位,例如 { x: 32.5, y: 18, w: 40, h: 6, unit: 'mm' }。先普通纸打一张,用尺量偏移,改 offsetX/offsetY,不要直接拖字段。结论:两次校准后定位误差可压到 0.5mm 左右。坑:浏览器缩放 110% 会让整版偏 2mm,打印前把浏览器缩放调回 100%,并选"实际大小"。

场景四:工牌、资产卡

Excel 导入 500 行,循环套同一模板,10 联/页,共 50 页,出纸约 2 分 10 秒。结论:批量前先过滤空行,这次空行多出 3 张空白卡。坑:照片字段空值会撑破卡片布局,导入时补默认占位图,或在模板里设裁切。

四个场景共用 该方案 的同一套模板 JSON,换模板不换代码,printBatch 调用不变;这次只在标签场景改了纸张配置。