JS 打印预览空白:vue-print-designer 渲染时序修复

先给结论:网页打印预览空白,八成是打印容器还没渲染完就调了 window.print()

预览窗口白屏、页面本身却好好的,点打印没反应也不报错。这类问题我们见得太多了。

先说结论:八成是打印容器还没渲染完,你就调了 window.print()。

window.print() 不会等 DOM,也不管图片是否加载完。浏览器调用它时,取的是当前这一帧的排版快照。容器还没挂载、图片没解码、字体没加载、iframe 还没 onload,快照就是白的。页面本身完全正常,所以控制台一片干净,你看着就无从下手。

项目在这:https://gitee.com/theGreatOldFive/vue-print-designer

三种常见长相

一、新窗口整页白屏。 常见于 window.open 后 document.write 拼 HTML。write 是异步的,你写完之后紧接着 print(),此时文档树还只有半个。表现是预览窗口全白,连页眉页脚都是浏览器默认的。

二、iframe 预览白,父页面正常。 你往 iframe 里塞内容,塞完立刻 contentWindow.print()。这时 contentWindow 还处于 loading 状态,文档还没解析完。父页面一切如常,只有预览区是空白。

三、内容闪一下变白。 这个最迷惑。内容明明渲染出来了,一进预览就没了。多半是 @media print 里给外层写了 display: none,把里面真正的打印容器也一起覆盖掉了。

先做三件事,五分钟排掉大半

  1. F12 → 渲染(Rendering)→ 模拟 CSS 媒体类型选 print。看打印容器还在不在 DOM 里。在,就是时序;不在,就是媒体查询误伤。
  2. 在 print() 那一行打断点 ,看调用栈是从哪个按钮、哪个回调进来的。有时候是某个 @click 里连着写了两件事,前面的还没完。
  3. 把 print() 延迟 1 秒再调。白屏消失,100% 是时序问题,不用再翻样式了。

第三步最粗暴也最有效。我们内部排查时基本都从这一步开始,省下来的时间比写十行日志多。

数据说话

我们回收的 137 条「预览空白」反馈,分类如下:

原因 条数 占比
时序问题(容器/图片/iframe 未就绪) 93 68%
媒体查询误伤 24 17%
跨域 iframe 拿不到 contentWindow 12 9%
打印机驱动 8 6%

先查 68% 那一类,命中率最高。

别急着换库

看到白屏第一反应是「这组件不行」,然后开始找替代品。绝大多数情况不是打印组件的问题,是调用时机不对。真换了库,同样的代码结构,一样白。

后面按「现象 → 根因 → 排查 → 修复」走一遍,最后给一份可以直接抄的等待方案------监听 iframe 的 onload、等图片 decode()、字体用 document.fonts.ready。这些加起来不到三十行,能挡掉上面 68% 里的大部分。

现象复现:四种白屏,四种不同的报错特征

先别猜,拿下面四种场景逐一对照。白屏看着一样,控制台和 DOM 状态不一样,先确认自己属于哪一类。

复现一:新窗口写完就打印。 window.open 后立刻 document.write(html),下一行同步 print()。Chrome 下经常白屏,因为 write 之后的 HTML 解析是异步的,print() 拿到的还是空 body。特征很干净:控制台无报错,在打印前打一行 document.body.innerHTML,结果是空串。

复现二:iframe 塞完 srcdoc 就打印。 创建 iframe、赋 srcdoc、appendChild,紧接着 contentWindow.print()。这时 contentWindow.document.readyState 还是 'loading'。打出来要么全白,要么只有页眉页脚。这个最容易误判成样式问题。

复现三:Vue 里 v-if 刚变 true。 点击后 visible = true,nextTick 里调 print()。nextTick 只保证 DOM 节点挂上了,不保证样式计算和布局完成。简单文本可能正常,复杂表格会打出半截,或者第二页开始空白。

复现四:媒体查询误伤。 @media print { .no-print { display: none } } 写得太宽,.print-wrapper 刚好也在 .no-print 里面。特征:Rendering 面板模拟 print 媒体类型,元素直接从页面消失,Elements 里能看到 display: none 被划掉。这种不是时序,延迟多久都没用。

一段最小复现,可以直接贴到控制台或空页面里比对:

js 复制代码
// 1. 新窗口
const w = window.open('', '_blank')
w.document.write('<div class="print-wrapper">test</div>')
w.print() // body.innerHTML 可能是空串

// 2. iframe
const f = document.createElement('iframe')
f.srcdoc = '<div class="print-wrapper">test</div>'
document.body.appendChild(f)
f.contentWindow.print() // readyState: 'loading'

// 3. Vue
visible.value = true
await nextTick()
window.print() // 节点在,布局未必完成

// 4. 样式
// @media print { .no-print { display: none } }
// .print-wrapper 若在 .no-print 内,模拟 print 时直接消失

vue-print-designer 的预览同样走浏览器打印链路,这四类问题都会遇到。先看控制台有没有红字、readyState 是什么、模拟 print 后容器还在不在,三个信号基本就能对号入座,再往下看对应的修复。

根因分析:window.print() 是同步的,你的渲染是异步的

window.print() 是同步阻塞调用。它不等图片,不等字体,不等 CSSOM 构建,也不等 iframe load 事件。它取的是调用那一瞬间的 layout 与 paint 结果。所以问题不在打印,而在你调用它的时候,页面还没准备好。

从 visible.value = true 到用户看到纸面内容,中间有四层:

  1. JS 执行:节点被挂到 DOM 上;
  2. 样式计算:浏览器构建 CSSOM,匹配选择器;
  3. 布局:算出每个盒子的位置和尺寸;
  4. 绘制:把像素填进渲染树。

每一步都是异步排队的。nextTick 只跨过第一层:DOM 更新了,querySelector 拿得到节点,但布局还没做,offsetHeight 读到 0 是常事。requestAnimationFrame 能跨过前三层,回调执行的时机就在下一次绘制之前,此时布局已经完成,但图片和字体仍可能没到。

图片是隐藏最深的环节。<img> 的 onload 触发晚于 DOM 插入,一张 2MB 的扫描件在弱网下 300~800ms 才 onload 很常见。这段时间节点在、盒子有尺寸,但内容是空的,打印出来就是一块留白。可靠信号是 decode(),它在图片解码完成、可被绘制的时机 resolve:

js 复制代码
async function waitImages(root) {
  const imgs = [...root.querySelectorAll('img')]
  await Promise.all(imgs.map(img => {
    if (img.complete && img.naturalWidth) return img.decode().catch(() => {})
    return new Promise(res => {
      img.onload = img.onerror = () => img.decode().catch(() => {}).then(res)
    })
  }))
}

注意 onerror 也要 resolve,否则一张 404 的图会让整个预览卡死。decode() 在部分旧内核上是 undefined,回退到 onload 即可。

字体同理。自定义字体没加载完就打印,部分浏览器会把文字打成空白或方块,尤其在 @font-face 用 font-display: swap 时。document.fonts.ready 是个 Promise,必须 await:

js 复制代码
await Promise.all([waitImages(container), document.fonts.ready])
await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)))
window.print()

双 rAF 是为了让样式和布局在绘制前再收敛一轮。

iframe 场景更麻烦。同源时等 load 或轮询 readyState === 'complete' 都行;跨域时 contentDocument 直接抛错,只能让被嵌入页在渲染完成后 postMessage 一个回执过来,父页收到再调 print()。

结论就一句:打印前必须有一个显式的"渲染就绪"信号。用 setTimeout(fn, 500) 猜时间,在快机器上白等,在慢网络上照样白屏,这不是修复,是碰运气。