html2canvas 踩坑记录：分享图生成与平板缩放兼容

背景

在 H5 活动里，经常需要把当前页面或某个区域「截」成一张图用于分享。
html2canvas 是常用的方案：对目标 DOM 做一次「快照」，输出 Canvas，再转成图片。

用下来有两个坑特别影响体验：资源重复请求导致卡顿 、平板端 CSS scale 导致分享图里文字错位。下面分别记录原因和做法。

---

坑一：图片/音频被重新请求，分享图生成卡顿甚至阻塞

现象

• 点击「生成分享图」后要等很久，或直接卡住。
• 打开 DevTools → Network，会发现页面里的图片、音频等资源被再次请求。
• 同一域名下浏览器对并发请求有限制（一般 6～8 个），多出来的会排队，html2canvas 在等这些资源，就会拖慢甚至阻塞生成。

原因简述

html2canvas 会克隆目标 DOM 到一个离线文档里再渲染。克隆过程中，<img>、<audio>、<video> 等会重新加载资源（或触发相关逻辑），于是产生大量重复请求，并受同域并发数限制。

解决方案

对不需要出现在分享图里的图片、音频、视频等元素，加上忽略属性，让 html2canvas 跳过它们，既不画进 Canvas，也不触发额外请求：

<img src="..." data-html2canvas-ignore="true" />
<audio src="..." data-html2canvas-ignore="true"></audio>

或在 React 里：

<img src={...} data-html2canvas-ignore="true" alt="..." />

只对「必须出现在分享图里的」内容保留不设该属性即可。

这样既减少请求，又避免无关资源拖慢生成，分享图速度会明显改善。

---

坑二：平板端 CSS scale 导致分享图里文字缩放失效、间距挤在一起

现象

• 页面针对平板做了兼容，核心是通过 CSS transform: scale(...) 对整页或某个容器做缩放。
• 在平板上页面看起来正常 ，但用 html2canvas 生成的分享图 里：
  • 文字缩放不对；
  • 字与字、行与行之间挤在一起，像被压扁了。

原因简述

html2canvas 在克隆 DOM 并计算样式时，对祖先节点上的 transform 处理并不等价于真实浏览器的渲染管线。

结果是：克隆文档里保留了祖先的 transform，但实际绘制时没有按同样方式应用，导致「视觉上」的缩放在 Canvas 里错位或失效，文字排版就乱了。

解决思路

思路是：在克隆文档里，把目标节点祖先链上的 transform 清掉，只把「等效缩放」统一施加在我们要截图的那个根节点上。这样 html2canvas 只处理一层 transform，结果就和页面看到的一致。

需要两步：

1. 在真实 DOM 上 ：算出目标节点所受的「祖先 scale」是多少（例如从某个父容器的 transform 里解析出 scaleX、scaleY）。
2. 在 onclone 里 ：在克隆文档中找到同一个目标节点，先清掉它到根路径上遇到的第一个带 transform 的节点的 transform，再给目标节点单独设置 transform: scale(scaleX, scaleY)（并设置 transform-origin，一般用 top left）。

实现要点

• 解析祖先 scale

  从目标元素开始向上遍历，用 getComputedStyle(node).transform 找到第一个非 none 的 transform，再解析成 scaleX、scaleY（支持 matrix() 和 matrix3d()，取矩阵左上 2×2 的缩放分量即可）。

• 在 onclone 里只改克隆 DOM

  在 onclone(clonedDoc) 里：

  • 用与真实 DOM 相同的选择器在 clonedDoc 里找到克隆的目标节点；
  • 从该节点向上找第一个 transform 不为 none 的祖先，把它的 transform / webkitTransform 设为 none，避免双重缩放；
  • 若 scaleX !== 1 || scaleY !== 1，给克隆目标设置：
    • transformOrigin: 'top left'
    • transform / webkitTransform: scale(scaleX, scaleY)

这样，克隆树里只有「截图根节点」带缩放，且与真实页面视觉效果一致，文字和间距就不会再错位。

示例代码结构（与项目中的用法对应）

// 1. 解析 transform 中的 scale（支持 matrix / matrix3d）
const parseTransformScale = (transform) => {
  if (!transform || transform === 'none') return { scaleX: 1, scaleY: 1 };
  const matrix3dMatch = transform.match(/^matrix3d\((.+)\)$/);
  if (matrix3dMatch) {
    const values = matrix3dMatch[1].split(',').map((v) => Number(v.trim()));
    if (values.length >= 16) {
      return {
        scaleX: Math.abs(values[0]) || 1,
        scaleY: Math.abs(values[5]) || 1,
      };
    }
  }
  const matrixMatch = transform.match(/^matrix\((.+)\)$/);
  if (matrixMatch) {
    const values = matrixMatch[1].split(',').map((v) => Number(v.trim()));
    if (values.length >= 6) {
      return {
        scaleX: Math.abs(values[0]) || 1,
        scaleY: Math.abs(values[3]) || 1,
      };
    }
  }
  return { scaleX: 1, scaleY: 1 };
};

// 2. 从目标元素向上找第一个带 transform 的祖先，并返回其 scale
const getAncestorScale = (el) => {
  let node = el;
  while (node) {
    const transform = window.getComputedStyle(node).transform;
    if (transform && transform !== 'none') {
      return parseTransformScale(transform);
    }
    node = node.parentElement;
  }
  return { scaleX: 1, scaleY: 1 };
};

// 3. 调用 html2canvas 时
const targetEl = document.querySelector('[data-share-png="common"]'); // 或你的选择器
const rect = targetEl.getBoundingClientRect();
const { scaleX, scaleY } = getAncestorScale(targetEl);

html2canvas(targetEl, {
  width: Math.ceil(rect.width),
  height: Math.ceil(rect.height),
  scale: Math.max(2, window.devicePixelRatio || 1),
  useCORS: true,
  onclone: (clonedDoc) => {
    const clonedTarget = clonedDoc.querySelector('[data-share-png="common"]');
    if (!clonedTarget) return;
    const view = clonedDoc.defaultView;

    // 从克隆目标向上找，清掉第一个带 transform 的祖先的 transform
    let node = clonedTarget;
    while (node) {
      const transform = view.getComputedStyle(node).transform;
      if (transform && transform !== 'none') {
        node.style.transform = 'none';
        node.style.WebkitTransform = 'none';
        break;
      }
      node = node.parentElement;
    }

    // 把「等效缩放」只加在目标节点上
    if (scaleX !== 1 || scaleY !== 1) {
      clonedTarget.style.transformOrigin = 'top left';
      clonedTarget.style.transform = `scale(${scaleX}, ${scaleY})`;
      clonedTarget.style.WebkitTransform = `scale(${scaleX}, ${scaleY})`;
    }
  },
}).then((canvas) => {
  // 使用 canvas.toDataURL() 等后续逻辑
});

实际项目里可以把选择器、宽高、scale 等参数按你的分享区域封装成函数，便于多处复用。

---

小结

问题	原因	做法
分享图生成慢/卡住	图片/音视频被重新请求，受同域并发限制	对不需入图的资源加 data-html2canvas-ignore="true"
平板下分享图文字错位、间距挤在一起	祖先的 CSS scale 在克隆文档中与渲染管线不一致	在 onclone 里清祖先 transform，仅对截图根节点设 scale

这两个点处理好之后，分享图在生成速度 和平板下的排版上都会稳定很多。如果你也用了 html2canvas 做 H5 分享图，希望这篇能少踩一点坑。

---

如有更好的做法或不同场景下的经验，欢迎补充。