做过Vue后台项目的人多半都逃不过打印这个需求。我刚接一个报表系统的时候第一版打印功能就是直接在按钮点击里写了句window.print()。结果用户截图反馈过来打印预览里页面顶部的菜单栏、侧边栏的折叠按钮、右下角那个在线客服的悬浮气泡全进来了一张 A4 纸挤得满满当当真正要看的表格数据反而被挤到第二页去了。从那次之后我才认真把“浏览器打印”这件事当成一个正经功能来做。如果你正在做后台管理系统被要求打印订单、报表、发货单、入库单或者被那句“打印出来必须和页面效果一样”折磨过这篇文章就是给你准备的。我会从方案选型对比开始讲到打印样式的关键细节再贴出一套可以直接抄走的 Vue 打印组件最后整理一份我在实际排查中积累的问题清单。1. 打印方案选型三条路线各自的底细1.1 window.print() 直打简单但粗糙直接用window.print()是入坑的第一步也是绝大多数人第一次尝试的方案。它的逻辑很简单浏览器弹出打印预览框把当前整个文档对象模型渲染成纸质页面。在纯展示型页面里这种做法没问题——比如一个没有任何导航栏的 HTML 文档你点打印出来的就是文档本身。但在 Vue 单页应用里页面结构通常是一层套一层的顶栏、侧栏、面包屑、页脚再加上弹窗、消息提示这类挂载在 body 下的浮层元素。你调用一次window.print()就是把整个 SPA 的当前状态全部交给打印预览框。用户看到的预览和他在电脑屏幕上看到的网页几乎一模一样——侧边栏、按钮、装饰图案全在。更麻烦的是如果某个弹窗刚好开着连弹窗也会被打进纸里。有人会说那我用v-show把不需要的元素隐藏打印完再恢复。这个思路能走通但埋了不少坑。v-show只是改变display而打印场景里需要精确控制哪些区域显示、哪些区域不显示一旦全局样式和打印样式冲突隐藏逻辑很容易失效。如果项目里用了第三方 UI 组件库很多后台项目都用组件内部的 DOM 结构复杂你没法保证每一个浮层、每一个图标都加了隐藏逻辑。打印结束后还要记得恢复状态一旦用户切换路由或触发响应式更新隐藏标记可能漏掉页面就乱了。所以window.print()适合那种“整页即内容”的场景比如一个独立的静态说明页。对于内部管理系统它远远不够。1.2 iframe 打印隔离干净主流的正道iframe 方案的核心思路是制造一个干净的打印环境。做法就是动态创建一个隐藏的 iframe把需要打印的 HTML 片段写进这个 iframe 的文档流里然后调用这个 iframe 内部window.print()。因为 iframe 是一个完全独立的文档不受主页面样式和 DOM 结构污染打印预览里就是你塞进去的那段内容不会有侧边栏也不会有悬浮按钮。我在实际项目里用这个方案处理过一份包含商品表格、客户信息栏、二维码和签字区域的订单页。二维码是用第三方库生成的 base64 图片表格有二十多列。用 iframe 方案之后打印预览干干净净一张 A4 纸刚好排完一单的信息。相比之下之前的window.print()方式在预览里还出现过表格列错位、二维码被裁掉一半的问题。iframe 方案的另一个好处是样式可控。因为 iframe 内部是一个全新文档你可以只注入打印需要的样式或者干脆把组件库的样式文件也塞进去实现和屏幕上 1:1 的打印效果。后续我会在封装组件部分给出具体实现。1.3 现成的封装库值不值得用社区里有不少现成的打印库比较知名的有vue-print-nb和基于它演化出的一些版本。它们的原理大同小异基本都是封装了 iframe 打印流程暴露一个指令或者方法给你调用。我的看法是小项目、时间紧用库完全没问题。它们能解决 80% 的“把页面上某个区域拿去打印”的需求尤其是vue-print-nb的使用门槛很低引入后给目标 DOM 加一个v-print指令就能弹出打印预览。但用库也存在几个现实的限制项目如果用了 Vite部分打印库的依赖加载会有兼容性毛病需要额外配置。自定义能力受限于库作者的设计比如我想在打印前动态拼接一段额外的 HTML 或注入自定义页眉库不一定能优雅支持。一旦遇到 bug排查库内部代码比自己写的 200 行打印组件难得多因为你不知道作者当初踩过什么坑、写的时候考虑了哪些边界情况。所以如果打印是核心功能之一或者打印的内容比较复杂表格、图片、二维码、分页都有我建议自己封装一个组件。成本不高一次封装后续所有页面复用还能按业务持续迭代。1.4 我为什么最终选了 iframe 方案我的选择逻辑其实很直接第一需要打印的页面结构复杂必须隔离主文档第二业务上对打印结果有明确要求比如必须包含固定的企业抬头、必须按单据类型区分横版竖版第三打印的内容不止一个模块有的页面打印单据有的页面打印报表我需要一个统一入口。iframe 方案在这三点上都能满足。window.print()做不到隔离封装库又不够灵活自己写 iframe 组件生产力完全可以接受。后续所有打印功能都走这个组件遇到问题只需要在一个地方修复不用去每个页面改代码。2. 打印样式控制媒体查询与分页的进阶用法2.1 media print 基础样式与页面尺寸打印样式和屏幕样式是两种完全不同的渲染场景。屏幕是滚动式的长度不受限制纸是固定尺寸的每一页的长宽就是那几十厘米。所以在做打印样式时media print是你的第一道防线。media print { body { /* 隐藏所有非打印内容 */ visibility: hidden; } .print-area, .print-area * { visibility: visible; } /* 调整页边距和字号 */ .print-area { margin: 0; padding: 20mm 15mm; } }visibility: hidden配合目标区域visibility: visible是打印样式中很经典的一招。它比display: none更稳因为display: none会把元素从文档流中移除而visibility: hidden保留了原始布局打印时目标区域还是能在期望的位置上显示。页面尺寸方面A4 是最常见的打印规格可以在 CSS 里显式声明page { size: A4; margin: 15mm 10mm; }如果内容比较宽比如数据量大的报表可以设置为横向page { size: A4 landscape; }注意page规则只能用于打印媒体不影响屏幕显示。不同浏览器的支持程度也有差异尤其是一些国产浏览器内核对size属性的支持并不到位打印预览里还是要手动确认纸型。2.2 分页控制核心属性分页是打印真正让人头疼的地方。一份报表可能有几十行数据如果每一行刚好卡在页面交界处被“腰斩”阅读体验会非常差。CSS 提供了三个与分页相关的属性分别是page-break-before、page-break-after和page-break-inside以及它们在最新规范中的break-before、break-after、break-inside版本。我用得最多的是这几个模式强制某一部分从新页开始.print-section { page-break-before: always; }比如打印一份包含多个供应商报价的文档希望每个供应商的报价单独占一页就可以在供应商容器上加这个属性。避免元素内部被分页切断.product-table tr { page-break-inside: avoid; }加了这一句表格行就不会出现上一页半行、下一页半行的情况。需要说明的是page-break-inside: avoid对块级元素和表格行的支持程度不同在部分浏览器里对tr的识别不理想。我的习惯是对整行内容再包一层div或者直接给table外层容器加page-break-inside: avoid不过这样也可能导致一个很长的表格无法分页。实际使用中要对表格做分包处理把一个大表格拆分成多个table每个table中间用分页符隔开。避免一个区块和它的标题分离h3 { page-break-after: avoid; }标题含义是“在标题后面不要立刻分页”这样标题就不会孤零零地出现在页面底部而内容却跑到了下一页。虽然看起来是细节但客户拿到纸质文件的时候这些小细节直接决定了文档质量。2.3 背景颜色与图片的打印适配做打印功能时另一个高频坑是背景色不显示。我们在屏幕上看一个底色为#f8f9fa的标签感觉挺正常但到了打印预览里背景色会变成白色除非用户手动在打印对话框里勾选“背景图形”选项。要强制背景色打出颜色需要加一个属性* { -webkit-print-color-adjust: exact; print-color-adjust: exact; }加了这个之后Chrome 打印预览里即使不勾选“背景图形”指定了背景色的区域也能带色打印。不过还是建议在交付前让用户实际打印一次确认效果毕竟不同浏览器的默认行为不一样。图片打印的问题往往出在异步加载上。比如 Vue 项目里用v-for渲染一批商品图片这些图片是异步加载的。你点击“打印”按钮时某些图片可能还在加载中。iframe 打印环境里图片还没渲染出来打印结果自然就是空白区域。解决办法是打印前用 JavaScript 检查目标区域所有图片的complete状态等待全部加载完成后再调打印方法。我在封装组件时会专门写这段逻辑。3. 实操封装一个可复用的 Vue 打印组件3.1 组件设计思路与边界划分封装打印组件的关键点是搞清楚组件到底负责什么。我的做法是组件只负责“把指定的 HTML 内容干干净净地打印出来”至于内容怎么生成、样式怎么组织由业务方传入。组件内部需要做的事包括创建一个隐藏的 iframe并写入传入的 HTML 内容。注入基础打印样式字体、边距、颜色适配以及业务方额外提供的样式。等待 iframe 内的图片全部加载完再调用打印。监听打印结束事件移除 iframe避免内存泄漏。暴露一个print方法由外部触发。业务方需要做的事是把要打印的 DOM 区域转换成 HTML 字符串或者干脆引用模板字符串传入组件的printContent参数。使用v-html传入内容是一种比较方便的方式因为打印的内容可能来自接口返回的富文本也可能是现有 DOM 区域的innerHTML。这里要注意如果内容中包含事件监听使用v-html后事件不会生效但打印本来就不需要交互所以这个问题可以忽略。3.2 完整代码实现下面是我在实际项目中打磨过的一版 Vue 3 打印组件用组合式 API 写的。template div v-showfalse div refprintBox/div /div /template script setup import { ref, onBeforeUnmount } from vue const props defineProps({ // 要打印的HTML字符串 printContent: { type: String, default: }, // 业务自定义样式会拼接到样式区末尾 extraStyles: { type: String, default: }, // 打印标题会显示在打印预览顶部 printTitle: { type: String, default: 打印 } }) const emit defineEmits([beforePrint, afterPrint]) const printBox ref(null) let iframeEl null let cleanupTimer null function getDefaultStyles() { return * { margin: 0; padding: 0; box-sizing: border-box; } html, body { font-family: -apple-system, PingFang SC, Microsoft YaHei, sans-serif; color: #333; background: #fff; -webkit-print-color-adjust: exact; print-color-adjust: exact; } .print-container { width: 100%; padding: 15mm 12mm; } img { max-width: 100% !important; } table { width: 100%; border-collapse: collapse; page-break-inside: avoid; } td, th { padding: 6px 8px; border: 1px solid #ddd; text-align: left; word-break: break-all; } .page-break { page-break-before: always; } } function waitForImages(doc) { const images doc.querySelectorAll(img) const pending [] images.forEach((img) { if (!img.complete) { pending.push( new Promise((resolve) { img.onload resolve img.onerror resolve }) ) } }) return Promise.all(pending) } function buildPrintHtml() { return !DOCTYPE html html langzh-CN head meta charsetUTF-8 / title${props.printTitle}/title style ${getDefaultStyles()} ${props.extraStyles} /style /head body div classprint-container ${props.printContent} /div /body /html } function cleanup() { if (cleanupTimer) { clearTimeout(cleanupTimer) cleanupTimer null } if (iframeEl) { iframeEl.remove() iframeEl null } } async function print() { emit(beforePrint) iframeEl document.createElement(iframe) iframeEl.style.position fixed iframeEl.style.right 0 iframeEl.style.bottom 0 iframeEl.style.width 0 iframeEl.style.height 0 iframeEl.style.border 0 iframeEl.setAttribute(aria-hidden, true) document.body.appendChild(iframeEl) const doc iframeEl.contentWindow.document doc.open() doc.write(buildPrintHtml()) doc.close() const printWindow iframeEl.contentWindow try { // 等待图片全部加载完成 await waitForImages(doc) // 图片加载完成后再等待一层渲染 await new Promise((resolve) setTimeout(resolve, 100)) printWindow.focus() printWindow.print() // 部分浏览器在 print() 返回后弹窗关闭时触发 afterprint const onAfterPrint () { cleanup() emit(afterPrint) } if (printWindow.matchMedia) { const mql printWindow.matchMedia(print) mql.addListener(function listener(e) { if (!e.matches) { onAfterPrint() mql.removeListener(listener) } }) } } catch (err) { console.error(打印失败:, err) cleanup() } } onBeforeUnmount(() { cleanup() }) defineExpose({ print }) /script这段代码有几点细节需要说明一下。第一waitForImages是绕开“图片还没加载完成就触发打印”这个坑的关键。我在实际开发中碰到过订单二维码打出来是空白的情况排查半天发现二维码的图片加载速度稍慢在 iframe 文档写入之后跟手调用print()图片还没解码完成。加了等待逻辑之后这个问题就消失了。第二matchMedia(print)监听是针对打印结束的兼容方案。因为afterprint事件在部分浏览器中实现得并不好matchMedia的change事件则能比较可靠地捕捉到“退出打印模式”的瞬间。这里我用mql.addListener是因为一些旧内核浏览器不支持addEventListener方式这个写法兼容性更好。第三打印完成后必须cleanup。如果你反复点击打印按钮却不清理 iframe浏览器地址栏附近的隐藏 iframe 会越积越多整个应用的性能都会被拖累。3.3 组件调用方式与实际效果组件在业务页面里的使用方式如下。template div !-- 要打印的区域 -- div refreportContent classreport-wrapper h2月度销售报表/h2 table thead tr th商品名称/th th销量/th th金额/th /tr /thead tbody tr v-foritem in rows :keyitem.id td{{ item.name }}/td td{{ item.volume }}/td td{{ item.amount }}/td /tr /tbody /table /div button clickhandlePrint打印报表/button !-- 打印组件 -- PrintArea refprintAreaRef :print-contentprintHtml :extra-stylesextraPrintStyles / /div /template script setup import { ref, computed } from vue import PrintArea from /components/PrintArea.vue const reportContent ref(null) const printAreaRef ref(null) // 把目标区域的HTML传给打印组件 const printHtml computed(() { return reportContent.value ? reportContent.value.innerHTML : }) const extraPrintStyles .report-wrapper h2 { font-size: 18pt; text-align: center; margin-bottom: 12mm; } .report-wrapper table th { background: #f5f5f5; font-weight: bold; } function handlePrint() { printAreaRef.value.print() } /script这段代码里reportContent是你页面上真正的报表容器点击打印按钮时直接把它的innerHTML传给打印组件。打印组件内部会把这段 HTML 写进 iframe 里再配合extraPrintStyles中注入的样式进行精确控制。需要注意的一点是业务页面对打印区的样式不能依赖 Vue 的 scoped 样式。因为 scoped 样式在编译后会给选择器加上>table tr, table td { page-break-inside: avoid; }第二步如果是一个特别长的表格单纯加avoid反而会让某个大行无法分页直接溢出。这时候就得换个思路把表格按固定行数拆分。比如每 15 行拆成一个独立的table每个表格后面写一个分页标记table !-- 第1~15行 -- /table div classpage-break/div table !-- 第16~30行 -- /table这样浏览器在分页时就能从容地在表格间隙处断开每一页都很规整。实际项目中我曾经用这种方式打印过一份有 80 多行的明细表打印结果每一页的表格都是完整闭合的没有任何一行被切断。4.4 高分辨率屏幕下打印字体过小这个问题在 MacBook 这类高 DPI 设备上特别明显。屏幕上看字号是 14px感觉挺合适但到了纸面上由于物理像素和打印像素之间的换算关系差异打印出来的字可能小得需要用放大镜看。建议在打印样式中直接使用pt或mm这类物理单位来定义字体大小。比如media print { body { font-size: 12pt; } .print-title { font-size: 18pt; } table { font-size: 10pt; } }pt是打印场景的标准单位1pt 约等于 1/72 英寸。一份 A4 纸默认的可用宽度大约 170mm 到 180mm正文用 10pt 到 12pt 比较合适标题用 16pt 到 20pt。这样不论在什么屏幕上预览打印出来的实际字号都是稳定的。另外一个容易踩的坑是 Chrome 的打印预览默认缩放在 80% 或 100% 之间会有些微偏差。如果客户反馈打印内容“稍微有点挤”可以在page的margin里稍微调大一点比如从10mm调整到12mm视觉上会宽松很多。5. 一些还没写进组件但很有用的补充5.1 使用 toPrint 指令式的封装如果你不想在每一个页面都显式放置一个打印组件可以考虑把打印能力封装成一个指令或一个全局方法。比如在某个目录组件里统一注册通过事件触发打印由某个容器负责输出。这种做法的好处是调用方不需要感知 iframe 细节只需要传一个目标 DOM 的 id 或 ref 过去。简单的指令式封装思路export function printHtml(html, styles , title 打印) { // 这里可以复用上面组件里的 let 逻辑 }全局调用时在业务代码里直接import { printHtml } from /utils/print printHtml(document.querySelector(#report).innerHTML, printStyles)我个人比较喜欢组件方式因为可以配合 Vue 的生命周期处理清理工作指令方式对局部状态的管理会更复杂一些。但如果你的页面极多、又不希望每个页面都引组件全局方法也是不错的选择。5.2 打印前加水印与防伪信息有些单据需要打印水印比如“内部文件”“作废”这类文字标识。最稳妥的水印方案不是在打印样式里硬调而是把水印做成一层覆盖在内容上的半透明元素。打印时把这层元素保留非打印场景隐藏。实现上可以这样在要打印的 HTML 片段里加上一个水印层 div然后用 CSS 控制它绝对定位、倾斜一定角度、透明度设得非常低字体稍微大一点。打印时它自然会被带上不额外占用正文字面位置。水印内容多的时候需要注意分页问题。如果水印是固定在一页上的跨页时会发现第二页没有水印。如果是多页打印水印层要为每一页重复生成或者通过定位悬浮到所有页面这个相对复杂。我的经验是水印问题放到需求明确之后再处理如果业务没有明确要求不要过度设计。5.3 打印完成后的数据联动打印动作往往不只是“出纸”还会伴随订单状态的变化。比如打印完发货单之后系统可能要把订单状态从“待打印”改成“已打印”。这块逻辑可以挂在afterPrint事件上。我的做法是在组件里把afterPrint事件暴露出来业务方监听这个事件后调用更新接口。PrintArea refprintAreaRef :print-contentprintHtml after-printhandleAfterPrint /handleAfterPrint里做数据状态更新、接口请求等操作。要注意的是afterPrint事件在部分浏览器里可能不会触发所以业务逻辑不要完全依赖这个事件。稳妥的做法是打印结束后不做强制校验后台定时同步状态或者打印弹出的同时前端先更新本地状态接口失败再回滚。我在实际项目里对“打印完成”的判定并没有把宝全押在浏览器事件上而是当用户点击打印按钮后前端先乐观更新状态为“打印中”等到打印窗口关闭监听窗口的模糊/焦点变化再调接口确认。虽然不算100%完美但至少不会出现“打印成功了但订单状态一直没变”这种让客服抓狂的 bug。最后分享一个我自己的小习惯如果你刚把打印功能接入项目建议你每次改完样式都实际打印一份 PDF出来看一眼而不是只看浏览器预览。预览框的渲染和真实打印驱动之间偶尔会有细微差别特别是背景色、页边距、字体渲染这几个点。有一次我在预览里看着表格完全正常导出的 PDF 里表格右侧竟然多了一条竖线查了半天才发现是某个元素的一个border-right没受page-break-inside约束。这种问题不真正打印一次根本发现不了。打印功能看着是个“小需求”但它牵扯到 DOM 拷贝、异步加载、样式隔离、浏览器兼容、分页控制这些琐碎但真实的问题。把组件封装好后面所有打印场景都会变得很省心。希望这篇内容能帮你把 Vue 项目里的打印功能做得干净利落。
