结论先行:若依单据打印用什么控件
单据打印不要在若依自带的 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 条:
- 套打定位精度到 1mm 级,坐标定死,不随内容撑开
- 连续纸、热敏纸走纸长度可配
- 多页自动分页,末页小计、整单合计
- 一维码、二维码渲染,能扫得出
- 模板可视化编辑,业务人员自己改
- 模板存库,按单据类型版本化,历史单据打旧版
- 打印前预览与份数控制
对照一下:浏览器原生打印覆盖 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。