html2canvas 完全实战指南：基于 DOM 的浏览器端截图方案

<div id="capture" style="padding: 10px; background: #f5da55">
  <h4 style="color: #000;">Hello world!</h4>
</div>

html2canvas(document.querySelector("#capture")).then((canvas) => {
  document.body.appendChild(canvas);
});

npm install --save html2canvas

import html2canvas from "html2canvas";

yarn add html2canvas

async function generateSharePoster() {
  const posterElement = document.querySelector(".poster-container");

  const canvas = await html2canvas(posterElement, {
    scale: 2, // 高清输出
    useCORS: true, // 允许跨域图片
    backgroundColor: null, // 透明背景
    logging: false, // 关闭调试日志
  });

  // 转换为图片并触发下载
  const imgData = canvas.toDataURL("image/png");
  const link = document.createElement("a");
  link.href = imgData;
  link.download = "share-poster.png";
  link.click();
}

import html2canvas from "html2canvas";
import jsPDF from "jspdf";

async function exportToPDF() {
  const element = document.getElementById("print-area");

  const canvas = await html2canvas(element, {
    scale: 2,
    useCORS: true,
    onclone: (doc) => {
      // 在克隆文档中隐藏打印按钮，不影响原始页面
      const printBtn = doc.getElementById("print-button");
      if (printBtn) printBtn.style.visibility = "hidden";
    },
  });

  const imgData = canvas.toDataURL("image/png");
  const pdf = new jsPDF("p", "mm", "a4");

  const imgWidth = 210; // A4 宽度 mm
  const imgHeight = (canvas.height * imgWidth) / canvas.width;

  pdf.addImage(imgData, "PNG", 0, 0, imgWidth, imgHeight);
  pdf.save("document.pdf");
}

function generateMultiPagePDF(element) {
  return html2canvas(element, { scale: 2 }).then((canvas) => {
    const imgData = canvas.toDataURL("image/png");
    const pdf = new jsPDF("p", "mm", "a4");

    const pdfWidth = pdf.internal.pageSize.getWidth();
    const pdfHeight = pdf.internal.pageSize.getHeight();
    const imgWidth = canvas.width;
    const imgHeight = canvas.height;
    const ratio = Math.min(pdfWidth / imgWidth, pdfHeight / imgHeight);

    let heightLeft = imgHeight * ratio;
    let position = 0;

    // 第一页
    pdf.addImage(
      imgData,
      "PNG",
      0,
      position,
      imgWidth * ratio,
      imgHeight * ratio,
    );
    heightLeft -= pdfHeight;

    // 后续分页
    while (heightLeft > 0) {
      position = heightLeft - imgHeight * ratio;
      pdf.addPage();
      pdf.addImage(
        imgData,
        "PNG",
        0,
        position,
        imgWidth * ratio,
        imgHeight * ratio,
      );
      heightLeft -= pdfHeight;
    }

    pdf.save("multi-page.pdf");
  });
}

// OpenLayers 地图导出示例
map.once("rendercomplete", function () {
  const target = map.getViewport();

  html2canvas(target, {
    ignoreElements: function (element) {
      // 过滤掉地图控件（缩放按钮、版权信息等）
      return element.className.indexOf("ol-control") !== -1;
    },
    logging: false,
    useCORS: true,
  }).then(function (canvas) {
    canvas.toBlob(function (blob) {
      saveAs(blob, "map.png");
    });
  });
});

async function generateWithWatermark() {
  const element = document.querySelector(".document-content");
  const canvas = await html2canvas(element, { scale: 2 });

  const ctx = canvas.getContext("2d");

  // 添加文字水印
  ctx.font = "20px Arial";
  ctx.fillStyle = "rgba(0, 0, 0, 0.1)";
  ctx.rotate(-Math.PI / 6);
  ctx.fillText("CONFIDENTIAL", 100, 200);

  // 保存
  const link = document.createElement("a");
  link.download = "watermarked.png";
  link.href = canvas.toDataURL();
  link.click();
}

html2canvas(element, {
  onclone: (clonedDoc) => {
    // 在导出版本中移除屏幕专属元素
    const screenOnly = clonedDoc.getElementsByClassName("screen-only");
    Array.from(screenOnly).forEach((el) => el.remove());

    // 在导出版本中显示打印专属元素
    const printOnly = clonedDoc.getElementsByClassName("print-only");
    Array.from(printOnly).forEach((el) => (el.style.display = "block"));
  },
}).then((canvas) => {
  // 处理导出...
});

// 方案 1：显式设置 scale（推荐）
html2canvas(element, {
  scale: 2, // 或 3，根据需求平衡清晰度与性能
});

// 方案 2：使用自定义 canvas 实现更精细控制
const scaleBy = 2;
const canvas = document.createElement("canvas");
canvas.width = element.offsetWidth * scaleBy;
canvas.height = element.offsetHeight * scaleBy;
canvas.style.width = element.offsetWidth + "px";
canvas.style.height = element.offsetHeight + "px";

const ctx = canvas.getContext("2d");
ctx.scale(scaleBy, scaleBy);

html2canvas(element, {
  canvas: canvas,
  scale: 1, // 使用外部 canvas 时，内部 scale 设为 1
}).then((canvas) => {
  // canvas 已经是高分辨率输出
});

<div data-html2canvas-ignore>这段内容不会出现在截图中</div>

html2canvas(document.body, {
  ignoreElements: (element) => {
    // 排除特定类名的元素
    return (
      element.classList.contains("no-export") ||
      element.classList.contains("ad-banner") ||
      element.tagName === "BUTTON"
    );
  },
});

html2canvas(document.getElementById("map"), {
  ignoreElements: (el) =>
    el.classList.contains("gmnoprint") || // Google Maps 打印控件
    el.classList.contains("gm-style-cc") || // 版权信息
    el.tagName === "BUTTON",
});

html2canvas(document.body, {
  onclone: (clonedDoc) => {
    // 1. 移除临时元素
    const banner = clonedDoc.querySelector(".temporary-banner");
    if (banner) banner.parentNode.removeChild(banner);

    // 2. 修改文本内容
    const title = clonedDoc.querySelector("h1");
    if (title) title.textContent = "截图专用标题";

    // 3. 调整样式
    const chart = clonedDoc.querySelector(".echarts-container");
    if (chart) {
      chart.style.transform = "scale(1)"; // 取消缩放
      chart.style.width = "800px"; // 固定宽度
    }

    // 4. 显示隐藏元素
    const hidden = clonedDoc.querySelector(".hidden-for-export");
    if (hidden) hidden.style.display = "block";

    // 5. 调试技巧：将克隆文档挂载到全局以便在 DevTools 中检查
    window.clonedDoc = clonedDoc;
  },
}).then((canvas) => {
  document.body.appendChild(canvas);
});

// 场景 A：需要导出图片，图片服务器支持 CORS
html2canvas(element, {
  useCORS: true,
  allowTaint: false, // 或不设置（默认 false）
});

// 场景 B：仅展示截图，不需要导出
html2canvas(element, {
  allowTaint: true, // canvas 被污染，无法 toDataURL()
});

// 场景 C：图片服务器不支持 CORS，但需要导出
// 必须使用代理服务器
html2canvas(element, {
  proxy: "https://your-proxy-server.com/proxy",
});

<img crossorigin="anonymous" src="https://cdn.example.com/image.jpg" />

// 截图前将页面滚动到顶部，避免截断
window.scrollTo(0, 0);
document.body.scrollTop = document.documentElement.scrollTop = 0;

html2canvas(element, {
  scrollX: 0,
  scrollY: 0,
  windowWidth: document.documentElement.scrollWidth,
  windowHeight: document.documentElement.scrollHeight,
});

// 显式设置 scale
html2canvas(element, {
  scale: 2, // 或 window.devicePixelRatio
  useCORS: true,
  logging: false,
});

// 对于打印级 PDF，可设置更高 scale
html2canvas(element, {
  scale: 3,
  dpi: 192, // 可选，明确设置每英寸点数
});

// 正确配置
html2canvas(element, {
  useCORS: true,
  allowTaint: false,
});

// 同时给 img 标签添加 crossorigin 属性
// <img crossorigin="anonymous" src="..." />

#app {
  font-family:
    Helvetica, Tahoma, Arial, "PingFang SC", "Hiragino Sans GB", "Heiti SC",
    STXihei, "Microsoft YaHei", SimHei;
}

html2canvas(element, {
  onclone: function (documentClone) {
    const box = documentClone.getElementById("export-box");
    if (box) box.style.transform = "scale(1)";
  },
});

html2canvas(element, {
  onclone: (doc) => {
    const uses = doc.querySelectorAll("use");
    uses.forEach((use) => {
      const symbolId =
        use.getAttribute("href") || use.getAttribute("xlink:href");
      const symbol = doc.querySelector(symbolId);
      if (symbol) {
        const svg = document.createElementNS(
          "http://www.w3.org/2000/svg",
          "svg",
        );
        svg.innerHTML = symbol.innerHTML;
        use.parentNode.replaceChild(svg, use);
      }
    });
  },
});

await document.fonts.ready; // 等待所有字体加载完成
const canvas = await html2canvas(element, { scale: 2 });

// 方案 1：设置窗口尺寸为元素完整尺寸
html2canvas(element, {
  windowWidth: element.scrollWidth,
  windowHeight: element.scrollHeight,
  scrollX: 0,
  scrollY: 0,
});

// 方案 2：截图前将页面滚动到顶部
window.scrollTo(0, 0);
document.body.scrollTop = document.documentElement.scrollTop = 0;

html2canvas(element, {
  scale: 2,
  onclone: (clonedDoc) => {
    // 强制设置字体颜色，确保一致性
    const textElements = clonedDoc.querySelectorAll(
      "p, span, h1, h2, h3, h4, h5, h6",
    );
    textElements.forEach((el) => {
      // 获取计算样式并强制内联
      const computedStyle = window.getComputedStyle(el);
      el.style.color = computedStyle.color;
      el.style.fontFamily = computedStyle.fontFamily;
      el.style.fontSize = computedStyle.fontSize;
      el.style.lineHeight = computedStyle.lineHeight;
    });

    // 处理特定组件的样式异常
    const cards = clonedDoc.querySelectorAll(".info-card");
    cards.forEach((card) => {
      card.style.backgroundColor = "#ffffff";
      card.style.border = "1px solid #e0e0e0";
    });
  },
}).then((canvas) => {
  // 生成 PDF...
});

async function exportWithProgressBar(element) {
  // 1. 备份原始 HTML
  const originalHTML = element.innerHTML;

  // 2. 替换进度条为绝对定位版本（操作真实 DOM）
  const progressBars = element.querySelectorAll(".progress-stacked");
  progressBars.forEach((bar) => {
    const width = bar.style.width || "50%";
    const label = bar.querySelector(".progress-label")?.textContent || "";

    // 创建绝对定位的替代结构
    const replacement = document.createElement("div");
    replacement.className = "progress-absolute-wrapper";
    replacement.style.cssText = `
      position: relative;
      width: 100%;
      height: 20px;
      background: #e9ecef;
      border-radius: 4px;
    `;

    replacement.innerHTML = `
      <div style="
        position: absolute;
        left: 0; top: 0;
        width: ${width};
        height: 100%;
        background: #0d6efd;
        border-radius: 4px;
      "></div>
      <span style="
        position: absolute;
        left: 50%; top: 50%;
        transform: translate(-50%, -50%);
        font-size: 12px;
        color: #333;
        white-space: nowrap;
      ">${label}</span>
    `;

    bar.parentNode.replaceChild(replacement, bar);
  });

  try {
    // 3. 执行截图
    const canvas = await html2canvas(element, {
      scale: 2,
      useCORS: true,
    });

    // 4. 生成 PDF 或图片
    const imgData = canvas.toDataURL("image/png");
    // ... 使用 jsPDF 生成 PDF

    return imgData;
  } finally {
    // 5. 还原原始 DOM（无论成功失败都执行）
    element.innerHTML = originalHTML;
  }
}