HTML2PDF.js 在 iOS 设备上生成空白 PDF 的原因与解决方案

碧海醫心 2026-01-24 00:00:00 次阅读

html2pdf.js 在 ios 设备上常输出空白 pdf，根本原因是其将整个 html 内容渲染到单个 canvas 元素中，而 ios 对 canvas 尺寸有严格限制（通常约 4096×4096 像素），超出即失效。

问题根源：Canvas 尺寸限制

html2pdf.js（基于 jsPDF + html2canvas）采用“全页一次性渲染”策略：先将目标 DOM 元素完整绘制到一个

你的代码中使用了 format: 'a3'（约 11.7×16.5 英寸 ≈ 297×420 mm），若内容较长或含高分辨率图表/表格，实际渲染像素极易突破限制（尤其在 scale: 2 默认高清屏适配下）。该问题虽在 Android 和桌面端也可能出现，但在 iOS 上最为普遍且难以规避。

✅ 推荐方案：迁移到 html3pdf

html3pdf 是 html2pdf.js 的积极维护分支，核心改进之一正是分页独立渲染：每一页都创建独立 Canvas，绕过单 Canvas 尺寸上限，彻底解决长文档空白问题。

迁移步骤（简洁版）

安装依赖
```
npm install html3pdf
```

替换

调用逻辑（保持 API 高度兼容）

import { html3pdf } from 'html3pdf';

function downloadPDF() {
  apply_print_style();

  const element = document.getElementById('LIMS_ROI_calculator');
  const opt = {
    margin: 0.2,
    filename: 'LIMS_ROI_calculator.pdf',
    pagebreak: { 
      mode: ['avoid-all', 'css', 'legacy'], 
      before: '#page_02' 
    },
    jsPDF: { 
      unit: 'in', 
      format: 'a3', 
      orientation: 'portrait' 
    }
  };

  // ✅ 替换为 html3pdf —— 无需修改配置结构
  html3pdf().set(opt).from(element).save();
}

? 提示：html3pdf 完全兼容 html2pdf.js 的选项语法和链式调用风格，迁移成本极低，且已修复包括 iOS Canvas 限制、CSS Grid 渲染异常、字体嵌入失败等数十个关键 issue。

⚠️ 补充建议与注意事项

避免强制放大内容：检查 apply_print_style() 中是否设置了 transform: scale(1.5) 或过大 font-size，这些会显著增加渲染像素；
启用分页控制：在长内容中显式插入，辅助 html3pdf 更精准分页；
性能权衡：因每页单独渲染，html3pdf 生成超长 PDF（如 50+ 页）时耗时略高，但稳定性远优于 html2pdf.js；
Polyfill 兼容性：确保项目已引入 core-js 或类似 polyfill，以支持 iOS 12–13 的 Promise 和 fetch。

总结

iOS 下 html2pdf.js 输出空白 PDF 并非代码错误，而是底层 Canvas 机制与平台限制冲突所致。与其尝试降尺度、裁剪内容或 hack Canvas，不如直接升级至更健壮的替代方案——html3pdf。它不仅解决了核心限制问题，还持续跟进现代 CSS 特性与移动端兼容性，是面向生产环境的推荐选择。