独立的 DOM 转换指南

替换 html2canvas。
使用 SnapDOM。

SnapDOM 只捕捉一次 DOM 子树并返回可复用结果。可导出为 PNG、JPG、WebP、SVG、Canvas 或 Blob，也可以通过插件添加自定义格式。

探索引擎 →查看官方仓库 ↗

↓ 向下重新认识 DOM 捕捉

DOM → ANYTHING

Mr. SnapDOM, the official SnapDOM mascot

OFFICIAL MASCOT

认识 Mr. SnapDOM

官方吉祥物，更快、更清晰的 DOM 捕捉守护者。

01 / RETHINK

为什么要替换 html2canvas？

传统工具的目标是生成截图；SnapDOM 创建可移植的 DOM 表示，无需再次克隆即可导出多种格式。

HTML2CANVAS 模型legacy toolsSNAPDOM 模型SnapDOM

核心理念在 Canvas 上重绘像素自包含的 DOM 表示

结果复用每种输出都要重新捕捉一次克隆，多次导出

网页还原CSS 支持因库而异样式、字体、伪元素与 Shadow DOM

输出主要是位图或 SVGPNG、JPG、WebP、SVG、Canvas、Blob 与自定义格式

架构固定的捕捉流程模块化、可扩展、支持插件

02 / BENCHMARK

在同一 DOM 上测量

SnapDOM 当前版本相对各竞争库在 Chromium 基准测试中的加速倍数，越高越好。结果来自项目公开的 Vitest 基准测试。

简单节点

场景vs html2canvasvs html-to-imagevs modern-screenshot

Small · 200×100443.97×4.76×13.27×

Modal · 400×300474.08×4.89×23.09×

Page view · 1200×800546.28×4.94×92.60×

Large scroll · 2000×1500661.06×4.95×209.84×

Very large · 4000×20001102.78×4.97×621.62×

复杂节点

场景vs html2canvasvs html-to-imagevs modern-screenshot

Small · 200×100219.07×7.17×19.28×

Modal · 400×300100.18×12.42×14.50×

Page view · 1200×80020.66×15.67×11.42×

Large scroll · 2000×150010.61×16.14×10.99×

Very large · 4000×20007.35×15.88×10.66×

视口裁剪24.6×

长页面中比完整页面 toCanvas 更快

图片画廊1.97×

scale 2 的栅格 PNG 比 html2canvas 更快

压缩1.17×

背景图片画廊中更快

复现基准测试

TERMINAL

git clone https://github.com/zumerlab/snapdom.git
cd snapdom
npm install
npm run test:benchmark

查看基准测试源码 ↗

03 / MIGRATE

三分钟完成迁移

保留界面，升级捕捉引擎。

安装

添加 @zumer/snapdom 包。

NPM / 构建工具

TERMINAL

npm install @zumer/snapdom

CDN / 无需构建

HTML

<script type="module">
  import { snapdom } from
    "https://unpkg.com/@zumer/snapdom/dist/snapdom.mjs";
</script>

替换调用

将同一个目标元素传给 snapdom.toPng()。

~~- const canvas = await html2canvas(node)~~+ const image = await snapdom.toPng(node)

复用 DOM

只捕捉一次，无需重复克隆即可多次导出。

PNGJPGWEBPSVGBLOB

03 / LANDSCAPE

比较替代方案

这些库解决类似任务，但架构、维护历史和扩展方式并不相同。

html2canvas

Canvas 重绘器

流行且熟悉，但它会解释页面，并把支持的 CSS 重新绘制到 Canvas。

html-to-image

维护中的分支

dom-to-image 的可维护分支，提供便利的输出方法，仍沿用 SVG foreignObject 技术路线。

dom-to-image

影响深远的先驱

启发了许多后继项目，简单且重要，但其架构已显露年代感。

dom-to-image-more

修补增强版

增加了重要修复和 iframe 支持，同时保留原有架构与 API 形态。

对于新的客户端 DOM 捕捉项目，SnapDOM 提供了超越固定图像导出 API 的更完整扩展路径。

04 / EXTEND

可编程的捕捉引擎

插件可以介入处理流程、转换捕捉结果，甚至添加全新的导出格式。

01 / 捕捉

控制输入内容

在导出前过滤节点、替换内容并准备 DOM。

＋

02 / 转换

改变结果

无需修改核心即可组合滤镜、叠加层和后处理。

＋

03 / 导出

创造新格式

不止图像：社区示例包括 ASCII、PDF 和面向提示词的导出。

＋

04 / 集成

构建工作流

全局或按次注册插件，并可自由组合。

＋

探索官方插件系统 ↗

05 / RECIPES

日常使用示例

大多数产品中反复使用的几种模式。

JAVASCRIPT

import { snapdom } from 'snapdom'

const card = document.querySelector('#card')
const image = await snapdom.toPng(card)
await image.download({ filename: 'card.png' })

WHY IT WORKS

浏览器已经完成了最难的工作。

布局已经渲染，字体已经加载，样式已经解析。SnapDOM 将这些成果保存在可移植的表示中，而不是再次解释整套页面。

01✓伪元素

02✓Web 字体

03✓CSS 变换

04✓Shadow DOM

05✓背景图像

06✓SVG 内容

06 / FAQ

迁移前的常见问题

01SnapDOM 只是截图工具吗？+

不是。它是 DOM 捕捉引擎：snapdom() 创建可复用的表示，可以反复转换和导出。

02可以创建自定义格式吗？+

可以。插件系统允许添加导出器并接入捕捉处理流程。

03还能获得 Canvas 吗？+

可以。使用 snapdom.toCanvas(element)，或选择 PNG、JPG、WebP、SVG 与 Blob。

04跨域图片怎么办？+

浏览器安全规则仍然适用。SnapDOM 提供 useProxy 选项来处理被 CORS 拒绝的资源。

READY TO MIGRATE

先迁移一处捕捉流程。

在支持的浏览器中比较输出，然后删除旧依赖。

替换 html2canvas。使用 SnapDOM。