前端 html2canvas 核心场景与实战指南

二、进阶处理：跨域图片问题

当 DOM 中包含网络图片（如 https://xxx.com/xxx.jpg）时，Canvas 会被污染导致图片空白。需配合后端 CORS 配置与前端参数。

关键点：

1. 前端配置：设置 useCORS: true + allowTaint: true。
2. 后端配置：图片服务器需返回 Access-Control-Allow-Origin: *。
3. 备选方案：若无法修改后端，可通过同源代理转发图片地址。

const canvas = await html2canvas(targetDom, {
  scale: 2,
  useCORS: true,
  allowTaint: true,
  logging: false,
  onclone: (clonedDoc) => {
    // 克隆体中处理图片地址替换
    const imgs = clonedDoc.querySelectorAll('img');
    imgs.forEach(img => {
      if (img.src.includes('跨域域名')) {
        img.src = img.src.replace('跨域域名', '同源代理域名');
      }
    });
  }
});

三、复杂场景：固定宽高 + 滚动内容截图

适用于长列表、聊天记录等需要截取完整滚动内容的场景。核心思路是临时展开滚动区域，截图后恢复。

async function captureScrollContent() {
  const targetDom = document.getElementById('targetDom');
  const originalStyle = {
    overflow: targetDom.style.overflow,
    height: targetDom.style.height
  };
  try {
    // 临时修改样式以显示所有内容
    targetDom.style.overflow = 'visible';
    targetDom.style.height = 'auto';
    
    const canvas = await html2canvas(targetDom, {
      scale: 2,
      useCORS: true,
      windowWidth: targetDom.offsetWidth,
      windowHeight: targetDom.offsetHeight
    });
    
    const base64Img = canvas.toDataURL('image/png', 1.0);
    const link = document.createElement('a');
    link.href = base64Img;
    link.download = '长列表截图.png';
    link.click();
  } finally {
    // 无论成功失败都恢复原始样式
    targetDom.style.overflow = originalStyle.overflow;
    targetDom.style.height = originalStyle.height;
  }
}

四、Vue 项目集成：组件内 DOM 截图

Vue 中需注意 DOM 渲染时机，确保数据更新后再截图，否则可能内容为空。

<template>
  <div>
    <div ref="certDom">
      <h2>{{ userName }} 的证书</h2>
      <p>项目：{{ projectName }}</p>
    </div>
    <button @click="generateCert">生成证书</button>
    <img :src="previewImg" alt="预览" />
  </div>
</template>

<script setup>
import { ref, nextTick } from 'vue';
import html2canvas from 'html2canvas';

const certDom = ref(null);
const previewImg = ref('');
const userName = ref('');
const projectName = ref('');

const generateCert = async () => {
  // 1. 等待数据加载
  await fetchUserInfo();
  // 2. 等待 Vue DOM 更新完成
  await nextTick();
  
  const canvas = await html2canvas(certDom.value, {
    scale: 2,
    useCORS: true,
    backgroundColor: '#fff'
  });
  
  previewImg.value = canvas.toDataURL('image/jpeg', 1.0);
};
</script>

五、React 项目集成：函数组件截图

React 中使用 useRef 获取 DOM 节点，利用 useEffect 或异步流程控制渲染时机。

import { useRef, useState } from 'react';
import html2canvas from 'html2canvas';

const ScreenshotComponent = () => {
  const targetRef = useRef(null);
  const [previewImg, setPreviewImg] = useState('');

  const captureDom = async () => {
    if (!targetRef.current) return;
    const canvas = await html2canvas(targetRef.current, {
      scale: 2,
      useCORS: true,
      logging: false
    });
    const base64 = canvas.toDataURL('image/png', 1.0);
    setPreviewImg(base64);
    
    const link = document.createElement('a');
    link.href = base64;
    link.download = 'react 截图.png';
    link.click();
  };

  return (
    <div style={{ padding: 20 }}>
      <div ref={targetRef} style={{ width: 400, height: 300, background: '#e8f4f8' }}>
        <h3>React 截图示例</h3>
        <p>{new Date().toLocaleString()}</p>
      </div>
      <button onClick={captureDom}>生成截图</button>
      {previewImg && <img src={previewImg} alt="预览" />}
    </div>
  );
};

六、特殊场景：隐藏 DOM 截图

适用于后台直接生成图片并下载，无需在页面展示 DOM。将 DOM 定位到视口外即可。

const hiddenDom = document.getElementById('hiddenDom');
// 初始样式建议：position: absolute; left: -9999px;
const canvas = await html2canvas(hiddenDom, {
  scale: 2,
  useCORS: true,
  logging: false
});
const base64 = canvas.toDataURL('image/jpeg', 1.0);
const link = document.createElement('a');
link.href = base64;
link.download = '隐藏 DOM 图片.jpg';
link.click();

七、性能优化：批量截图

批量生成时需按顺序执行，避免浏览器卡顿。使用 async/await 串行处理，并及时清理临时 DOM。

const certList = [
  { id: 1, userName: '张三', project: '前端开发' },
  { id: 2, userName: '李四', project: '后端开发' }
];

async function batchCapture() {
  for (const cert of certList) {
    const tempDom = document.createElement('div');
    tempDom.style.position = 'absolute';
    tempDom.style.left = '-9999px';
    tempDom.innerHTML = `<h2>${cert.userName}</h2>`;
    document.body.appendChild(tempDom);
    
    try {
      const canvas = await html2canvas(tempDom, { scale: 2 });
      const base64 = canvas.toDataURL('image/jpeg', 1.0);
      // 下载逻辑...
    } finally {
      document.body.removeChild(tempDom);
      await new Promise(resolve => setTimeout(resolve, 500)); // 防卡顿
    }
  }
}

八、常见问题排查

1. 图片模糊：默认缩放为 1，Retina 屏下会模糊。设置 scale: window.devicePixelRatio 或 2。
2. 跨域图片空白：检查后端 CORS 头及前端 useCORS: true。
3. 内容未渲染：截图过早。Vue 用 $nextTick()，React 用 useEffect 或 await 等待数据。
4. 大 DOM 卡顿：简化 DOM 结构，分批截图，关闭 logging。

九、高级应用：Canvas 转 Blob 上传

相比 Base64，Blob 格式更节省带宽，适合直接上传至服务器。

async function captureAndUpload() {
  const targetDom = document.getElementById('targetDom');
  const canvas = await html2canvas(targetDom, { scale: 2 });
  
  canvas.toBlob(async (blob) => {
    const formData = new FormData();
    formData.append('image', blob, '上传图片.jpg');
    formData.append('userId', '123');
    
    const res = await fetch('/api/upload-image', {
      method: 'POST',
      body: formData
    });
    const data = await res.json();
    console.log(data.imageUrl);
  }, 'image/jpeg', 0.8);
}

以上覆盖了从基础到高级的常见需求。实际使用中，根据具体业务调整 scale 和 backgroundColor 等参数，通常能获得最佳效果。