H5 应用如何将指定 DOM 节点转化为图片

在 H5 项目里，经常会遇到“把页面中的某一块内容保存成图片”的需求，比如生成分享海报、保存活动卡片、导出证书、保存订单截图等。这个需求看起来像是“截屏”，但前端真正要做的通常不是截取整个屏幕，而是把某个指定 DOM 节点渲染成一张 PNG、JPEG 或 SVG 图片。

本文以 dom-to-image 为例，讲清楚它的使用方式、基本原理和常见踩坑。

一、为什么不能直接“截图 DOM”

浏览器里的 DOM 本质上是结构化文档，不是图片。一个节点可能包含：

HTML 结构
CSS 样式
Web Font 字体
图片资源
背景图
伪元素
Canvas
SVG
异步加载内容

所以“把 DOM 变成图片”不是简单读取节点内容，而是要把这个节点的视觉结果重新绘制出来。

dom-to-image 做的事情就是：接收一个 DOM 节点，把它转换成 SVG、PNG、JPEG、Blob 或像素数据。官方 README 中也说明，它可以将任意 DOM 节点转换为 SVG、PNG 或 JPEG 图片，并通过 Promise 返回结果。参考：dom-to-image GitHub。

二、安装 dom-to-image

如果是现代前端项目，可以直接通过 npm 安装：

npm install dom-to-image

然后在代码中引入：

import domtoimage from 'dom-to-image';

如果是传统 H5 页面，也可以通过打包后的脚本引入，暴露全局变量 domtoimage。

三、最基础用法：DOM 转 PNG

假设页面中有一个海报区域：

<div id="poster" class="poster">   
   <h2>夏日活动邀请函</h2>   
   <p>扫码参与，领取专属福利</p>   
   <img src="/qrcode.png" alt="二维码" /> 
</div>  
<button id="saveBtn">保存图片</button>

对应的转换代码：

import domtoimage from 'dom-to-image';

const saveBtn = document.getElementById('saveBtn');
const poster = document.getElementById('poster');

saveBtn.addEventListener('click', async () => {
  try {
    const dataUrl = await domtoimage.toPng(poster);

    const link = document.createElement('a');
    link.download = 'poster.png';
    link.href = dataUrl;
    link.click();
  } catch (error) {
    console.error('生成图片失败:', error);
  }
});

toPng 返回的是一个 base64 格式的 Data URL，可以直接赋值给 img.src，也可以作为下载链接。

四、导出 JPEG、Blob 和 SVG

dom-to-image 常用 API 包括：

domtoimage.toPng(node);
domtoimage.toJpeg(node, { quality: 0.95 });
domtoimage.toBlob(node);
domtoimage.toSvg(node);
domtoimage.toPixelData(node);

例如导出 JPEG：

const dataUrl = await domtoimage.toJpeg(poster, {
  quality: 0.95,
});

const link = document.createElement('a');
link.download = 'poster.jpeg';
link.href = dataUrl;
link.click();

如果你要上传到服务器，toBlob 通常更方便：

const blob = await domtoimage.toBlob(poster);

const formData = new FormData();
formData.append('file', blob, 'poster.png');

await fetch('/api/upload', {
  method: 'POST',
  body: formData,
});

五、常用配置项

dom-to-image 支持传入配置对象，例如：

const dataUrl = await domtoimage.toPng(poster, {
  bgcolor: '#ffffff',
  width: poster.scrollWidth,
  height: poster.scrollHeight,
  style: {
    transform: 'scale(1)',
    transformOrigin: 'top left',
  },
  cacheBust: true,
});

几个常见配置：

bgcolor：设置导出图片背景色，避免透明背景。
width / height：指定导出尺寸。
style：在渲染前临时应用到节点上的样式。
quality：JPEG 图片质量，范围是 0 到 1。
cacheBust：给资源 URL 添加时间戳，减少缓存导致的图片加载问题。
filter：过滤不想导出的节点。

例如隐藏按钮：

const dataUrl = await domtoimage.toPng(poster, {
  filter(node) {
    return !node.classList?.contains('no-export');
  },
});

六、它的实现原理

dom-to-image 的核心思路大致是：

克隆目标 DOM 节点。
计算节点及其子节点的样式，并复制到克隆节点。
处理伪元素。
内联 Web Font。
内联图片和背景图资源。
把克隆后的 DOM 序列化为 XML。
使用 SVG 的 <foreignObject> 包裹 HTML 内容。
如果需要 PNG 或 JPEG，再把 SVG 绘制到离屏 Canvas 上，最终导出图片。

这也是为什么它能保留大部分 HTML 和 CSS 效果，但同时也会受到浏览器安全策略、跨域资源、Canvas 污染等限制。

七、H5 场景中的常见问题

最常见的问题是图片跨域。如果 DOM 中包含外部图片，而图片服务没有正确配置 CORS，最终可能导致 Canvas 被污染，导出失败。解决方式通常有三种：使用同域图片；图片服务添加 CORS 响应头；或者后端先把图片转成 base64 再返回给前端。

第二个问题是字体未加载完成。生成图片前最好等待字体和图片加载完毕：

async function waitForReady() {
  if (document.fonts?.ready) {
    await document.fonts.ready;
  }

  const images = Array.from(document.images);
  await Promise.all(
    images.map((img) => {
      if (img.complete) return Promise.resolve();

      return new Promise((resolve, reject) => {
        img.onload = resolve;
        img.onerror = reject;
      });
    })
  );
}

使用时：

await waitForReady();
const dataUrl = await domtoimage.toPng(poster);

第三个问题是移动端导出的图片模糊。可以通过放大导出尺寸来提高清晰度：

const scale = window.devicePixelRatio || 2;

const dataUrl = await domtoimage.toPng(poster, {
  width: poster.offsetWidth * scale,
  height: poster.offsetHeight * scale,
  style: {
    transform: `scale(${scale})`,
    transformOrigin: 'top left',
    width: `${poster.offsetWidth}px`,
    height: `${poster.offsetHeight}px`,
  },
});

八、封装一个通用方法

实际项目里建议封装一层：

import domtoimage from 'dom-to-image';

export async function exportNodeToImage(node, options = {}) {
  if (!node) {
    throw new Error('导出节点不存在');
  }

  if (document.fonts?.ready) {
    await document.fonts.ready;
  }

  const scale = options.scale || window.devicePixelRatio || 2;
  const width = node.offsetWidth;
  const height = node.offsetHeight;

  return domtoimage.toPng(node, {
    bgcolor: '#ffffff',
    cacheBust: true,
    width: width * scale,
    height: height * scale,
    style: {
      transform: `scale(${scale})`,
      transformOrigin: 'top left',
      width: `${width}px`,
      height: `${height}px`,
      ...options.style,
    },
    ...options,
  });
}

调用：

const dataUrl = await exportNodeToImage(document.getElementById('poster'));

const link = document.createElement('a');
link.download = 'poster.png';
link.href = dataUrl;
link.click();

九、适合与不适合的场景

dom-to-image 很适合 H5 海报、分享卡片、证书、二维码活动图、局部页面导出等场景。

但它不太适合复杂长页面截图、大量节点导出、强依赖跨域图片的页面、复杂 Canvas/WebGL 场景，以及需要在 Safari 中稳定运行的业务。官方也提到，IE 不支持，Safari 因 <foreignObject> 安全模型较严格，支持并不理想。参考：dom-to-image 浏览器说明。

十、注意事项

在 iPhone 机型上面，由Safari 浏览器的 foreignObject 兼容性问题，最好不好使用 toPng 的方法，使toSvg 方法更好用

十一、总结

用 dom-to-image 将指定 DOM 节点转成图片，本质上是一次“前端渲染快照”：它把 DOM、样式、字体和图片资源整合起来，再借助 SVG 与 Canvas 输出图片。

项目落地时，重点关注三件事：资源是否跨域、字体和图片是否加载完成、移动端清晰度是否足够。把这些问题处理好，dom-to-image 就能很好地支撑大多数 H5 海报和分享图片生成需求。

H5应用如何将指定DOM节点转化为图片