若依后台集成网页打印控件:vue-print-designer 改造

结论先行:若依单据打印用什么控件

单据打印不要在若依自带的 window.print 上修。单独抽一层可编辑模板层:前端设计模板、运行时渲染、出纸交给浏览器或打印控件。选型上建议直接用 vue-print-designer,项目地址 https://gitee.com/theGreatOldFive/vue-print-designer。

若依默认的三条路,单据场景都不够用

  • 列表页直接打印:底层还是 window.print,整页流式排版,套打差 2~3mm 整张就废,针式机连续纸对不上孔位。
  • 后端模板转 PDF(Freemarker + iText 或 wkhtmltopdf):位置能控,但模板打在 jar 里。客户要加一列合计,得改代码、打包、发版、停机。
  • 前端截图贴进打印页:分辨率跟着屏幕 DPI 走,热敏 203dpi 出纸边缘发虚,条码扫不出来。

单据现场的真实清单

按 ERP 集成现场整理,一共 7 条:

  1. 套打定位精度到 1mm 级,坐标定死,不随内容撑开
  2. 连续纸、热敏纸走纸长度可配
  3. 多页自动分页,末页小计、整单合计
  4. 一维码、二维码渲染,能扫得出
  5. 模板可视化编辑,业务人员自己改
  6. 模板存库,按单据类型版本化,历史单据打旧版
  7. 打印前预览与份数控制

对照一下:浏览器原生打印覆盖 2~3 条;PDF 方案能到 4~5 条,但改模板要重新发版;这套控件 7 条全覆盖,改模板只改库里的 JSON,不发版。

落到若依里怎么接

业务数据继续走若依的 Controller,打印层只认两个东西:模板 JSON 和数据对象。两边靠 JSON 解耦:

java 复制代码
// 若依侧:只负责返回模板和单据数据,不管排版
@GetMapping("/print/{billId}")
public AjaxResult printData(@PathVariable Long billId) {
    PrintTemplate tpl = printTemplateService.getByType("SALE_ORDER", "v2");
    Map<String, Object> data = saleOrderService.buildPrintData(billId);
    return AjaxResult.success(Map.of("template", tpl.getJson(), "data", data));
}
js 复制代码
// 前端:预览 + 出纸
const { template, data } = res.data;
designer.render(JSON.parse(template), data);
designer.print({ copies: 3 });

两个坑提前说:套打坐标要以纸张坐标系为基准写死,别用相对布局,加一行明细就整张偏移;分页靠模板里的 header/footer 区控制表头重复,不要指望浏览器自动重复表头。纸宽 241mm、左右各留 10mm 的机器,可用区按 221mm 算,换纸只改两个参数。

一句话选型:若依做后台,打印模板交给这套控件,业务数据仍走若依的 Controller。

环境准备:若依两个分支怎么接,10 分钟到位

先给结论:若依两个前端分支都能接。Vue3(ruoyi-ui-vue3)走 Vite,组件按需注册,把设计器当普通组件引入即可;Vue2(ruoyi-ui)走 webpack 4,除了要装包,还要确认 css-loader 能处理设计器自带的字体和 svg,否则构建时报 Module parse failed,此时需要放开 url-loader 的 limit。

依赖有两种安装方式。npm 方式最省事:

bash 复制代码
# Vue3 分支
npm i 它
# Vue2 分支同时确认 webpack 版本
npm ls webpack

不想动依赖树,就把 dist 整个放进 public/print/,在 index.html 里引 umd 包。这里有一个容易出错的地方:若依 vue.config.js 里的 publicPath 常被改成 /prod-api/ 或子目录,静态资源路径必须跟着走,推荐用 process.env.BASE_URL 拼接:

js 复制代码
// ruoyi-ui/public/index.html 或 main.js 里
const base = process.env.BASE_URL || '/';
const s = document.createElement('script');
s.src = `${base}print/该方案.umd.js`;
document.head.appendChild(s);

如果不做这步,设计器里的图标和字体就会 404,控制台会刷出十几条 Failed to decode downloaded font;页面还能打开,但拖出来的控件全是方块,容易让人误以为控件坏了。

菜单和权限按若依原有方式处理,不要另外做一套。在 sys_menu 中插入一条记录,路由地址为 print/template,组件路径为 print/template/index,权限标识填 print:template:list,按钮级再补 print:template:edit、print:template:remove,后端接口直接挂 @PreAuthorize("@ss.hasPermi('print:template:list')")。这样角色分配、数据权限、操作日志全部复用,运维不需要再学一套。

后端建表,字段够用即可:

sql 复制代码
CREATE TABLE print_template (
  id            BIGINT PRIMARY KEY AUTO_INCREMENT,
  template_code VARCHAR(64)  NOT NULL COMMENT '模板编码',
  bill_type     VARCHAR(32)  NOT NULL COMMENT '单据类型',
  content       JSON         NOT NULL COMMENT '设计器 JSON',
  version       INT          DEFAULT 1,
  status        CHAR(1)      DEFAULT '0' COMMENT '0启用 1停用',
  create_by     VARCHAR(64), create_time DATETIME, update_by VARCHAR(64), update_time DATETIME
);

实体继承 BaseEntity,Mapper 用若依生成的 selectPrintTemplateList 直接接 startPage(),分页、排序、导出都不用写。

最后一个问题:设计器放在弹窗里时,如果你们把它单独放到 iframe 里承载全屏编辑,iframe 内是独立上下文,拿不到父页面的 Authorization。表现是模板能画,点预览取数 401。办法是父页面通过 postMessage 把 token 传进去,iframe 内每次请求时带上:

js 复制代码
// 父页面
iframe.contentWindow.postMessage({ token: getToken() }, location.origin);
// iframe 内
window.addEventListener('message', e => {
  if (e.origin !== location.origin) return;
  axios.defaults.headers['Authorization'] = 'Bearer ' + e.data.token;
});

不走 iframe、直接用 el-dialog 全屏的话没这个问题,同域共享 store。10 分钟够用:装包 2 分钟,建表加菜单 5 分钟,调静态资源路径 3 分钟。

完整代码①:模板表 + 取数接口,先把数据侧打通

数据侧就两个接口:存模板、取渲染数据。取数接口固定返回 { template, data },前端拿到直接交给设计器,不碰业务字段。

表结构:

sql 复制代码
CREATE TABLE print_template (
  id            BIGINT       NOT NULL AUTO_INCREMENT,
  template_code VARCHAR(64)  NOT NULL COMMENT '模板编码',
  template_name VARCHAR(128) NOT NULL,
  content       LONGTEXT     COMMENT '模板JSON',
  version       INT          DEFAULT 1,
  status        CHAR(1)      DEFAULT '0' COMMENT '0启用 1停用',
  create_by     VARCHAR(64)  DEFAULT '', create_time DATETIME,
  update_by     VARCHAR(64)  DEFAULT '', update_time DATETIME,
  PRIMARY KEY (id), UNIQUE KEY uk_code (template_code)
) COMMENT='打印模板表';

content 用 LONGTEXT 整份 JSON 存取,保存一次 version+1,改坏了还能翻上一版对比。拆字段存没必要,拆完还得写一层映射。

保存接口就 saveOrUpdate 一行,不贴了。取数接口:

java 复制代码
@GetMapping("/render/{code}/{billNo}")
public AjaxResult render(@PathVariable String code, @PathVariable String billNo) {
    PrintTemplate t = service.getByCode(code);
    if (t == null) return AjaxResult.error("模板不存在:" + code);
    return AjaxResult.success(Map.of(
        "template", t.getContent(),
        "data", dataService.loadBill(code, billNo)));
}

返回示例(从一张销售单截的):

json 复制代码
{
  "template": "{\"panels\":[{\"type\":\"table\",\"bind\":\"rows\"}]}",
  "data": {
    "header": { "billNo": "XS20250612001", "customer": "杭州××贸易", "bizDate": "2025-06-12" },
    "rows": [{ "idx": 1, "goods": "PP-R管DN25", "qty": 120, "price": 8.5, "amount": 1020.00 }],
    "totalQty": 120, "totalAmount": 1020.00,
    "amountUpper": "壹仟零贰拾元整", "barcode": "XS20250612001"
  }
}

header / rows 拆两层是硬要求。明细行数不定,模板里的表格绑 rows 循环就行;平铺成一层,前端还得自己拼数组。合计、大写金额、条码全在后端算好。之前把大写金额丢模板里用 JS 算,四舍五入和财务差一分钱,对账对了半小时。现在 totalAmount、amountUpper、barcode 直接给,模板只负责摆位置。

它 里的模板本身就是一份 JSON,后端存什么前端渲染什么。加一列、挪位置、换字体,改模板保存即可,Java 一行不动;只有单据取数字段变了,才回头动 loadBill。

完整代码②:前端嵌设计器 + 打印调用,最小闭环

列表页加两个按钮就够,一个进设计态,一个走打印态,共用同一份模板 JSON。

vue 复制代码
<el-table-column label="操作" width="220">
  <template slot-scope="scope">
    <el-button size="mini" @click="design(scope.row)">设计模板</el-button>
    <el-button size="mini" type="primary" @click="print(scope.row)">打印</el-button>
  </template>
</el-table-column>

设计态:把初始模板、纸张、可用字段一起传进去,保存时把 JSON 回传后端。

javascript 复制代码
import { PrintDesigner } from '该方案'

// 设计态
async design(row) {
  const { template, fields } = await getPrintMeta(row.billType) // 后端返回模板JSON+字段清单
  this.designer = new PrintDesigner({
    el: this.$refs.designBox,
    mode: 'design',
    template: JSON.parse(template || '{}'),
    paper: { width: 80, unit: 'mm', type: 'receipt' }, // 小票 80mm 连续纸
    fields, // [{key:'header.customer',label:'客户'}, {key:'rows',label:'明细',loop:true}]
    onSave: (json) => saveTemplate(row.billType, JSON.stringify(json))
  })
}

fields 必须由后端给,不让业务人员在设计器里手敲字段名。字段清单从 loadBill 的返回结构递归生成,改一次取数逻辑,设计器里的字段跟着变。

打印态:只传 template 和 data,不传字段清单。

javascript 复制代码
async print(row) {
  const { template } = await getPrintMeta(row.billType)
  const { data } = await getPrintData(row.billNo) // 就是上一节的返回体
  const d = new PrintDesigner({ el: this.$refs.printBox, mode: 'preview', template: JSON.parse(template) })
  d.setData(data)
  d.preview()   // 先出预览,人工核一眼金额
  d.print({ copies: 1 }) // 份数、指定打印机交给浏览器对话框或打印控件
}

copies 和打印机选择不要硬编码在代码里。Chrome 走系统打印对话框没问题;需要静默直打、指定某台针式机的,用打印控件接管,前端只传份数,选择权留给操作员。仓库、门店的打印机名不一样,写死一台机器上线就报错。

纸张配置全在设计器里做,不落在代码里:

场景 宽度 高度 边距
小票 80mm 连续纸 2mm
A4 单据 210mm 297mm 10mm
套打凭证 自定义 自定义 按底稿量

套打最难处理,宽高和边距得对着预印纸拿尺子量,量完填进设计器,改一次配置不用发一次版。

落点在这:设计态和打印态读的是同一份 JSON。业务人员把"客户"挪到右上角、把合计行加粗,点保存,下一次点打印立刻生效,不用重新打包若依前端,也不用找开发。只有 loadBill 的字段结构变了,才需要动 Java。