使用 JS 渲染页面并导出为PDF 常见问题与修复

本文直击两个最常见的导出痛点，并给出可直接落地的诊断 + 修复方案（适用于 html2canvas + jsPDF + ECharts/自绘 canvas 场景）。

问题清单

• 问题 A：导出后图表模糊，线条与文字不清晰（低分辨率）。
• 问题 B：开启高分辨率导出后，图表被放大或显示不全（比例错乱 / 裁切）。

针对每个问题：现象 → 根因 → 快速诊断 → 代码层面修复要点。

---

问题 A：图表模糊（低分辨率）

症状

• 导出的 PDF 上图表看起来像被缩小拉伸，细线与文字失真、模糊。

根因（要点）

1. 导出位图分辨率不足：html2canvas / canvas 的 scale 过小，生成的位图像素不足以满足 A4 打印分辨率。
2. 图表在默认 CSS 大小下只渲染为屏幕分辨率（devicePixelRatio）而非目标打印分辨率。

快速诊断

• 打开导出生成的中间图片（base64）查看其像素宽度（是否接近 A4@目标 DPI 的像素宽，例如 210mm@300DPI ≈ 2480px）。
• 在浏览器控制台临时运行：
  • const img = new Image(); img.src = '<base64>'; document.body.appendChild(img)，并查看自然宽度/高度。

修复要点（代码级）

1. 以目标 DPI 计算 html2canvas 的 scale：

// 目标：A4 @ 300 DPI
const A4_PX_WIDTH = 210 * 300 / 25.4; // ≈ 2480
const scale = A4_PX_WIDTH / elementCSSWidth;
html2canvas(element, { scale });

2. 对 ECharts 使用高像素比导出（避免让 html2canvas 通过普通缩放拉伸矢量）：

// ec 为 echarts 实例
const imgData = ec.getDataURL({ pixelRatio: scale, type: 'jpeg', backgroundColor: '#fff' });
// 用 <img> 临时替换 DOM 中的图表节点，保持 CSS 尺寸不变

3. 对自定义 canvas（项目里的 LineCharts）用 "intrinsic -> target" 放大方式导出：

• 源像素为 canvas.width/height（intrinsic buffer），显示尺寸用 clientWidth/clientHeight。
• 目标像素为 clientWidth * scale。

const srcW = canvas.width, srcH = canvas.height; // intrinsic
const dstW = Math.round(canvas.clientWidth * scale);
const dstH = Math.round(canvas.clientHeight * scale);
const tmp = document.createElement('canvas');
tmp.width = dstW; tmp.height = dstH;
const tctx = tmp.getContext('2d');
// 可先填白：tctx.fillStyle='#fff'; tctx.fillRect(0,0,dstW,dstH);
tctx.drawImage(canvas, 0, 0, srcW, srcH, 0, 0, dstW, dstH);
const dataUrl = tmp.toDataURL('image/jpeg', 1.0);

要点说明：让图表先以高像素渲染（或导出高像素位图），然后再由 html2canvas 捕捉页面。这样可把矢量/高 DPI 绘制的细节固化到位图中，避免最终 PDF 模糊。

---

问题 B：开启高分辨率后图表被放大或显示不全（比例错乱 / 裁切）

症状

• 在把 scale 提高后，图表在 PDF 中看起来被放大、局部被裁切，或图像比例与页面显示不一致。

根因（要点）

1. CSS 显示尺寸（clientWidth/clientHeight）与 canvas intrinsic 像素尺寸（canvas.width/height）混淆导致 drawImage 使用了错误的 source 或 dest 尺寸。Charts 实例通常会做 canvas.width = cssW * ratio 并 ctx.scale(ratio)。
2. html2canvas 的合并 canvas（content canvas）尺⼨与随后切片/插入 PDF 的换算不一致，造成裁切。

快速诊断

• 在控制台打印涉及值：
  • DOM 显示宽度：el.clientWidth
  • canvas intrinsic：canvas.width
  • html2canvas 输出 canvas：contentCanvas.width
• 若 contentCanvas.width 不等于 clientWidth * scale（预期），说明 scale 计算或替换流程有问题。

修复要点（代码级）

1. 在绘图库（src/libs/charts/index.js）中保证"清晰语义"：
   • opts.grid.width/height 应基于 dom.clientWidth/clientHeight（CSS 显示尺寸）。
   • canvas intrinsic 设置为 cssW * ratio，并 ctx.scale(ratio)。

示例（已采纳改动）：

// index.js (Charts.setOption) 建议
opts.grid.width = opts.grid.width || this.dom.clientWidth || this.dom.scrollWidth;
opts.grid.height = opts.grid.height || this.dom.clientHeight || this.dom.scrollHeight;
this.canvas.width = opts.grid.width * this.ratio;
this.canvas.height = opts.grid.height * this.ratio;
this.canvas.style.width = opts.grid.width + 'px';
this.canvas.style.height = opts.grid.height + 'px';
this.ctx.scale(this.ratio, this.ratio);

2. 导出时绘制步骤必须使用正确的 source/dest：

• sourceRect = (0,0, canvas.width, canvas.height) （intrinsic）
• destRect = (0,0, clientWidth * exportScale, clientHeight * exportScale)

这就避免了把 clientWidth 当作 source 或把 canvas.width 当作 dest 的错误。

3. html2canvas 的 scale 应与上面 exportScale 一致，随后把 contentCanvas 按相同换算切片成 A4 的像素高度并插入 PDF。

示例切片逻辑（核心）：

const contentWidth = contentCanvas.width; // pixels
const pageHeight = (contentWidth / a4PtWidth) * a4PtHeight; // 保持比例
// 逐页绘制：subCtx.drawImage(contentCanvas, 0, startY, contentWidth, subH, 0, 0, subCanvas.width, subCanvas.height);

要点说明：问题常因 "哪一个是 CSS 大小" 与 "哪一个是像素缓冲大小" 搞混而来。严格区分并使用 intrinsic → target 的绘制映射可彻底避免放大/裁切问题。

---

结论

• 模糊 = 分辨率不足 → 提高导出 scale / 先把图表以高像素导出（ECharts getDataURL({pixelRatio}) 或自绘 canvas 放大）再捕获。
• 放大/裁切 = 尺寸语义混淆 → 明确区分 CSS 显示尺寸（clientWidth）与 canvas intrinsic（canvas.width），用 intrinsic 作为 source，用 clientWidth * scale 作为目标。

把以上两点结合起来实现：优先把图表固化为高分位图，再以统一的 export-scale 用 html2canvas 捕获并按 A4 切片插入 PDF，通常即可同时解决"模糊"与"比例错乱"两个问题。