html2canvas 核心使用场景与实战指南

进阶处理：跨域图片问题

当 DOM 中包含网络图片时，容易出现'图片空白'。需同时配置前端参数和后端响应头。

关键点：

1. 前端开启 useCORS: true + allowTaint: true。
2. 后端图片服务器需返回 Access-Control-Allow-Origin: *。

若后端无法修改 CORS，可尝试在 onclone 回调中替换图片地址为同源代理域名：

const canvas = await html2canvas(targetDom, {
  scale: 2,
  useCORS: true,
  allowTaint: true,
  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 渲染时机，确保数据更新后再截图。

<template>
  <div>
    <div ref="certDom" class="cert-container">
      <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 fetchUserInfo = async () => {
  const res = await fetch('/api/user');
  const data = await res.json();
  userName.value = data.userName;
  projectName.value = data.projectName;
};

const generateCert = async () => {
  await fetchUserInfo();
  await nextTick(); // 等待 DOM 更新
  
  const canvas = await html2canvas(certDom.value, {
    scale: 2,
    useCORS: true,
    backgroundColor: '#fff'
  });
  
  previewImg.value = canvas.toDataURL('image/jpeg', 1.0);
  const link = document.createElement('a');
  link.href = previewImg.value;
  link.download = `${userName.value}的证书.jpg`;
  link.click();
};
</script>

React 项目集成

函数组件中使用 useRef 获取节点，配合 Hooks 管理状态。

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 定位到视口外即可。

document.getElementById('generateBtn').addEventListener('click', async () => {
  const hiddenDom = document.getElementById('hiddenDom');
  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();
  // hiddenDom.remove(); // 可选清理
});

批量截图性能优化

批量生成时需控制顺序，避免浏览器卡顿。

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

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

常见问题排查

1. 图片模糊 原因通常是 DPI 过高。设置 scale: window.devicePixelRatio 自适应屏幕。

2. 跨域图片空白 检查后端是否配置了 Access-Control-Allow-Origin，并确保前端开启了 useCORS。

3. 内容未完全渲染 截图过早导致数据未加载。Vue 用 $nextTick()，React 用 useEffect 或 await 等待数据。

4. 大 DOM 卡顿 简化 DOM 结构，移除无关节点，分批截图，并关闭日志 logging: false。

高级方案：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);
}