html2canvas：将 HTML 渲染为 Canvas 图像

2025-02-19 08:30:13

在现代 Web 开发中，将 HTML 内容转换为图像文件是一个常见的需求，例如生成报告、创建截图或进行可视化展示。html2canvas 是一个功能强大的 JavaScript 库，能够将 HTML 元素渲染为 Canvas 图像。它支持复杂的 HTML 结构和样式，适用于各种截图和报告生成场景。本文将详细介绍 html2canvas 的主要功能、特点以及使用方法，帮助读者更好地了解和使用这款优秀的工具。

主要功能

复杂 HTML 结构支持

html2canvas 支持复杂的 HTML 结构和嵌套元素，能够准确地渲染多层嵌套的 HTML 内容。无论是简单的文本还是复杂的布局，html2canvas 都能提供高质量的渲染结果。

样式支持

html2canvas 支持各种 CSS 样式，包括颜色、字体、边框、阴影、渐变等。这种全面的样式支持确保了渲染的图像与原始 HTML 内容高度一致。

图像导出

html2canvas 提供了多种图像导出格式，包括 PNG、JPEG 和 WebP。用户可以根据需要选择合适的导出格式，满足不同的使用场景。

异步渲染

html2canvas 使用异步渲染机制，能够在不影响页面性能的情况下进行图像渲染。异步渲染机制确保了页面的流畅性和响应性。

跨浏览器兼容

html2canvas 支持多种浏览器，包括 Chrome、Firefox、Safari 和 Edge。跨浏览器兼容性确保了用户在不同浏览器中都能获得一致的渲染效果。

高度可定制

html2canvas 提供了丰富的配置选项，用户可以根据自己的需求进行定制。无论是渲染范围、图像质量还是样式处理，html2canvas 都能提供灵活的配置选项。

错误处理

html2canvas 提供了详细的错误处理机制，能够捕获和处理渲染过程中的错误。错误处理机制确保了渲染的稳定性和可靠性。

支持 SVG

html2canvas 支持 SVG 元素的渲染，能够准确地将 SVG 内容转换为 Canvas 图像。这种支持使得用户可以处理包含 SVG 的复杂 HTML 内容。

支持 Canvas 和 WebGL

html2canvas 支持 Canvas 和 WebGL 渲染，能够处理复杂的图形和动画效果。这种支持确保了渲染的图像能够包含丰富的视觉效果。

支持跨域资源

html2canvas 支持跨域资源的渲染，能够处理包含跨域图像的 HTML 内容。跨域资源支持确保了渲染的图像完整性，避免了跨域问题。

使用方法

安装 html2canvas

  1. 通过 CDN 引入: 在 HTML 文件中通过 CDN 引入 html2canvas：

    <script src="https://html2canvas.hertzen.com/dist/html2canvas.min.js"></script>

  2. 通过 npm 安装: 使用 npm 安装 html2canvas：

    npm install html2canvas

  3. 通过 yarn 安装: 使用 yarn 安装 html2canvas：

    yarn add html2canvas

基本使用

  1. HTML 结构: 创建一个基本的 HTML 结构：

    <div id="capture">
  <h1>Hello, html2canvas!</h1>
  <p>This is a sample text.</p>
</div>
<button id="capture-button">Capture</button>
<canvas id="canvas"></canvas>

  2. 初始化 html2canvas: 使用 JavaScript 初始化 html2canvas 并进行截图：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture')).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  });
});

配置选项

  1. 设置渲染范围: 设置渲染的 HTML 元素范围：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture'), {
    scale: 2, // 设置缩放比例
    useCORS: true, // 支持跨域资源
    allowTaint: true // 允许跨域污染
  }).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  });
});

  2. 设置图像质量: 设置导出图像的质量：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture'), {
    quality: 0.8 // 设置图像质量
  }).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  });
});

  3. 设置样式处理: 设置样式处理选项：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture'), {
    ignoreElements: function (element) {
      return element.classList.contains('ignore');
    }
  }).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  });
});

导出图像

  1. 导出为 PNG: 将渲染的 Canvas 图像导出为 PNG 格式：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture')).then(function (canvas) {
    const imgData = canvas.toDataURL('image/png');
    const link = document.createElement('a');
    link.href = imgData;
    link.download = 'capture.png';
    link.click();
  });
});

  2. 导出为 JPEG: 将渲染的 Canvas 图像导出为 JPEG 格式：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture')).then(function (canvas) {
    const imgData = canvas.toDataURL('image/jpeg', 0.8);
    const link = document.createElement('a');
    link.href = imgData;
    link.download = 'capture.jpeg';
    link.click();
  });
});

支持 SVG

  1. 渲染 SVG 元素: 渲染包含 SVG 的 HTML 内容：

    <div id="capture">
  <h1>Hello, html2canvas!</h1>
  <p>This is a sample text.</p>
  <svg width="100" height="100">
    <circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" fill="red" />
  </svg>
</div>
<button id="capture-button">Capture</button>
<canvas id="canvas"></canvas>

  2. 配置 SVG 渲染: 配置 SVG 渲染选项：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture'), {
    useCORS: true,
    allowTaint: true
  }).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  });
});

支持 Canvas 和 WebGL

  1. 渲染 Canvas 元素: 渲染包含 Canvas 的 HTML 内容：

    <div id="capture">
  <h1>Hello, html2canvas!</h1>
  <p>This is a sample text.</p>
  <canvas id="myCanvas" width="200" height="200"></canvas>
</div>
<button id="capture-button">Capture</button>
<canvas id="canvas"></canvas>

  2. 配置 Canvas 渲染: 配置 Canvas 渲染选项：

    document.getElementById('capture-button').addEventListener('click', function () {
  const canvas = document.getElementById('myCanvas');
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = 'blue';
  ctx.fillRect(0, 0, 200, 200);

  html2canvas(document.getElementById('capture'), {
    useCORS: true,
    allowTaint: true
  }).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  });
});

支持跨域资源

  1. 处理跨域图像: 处理包含跨域图像的 HTML 内容：

    <div id="capture">
  <h1>Hello, html2canvas!</h1>
  <p>This is a sample text.</p>
  <img src="https://example.com/image.jpg" alt="Example Image" crossOrigin="anonymous">
</div>
<button id="capture-button">Capture</button>
<canvas id="canvas"></canvas>

  2. 配置跨域资源: 配置跨域资源选项：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture'), {
    useCORS: true,
    allowTaint: true
  }).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  });
});

错误处理

  1. 捕获渲染错误: 捕获和处理渲染过程中的错误：
    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture'), {
    useCORS: true,
    allowTaint: true
  }).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  }).catch(function (error) {
    console.error('Error during rendering:', error);
  });
});

高度可定制

  1. 自定义渲染范围: 自定义渲染的 HTML 元素范围：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture'), {
    scale: 2, // 设置缩放比例
    useCORS: true, // 支持跨域资源
    allowTaint: true // 允许跨域污染
  }).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  });
});

  2. 自定义图像质量: 自定义导出图像的质量：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture'), {
    quality: 0.8 // 设置图像质量
  }).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  });
});

  3. 自定义样式处理: 自定义样式处理选项：

    document.getElementById('capture-button').addEventListener('click', function () {
  html2canvas(document.getElementById('capture'), {
    ignoreElements: function (element) {
      return element.classList.contains('ignore');
    }
  }).then(function (canvas) {
    document.getElementById('canvas').appendChild(canvas);
  });
});

总结

html2canvas 是一个功能强大的 JavaScript 库，用于将 HTML 元素渲染为 Canvas 图像。无论是复杂 HTML 结构支持、样式支持、图像导出、异步渲染、跨浏览器兼容、高度可定制、错误处理、支持 SVG、支持 Canvas 和 WebGL 还是支持跨域资源，html2canvas 都能满足用户的各种需求。

niklasvh
niklasvh/html2canvas
一个用于实现网页截图的 JavaScript 库
TypeScript
MIT
31.1 k