1. 项目概述与核心痛点最近在做一个后台管理系统里面有个需求是用户需要批量打印大量的数据报表。一开始想得挺简单不就是调用浏览器的window.print()嘛结果一上手就发现全是坑。数据量稍微大一点浏览器原生的打印功能就完全失控了——要么是内容被截断要么是分页位置诡异表格跨页时表头不重复最头疼的是样式在打印预览里和屏幕上看到的完全是两回事。这种体验对于需要处理成百上千条记录的管理员来说简直是灾难。这时候hiprint这个专门针对Web打印的插件就进入了我的视线。它不是一个简单的封装而是一个基于jQuery的、声明式的打印设计器核心思路是让你能像画布一样通过拖拽组件的方式“画”出你想要的打印模板然后通过JSON数据驱动渲染。在Vue项目里集成它目标很明确实现精准、可控、样式稳定的数据分页打印。这不仅仅是“能打印”而是要解决原生打印的三大痛点分页不可控、样式不一致、批量操作繁琐。如果你也在Vue项目中遇到了复杂的票据打印、合同套打、带分页的清单报表这类需求那么这套方案会非常对路。2. 技术选型为什么是hiprint市面上处理Web打印的方案不少比如直接用CSS的media print做打印样式适配或者用html2canvasjspdf把页面转成PDF再打印。但经过一番对比和踩坑我最终还是选择了hiprint。2.1 主流方案对比与hiprint的优势原生window.print()media printCSS优点无依赖最简单。缺点控制力极弱。你无法精确控制分页符的位置特别是当内容高度动态变化时。表格跨页的表头重复、脚注定位、避免在行中间分页等需求实现起来非常棘手且浏览器兼容性差。样式调试更是噩梦需要写一套独立的打印样式且预览和实际输出常有差异。结论仅适用于内容简单、格式固定的单页打印。html2canvasjspdf优点能100%还原屏幕所见生成PDF文件便于下载和传输。缺点性能是最大瓶颈。渲染大量DOM节点到Canvas非常消耗资源容易导致页面卡顿甚至崩溃。生成的文件体积大且文字在PDF中是作为图片存在的无法复制和搜索这在需要存档或打印正式文件的场景下是硬伤。分页逻辑需要自己计算同样复杂。结论适合需要生成高质量、不可编辑的图片式PDF快照对性能和文本可选择性无要求的场景。hiprint优点声明式模板设计通过JSON定义模板将打印样式与业务代码彻底解耦。设计师或实施人员可以在设计器里调整无需开发人员修改代码。精准的分页控制内置了强大的分页逻辑。可以轻松设置“是否允许在元素中间分页”、“重复表头”、“每页固定页眉页脚”等。纯文本打印最终调用的是浏览器的打印接口打印出来的是矢量文字清晰且可复制符合正式票据、单据的打印要求。高性能模板渲染和数据填充是轻量级的操作即使面对上千条数据也只是JSON数据的遍历和文本替换远比DOM渲染和Canvas绘制高效。缺点需要引入额外的插件库有一定的学习成本并且其设计器界面风格可能需要进行定制化以适应项目UI。结论专为复杂、数据驱动的Web打印场景而生尤其擅长解决分页、格式固定、批量打印的需求。2.2 hiprint的核心概念理解在开始集成前需要理解它的两个核心部分hiprint核心库 (hiprint.bundle.js)负责根据模板JSON渲染打印预览、调用打印对话框。设计器 (hiprint-design)一个独立的Vue组件或页面提供拖拽式UI用于生成和编辑模板JSON。通常模板设计是管理员在后台完成的一次性动作而终端用户只使用生成好的模板进行打印。我们的集成工作主要就是让Vue项目能加载和使用这两部分。3. Vue项目集成hiprint的详细步骤这里以 Vue 3 Vite 项目为例Vue 2 的项目思路类似主要在插件注册和组件使用上略有区别。3.1 环境准备与依赖安装首先我们需要获取hiprint的源码。它通常不通过 npm 直接安装而是需要手动下载并引入。获取hiprint资源 访问hiprint的官方仓库或发布地址下载最新的发布包。通常你会得到几个核心JS文件例如hiprint.bundle.js(核心打印库)vendor.js(可能依赖的第三方库如jQuery)hiprint-design.js(设计器库)放置资源文件 将下载的.js文件放入你项目的public目录下Vite项目或static目录Vue CLI项目。这样它们可以作为静态资源被直接引用。例如放在public/plugins/hiprint/目录下。在HTML中引入 在index.html的head或body底部引入这些资源。注意顺序因为hiprint.bundle.js可能依赖vendor.js。!-- index.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 link relicon typeimage/svgxml href/vite.svg / meta nameviewport contentwidthdevice-width, initial-scale1.0 titleVue Hiprint Demo/title /head body div idapp/div script typetext/javascript src/plugins/hiprint/vendor.js/script script typetext/javascript src/plugins/hiprint/hiprint.bundle.js/script script typemodule src/src/main.js/script /body /html注意由于hiprint内部可能依赖全局的jQuery或$通过script标签全局引入是最可靠的方式。尝试通过npm包形式引入可能会遇到作用域问题。3.2 封装Vue可用的hiprint工具类由于hiprint是全局引入的我们需要将其能力封装成Vue中易于使用的形式。创建一个src/utils/hiprint.js文件。// src/utils/hiprint.js // 这里 hiprint 已经作为全局变量存在 const hiprint window.hiprint; /** * 初始化并导出一个默认的打印提供者 (Provider) * Provider 可以理解为一组可拖拽的打印元素类型集合 */ export const initHiprint () { // 检查 hiprint 是否加载成功 if (!hiprint) { console.error(hiprint 库未加载请检查静态资源引入); return null; } // 使用 hiprint 提供的默认元素类型创建 Provider // 你也可以自定义元素类型这里先用默认的 const defaultProvider new hiprint.PrintProvider(); console.log(hiprint 初始化成功); return defaultProvider; }; /** * 根据模板JSON和打印数据渲染打印预览 * param {Object} templateJson - 设计器导出的模板JSON * param {Array|Object} printData - 需要打印的数据 * param {HTMLElement} container - 用于承载预览的DOM元素 */ export const renderPrintPreview (templateJson, printData, container) { if (!hiprint) { console.error(hiprint 未初始化); return; } // 清空容器 container.innerHTML ; // 创建模板实例 const template new hiprint.PrintTemplate(templateJson); // 将数据渲染到容器中 template.print(printData, container); }; /** * 直接调用打印对话框 * param {Object} templateJson - 模板JSON * param {Array|Object} printData - 打印数据 */ export const doPrint (templateJson, printData) { if (!hiprint) { console.error(hiprint 未初始化); return; } const template new hiprint.PrintTemplate(templateJson); // 直接打印不显示预览 template.print(printData); }; // 导出 hiprint 实例以便在组件中直接使用其高级API export { hiprint };3.3 构建打印模板设计器组件 (可选但建议)如果项目需要让用户如管理员动态创建打印模板那么需要集成设计器。创建一个src/components/HiprintDesigner.vue组件。!-- src/components/HiprintDesigner.vue -- template div classdesigner-container div refdesignerEl styleheight: 800px;/div div classdesigner-actions button clickgetTemplateJson导出模板JSON/button button clickclearDesigner清空设计/button button clickloadTemplate加载模板/button /div div v-iftemplateJsonStr classjson-preview h4模板JSON/h4 pre{{ templateJsonStr }}/pre /div /div /template script setup import { ref, onMounted, onBeforeUnmount } from vue; import { hiprint } from /utils/hiprint; // 导入我们封装的工具 const designerEl ref(null); let designer null; const templateJsonStr ref(); // 初始化设计器 const initDesigner () { if (!hiprint) { console.error(hiprint 不可用); return; } // 创建一个新的设计器实例并挂载到DOM元素上 // 第二个参数是配置项可以设置初始化的元素类型面板等 designer new hiprint.PrintDesigner({ container: designerEl.value, // 可以在这里自定义可拖拽的组件 // panels: [...] }, hiprint.getDefaultElements()); }; // 导出当前设计的模板JSON const getTemplateJson () { if (designer) { const json designer.getJson(); templateJsonStr.value JSON.stringify(json, null, 2); // 在实际项目中这里通常会将 json 保存到后端数据库 console.log(模板JSON:, json); } }; // 清空设计面板 const clearDesigner () { if (designer) { designer.clear(); templateJsonStr.value ; } }; // 加载一个已有的模板JSON进行编辑 const loadTemplate () { // 假设从某个地方获取了模板JSON const savedJson { /* 你之前保存的模板JSON */ }; if (designer savedJson) { designer.update(savedJson); } }; onMounted(() { initDesigner(); }); onBeforeUnmount(() { // 清理资源防止内存泄漏 if (designer) { designer.destroy(); designer null; } }); /script style scoped .designer-container { border: 1px solid #ddd; padding: 10px; } .designer-actions { margin-top: 10px; display: flex; gap: 10px; } .json-preview { margin-top: 20px; background: #f5f5f5; padding: 10px; max-height: 300px; overflow: auto; } /style3.4 在业务页面中使用打印功能假设我们有一个订单列表需要分页打印。首先我们需要一个预先设计好的模板JSON可以从设计器导出并保存到后端。在业务页面中我们这样做!-- src/views/OrderList.vue -- template div !- 订单列表表格 -- table !-- ... 表格内容 ... -- /table button clickhandleBatchPrint批量打印订单/button !-- 打印预览模态框 -- div v-ifshowPreview classpreview-modal div classmodal-header h3打印预览/h3 button clickshowPreview false关闭/button button clickdirectPrint直接打印/button /div div refpreviewContainer classpreview-content/div /div /div /template script setup import { ref, onMounted } from vue; import { initHiprint, renderPrintPreview, doPrint } from /utils/hiprint; // 假设从后端API获取的模板JSON const printTemplateJson ref(null); // 订单数据 const orderList ref([]); // 预览相关 const showPreview ref(false); const previewContainer ref(null); // 初始化 hiprint onMounted(async () { await initHiprint(); // 从后端加载打印模板 loadPrintTemplate(); // 加载订单数据 loadOrders(); }); const loadPrintTemplate async () { // 模拟API调用 const res await fetch(/api/print-template/order); printTemplateJson.value await res.json(); }; const loadOrders async () { // 模拟API调用获取大量订单数据 const res await fetch(/api/orders); orderList.value await res.json(); }; const handleBatchPrint () { if (!printTemplateJson.value) { alert(打印模板未加载); return; } if (orderList.value.length 0) { alert(没有可打印的订单); return; } // 显示预览 showPreview.value true; // 等待DOM更新后渲染预览 setTimeout(() { renderPrintPreview( printTemplateJson.value, orderList.value, // 传入数组hiprint会自动根据模板分页 previewContainer.value ); }, 100); }; // 不预览直接调用打印机 const directPrint () { if (!printTemplateJson.value) return; doPrint(printTemplateJson.value, orderList.value); }; /script style scoped .preview-modal { position: fixed; top: 0; left: 0; width: 100%; height: 100%; background: rgba(0,0,0,0.5); display: flex; flex-direction: column; } .modal-header { background: white; padding: 10px; display: flex; justify-content: space-between; } .preview-content { flex: 1; background: white; margin: 10px; overflow: auto; } /style4. 实现分页打印的核心模板设计与配置上面集成的代码只是“骨架”真正决定分页效果的是模板JSON。这个JSON定义了纸张大小、边距、以及内容元素文本、表格、图片等的布局和分页行为。我们需要在设计器里进行配置或者手动编写这个JSON。4.1 一个典型的分页表格模板JSON结构解析以下是一个简化版的、支持分页和表头重复的订单表格模板JSON片段{ panels: [{ width: 210, height: 297, paperType: A4, paperHeader: 40, paperFooter: 60, elements: [ { type: text, options: { width: 180, height: 20, top: 10, left: 15, title: 订单列表, field: title, textAlign: center, fontSize: 16, fontWeight: bold } }, { type: table, options: { top: 40, left: 10, width: 190, height: 200, contentHeight: 180, fields: [ {field: orderId, title: 订单号, width: 80}, {field: customerName, title: 客户, width: 60}, {field: amount, title: 金额, width: 50} ], // 分页关键配置 tableHeaderRepeat: true, // 表头每页重复 tableFooterRepeat: false, canSplitRow: false, // 禁止在表格行中间分页避免一行数据被切成两半 showBorder: true }, // 数据源绑定这里告诉表格去遍历打印数据中的 items 数组 dataSource: items }, { type: text, options: { width: 180, height: 20, top: 250, left: 15, title: 第 {hiprint-printpage} 页 / 共 {hiprint-pagetotal} 页, textAlign: center, fontSize: 10 } } ] }] }4.2 关键配置项详解paperHeader和paperFooter 定义了页眉和页脚区域的高度。在这两个区域内的元素会固定出现在每一页的顶部和底部。这是实现每页固定标题、页码、公司Logo的关键。tableHeaderRepeat: true 这是实现表格跨页时表头自动重复的核心配置。设置为true后当表格内容超过一页时后续每一页的顶部都会自动渲染表头。canSplitRow: false 这个配置至关重要。当设置为false时会禁止将一行表格数据拆分到两页。打印引擎会在当前页空间不足容纳整行时强制将此行推到下一页开始保证了数据的完整性。对于清单类打印强烈建议关闭。dataSource: “items” 指定了表格绑定的数据字段。假设你的打印数据是{ items: [ ...订单列表... ] }表格就会自动遍历items数组进行渲染。如果直接传入数组[ ...订单列表... ]则dataSource可以省略或设为“”。{hiprint-printpage}和{hiprint-pagetotal} 这是hiprint内置的页码变量。可以在任何文本元素中使用它们会在渲染时被自动替换为当前页页码和总页数。4.3 设计器中的分页设置实操在设计器UI中这些设置通常通过属性面板完成选中表格元素在属性面板中找到“表头”或“高级”选项卡勾选“每页重复表头”。在同样的地方找到“行分割”或“允许分页”选项取消勾选即可设置canSplitRow: false。纸张、页眉页脚高度通常在画布的整体属性中设置。实操心得在设计复杂模板时务必先用A4纸的实物尺寸宽210mm高297mm在画布上规划。将页眉、内容区、页脚的高度分配好。内容区的高度决定了每页能放下多少行数据这有助于预估分页效果。5. 高级技巧与常见问题排查5.1 动态数据与字段映射打印数据往往不是简单的扁平列表。hiprint支持嵌套对象的字段访问。数据格式const printData { company: { name: XX公司, address: ... }, printDate: 2023-10-27, items: [ { product: { code: A001, name: 商品A }, quantity: 2, price: 100 }, // ... ] };模板字段配置在文本元素中field可以设为“company.name”来打印公司名。在表格中fields里可以配置{“field”: “product.name”, “title”: “商品名”}。5.2 自定义打印样式CSS虽然hiprint主要用JSON定义样式但也可以通过注入CSS进行微调。// 在初始化模板或打印前添加自定义样式 hiprint.setConfig({ style: .hiprint-printElement-text { font-family: SimSun, 宋体 !important; /* 强制使用打印友好的字体 */ } .hiprint-printElement-table-header { background-color: #f0f0f0 !important; font-weight: bold; } media print { /* 打印时隐藏不必要的页面元素 */ .no-print { display: none !important; } } });5.3 常见问题与解决方案速查表问题现象可能原因解决方案打印预览空白1.hiprint库未正确加载。2. 模板JSON格式错误。3. 打印数据为空或格式不符。1. 检查浏览器控制台有无JS错误确认script标签路径正确。2. 使用JSON.parse()验证模板JSON有效性。3. 打印前console.log数据确保其结构与模板字段匹配。分页位置不对内容被切断1. 元素高度计算不准确。2. 未设置canSplitRow: false行内分页。3. 页眉页脚高度 (paperHeader/Footer) 设置过大挤占了内容空间。1. 在设计器中仔细调整元素位置和高度留出安全边距。2. 为表格元素设置canSplitRow: false。3. 重新测量减小固定区域高度。表格表头不重复表格的tableHeaderRepeat属性未设置为true。在表格元素的高级属性中明确勾选“每页重复表头”。打印出来的字体与屏幕显示不一致浏览器打印时使用了默认字体未指定打印字体。通过hiprint.setConfig注入CSS为打印元素指定font-family如‘SimSun’ ‘宋体’等打印机通用字体。大量数据打印时浏览器卡死一次性渲染所有数据的DOM到预览页面DOM节点过多。hiprint本身性能较好但如果数据量极大如万条建议在后端进行分页前端分批调用打印。或者考虑使用“直接打印”模式跳过预览。设计器无法拖拽元素或样式错乱设计器所需的CSS样式未加载。确保设计器对应的CSS文件如果有也被引入到index.html中。检查浏览器控制台有无404错误。5.4 性能优化建议模板缓存将设计好的模板JSON存储在后端或localStorage中避免每次页面加载都重新获取或初始化。数据分片对于超大规模数据如超过5000条不要一次性传给hiprint。可以与后端协商实现分页查询、分批打印。例如每次打印500条用户点击“打印下一页”再处理下一批。直接打印模式如果用户不需要预览使用template.print(data)直接调起打印对话框可以节省渲染预览页面的开销。5.5 一个踩坑记录跨域与静态资源服务在开发环境下如果Vite的Dev Server和你的静态资源hiprint.bundle.js不在同一个“协议域名端口”下可能会因为CORS策略导致JS文件加载失败。最稳妥的做法就是将hiprint的资源文件放在public目录下Vite会将其作为根目录下的静态资源提供服务确保同源。我个人在几个生产项目中落地了这套方案从简单的送货单到复杂的多页报表hiprint都表现得非常稳定。它的学习曲线主要在于理解其“模板驱动”的思维模式一旦掌握了模板设计后续的维护和扩展成本极低。尤其是让业务人员通过设计器自行调整打印格式解放了开发人员的生产力这个价值远超集成它所花费的初期成本。如果非要给个建议那就是在项目初期就花点时间好好设计几个基础模板后续的打印需求几乎都能通过复用和微调模板来解决。