snapdom

SnapDOM 技能

快速、无依赖的 DOM 转图像捕获库，可将 HTML 元素转换为可缩放的 SVG 或栅格图像格式。

何时使用此技能

在以下情况下使用 SnapDOM：

• 将 HTML 元素转换为图像（SVG、PNG、JPG、WebP）
• 捕获包含伪元素和阴影的样式化 DOM
• 导出嵌入字体和图标的元素
• 使用自定义尺寸或缩放比例创建屏幕截图
• 使用代理回退处理受 CORS 阻止的资源
• 使用插件实现自定义渲染管线
• 优化大型或复杂元素的性能

主要功能

通用导出选项

• SVG - 可缩放矢量格式，嵌入所有样式
• PNG、JPG、WebP - 可配置质量的栅格格式
• Canvas - 获取原始 Canvas 元素以便进一步处理
• Blob - 用于自定义处理的原始二进制数据

性能

• 超快捕获（小型元素为 1.6ms，4000×2000 的元素约为 171ms）
• 无依赖 - 仅使用标准 Web API
• 处理复杂元素时，性能比 html2canvas 快 10 到 40 倍

样式支持

• 嵌入字体（包括图标字体）
• CSS 伪元素（::before、::after）
• CSS 计数器
• CSS 行数限制
• 变换和阴影效果
• Shadow DOM 内容

高级功能

• 支持同源 iframe
• 针对受阻资源的 CORS 代理回退
• 用于自定义转换的插件系统
• 拉直变换（移除 rotate/translate）
• 选择性排除元素
• 紧凑边界框计算

安装

NPM/Yarn

npm install @zumer/snapdom
# or
yarn add @zumer/snapdom

CDN（ES 模块）

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

CDN（UMD）

<script src="https://unpkg.com/@zumer/snapdom/dist/snapdom.umd.js"></script>

快速入门示例

基本的可复用捕获

// Create reusable capture object
const result = await snapdom(document.querySelector('#target'));

// Export to different formats
const png = await result.toPng();
const jpg = await result.toJpg();
const svg = await result.toSvg();
const canvas = await result.toCanvas();
const blob = await result.toBlob();

// Use the result
document.body.appendChild(png);

一步导出

// Direct export without intermediate object
const png = await snapdom.toPng(document.querySelector('#target'));
const svg = await snapdom.toSvg(element);

下载元素

// Automatically download as file
await snapdom.download(element, 'screenshot.png');
await snapdom.download(element, 'image.svg');

使用选项

const result = await snapdom(element, {
  scale: 2,                    // 2x resolution
  width: 800,                  // Custom width
  height: 600,                 // Custom height
  embedFonts: true,            // Include @font-face
  exclude: '.no-capture',      // Hide elements
  useProxy: true,              // Enable CORS proxy
  straighten: true,            // Remove transforms
  noShadows: false             // Keep shadows
});

const png = await result.toPng({ quality: 0.95 });

常用选项参考

选项	类型	用途
scale	Number	缩放输出（例如，2 表示 2 倍分辨率）
width	Number	自定义输出宽度（像素）
height	Number	自定义输出高度（像素）
embedFonts	Boolean	包含非图标类 @font-face 规则
useProxy	String|Boolean	启用 CORS 代理（输入 URL，或设为 true 使用默认值）
exclude	String	用于隐藏元素的 CSS 选择器
straighten	Boolean	移除 translate/rotate 变换
noShadows	Boolean	移除阴影效果

常见用法

响应式屏幕截图

// Capture at different scales
const mobile = await snapdom.toPng(element, { scale: 1 });
const tablet = await snapdom.toPng(element, { scale: 1.5 });
const desktop = await snapdom.toPng(element, { scale: 2 });

排除元素

// Hide specific elements from capture
const png = await snapdom.toPng(element, {
  exclude: '.controls, .watermark, [data-no-capture]'
});

固定尺寸

// Capture with specific size
const result = await snapdom(element, {
  width: 1200,
  height: 630  // Standard social media size
});

CORS 处理

// Fallback for CORS-blocked resources
const png = await snapdom.toPng(element, {
  useProxy: 'https://cors.example.com/?' // Custom proxy
});

插件系统（Beta）

// Extend with custom exporters
snapdom.plugins([pluginFactory, { colorOverlay: true }]);

// Hook into lifecycle
defineExports(context) {
  return {
    pdf: async (ctx, opts) => { /* generate PDF */ }
  };
}

// Lifecycle hooks available:
// beforeSnap → beforeClone → afterClone →
// beforeRender → beforeExport → afterExport

性能比较

SnapDOM 的性能显著优于 html2canvas：

场景	SnapDOM	html2canvas	提升幅度
小型（200×100）	1.6ms	68ms	快 42 倍
中型（800×600）	12ms	280ms	快 23 倍
大型（4000×2000）	171ms	1,800ms	快 10 倍

开发

设置

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

构建

npm run compile

测试

npm test

浏览器支持

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• 移动浏览器（iOS Safari 14+、Chrome Mobile）

资源

文档

• 官方网站： https://snapdom.dev/
• GitHub 仓库： https://github.com/zumerlab/snapdom
• NPM 包： https://www.npmjs.com/package/@zumer/snapdom
• 许可证： MIT

scripts/

在此添加用于自动化的辅助脚本，例如：

• batch-screenshot.js - 捕获多个元素
• pdf-export.js - 将快照转换为 PDF
• compare-outputs.js - 比较 SVG 与 PNG 的质量

assets/

添加模板和示例：

• 常见捕获场景的 HTML 模板
• 预先配置 snapdom 的 CSS 框架
• 集成 snapdom 的样板项目

相关工具

• html2canvas - DOM 捕获替代方案（速度较慢，但兼容性更好）
• Orbit CSS Toolkit - Zumerlab 推出的配套工具包（https://github.com/zumerlab/orbit）

提示与最佳实践

1. 性能：使用 scale 代替 width/height，以获得更好的性能
2. 字体：设置 embedFonts: true，确保自定义字体正确显示
3. CORS 问题：如果图片无法加载，请使用 useProxy: true
4. 大型元素：对于复杂页面，将其拆分为较小的区块
5. 质量：对于 PNG/JPG，使用 quality: 0.95 以获得最佳质量
6. SVG 矢量图：图表和图形优先使用 SVG 导出

故障排查

元素未渲染

• 检查元素是否有足够的高度/宽度
• 确认捕获前 CSS 已完全加载
• 如果变换导致问题，请尝试 straighten: false

缺少字体

• 设置 embedFonts: true
• 确保在调用 snapdom 前已加载字体
• 检查浏览器控制台中的字体加载错误

CORS 问题

• 启用 useProxy: true
• 如果默认代理无法使用，请使用自定义代理 URL
• 检查资源是否来自同一源

性能问题

• 降低 scale 值
• 使用 noShadows: true 跳过阴影渲染
• 考虑将大型捕获拆分为较小的区段