SnapDOM

概述

SnapDOM 是新一代的 DOM 捕获引擎（DOM Capture Engine）——超高速、模块化、可扩展。它可以将任意 DOM 子树转换为自包含的结构，并导出为 SVG、PNG、JPG、WebP、Canvas、Blob，或通过插件系统生成 任何自定义格式。

SnapDOM 会保留样式、字体、背景图像、伪元素、Shadow DOM 等所有视觉特性，并通过可扩展的架构实现强大的灵活性和最高级别的捕获质量。

核心特性

• 完整的 DOM 捕获 - 支持复杂 DOM 结构的完整捕获
• 内嵌样式、伪元素和字体 - 完美保留视觉效果
• 多格式导出 - SVG、PNG、JPG、WebP、Canvas 或 Blob
• ⚡ 超快速度，无依赖 - 零依赖的高性能处理
• 100% 基于标准 Web API - 无需外部库支持
• 支持同源 iframe - 完整的页面捕获能力
• 支持 CSS counter() 和 CSS counters() - CSS 计数器功能保留
• 支持 ... 文本截断（line-clamp） - CSS 截断效果保留

安装

NPM / Yarn (稳定版)

npm i @zumer/snapdom
yarn add @zumer/snapdom

NPM / Yarn (开发版)

npm i @zumer/snapdom@dev
yarn add @zumer/snapdom@dev

CDN 使用

<!-- UMD 构建 -->
<script src="https://unpkg.com/@zumer/snapdom/dist/snapdom.js"></script>

<!-- ES 模块构建 -->
<script type="module">
  import { snapdom } from "https://unpkg.com/@zumer/snapdom/dist/snapdom.mjs";
</script>

基本用法

可复用的捕获

import { snapdom } from '@zumer/snapdom';

const el = document.querySelector('#target');
const result = await snapdom(el);

// 转换为 PNG
const img = await result.toPng();
document.body.appendChild(img);

// 直接下载
await result.download({ format: 'jpg', filename: 'my-capture' });

一步式快捷方法

const el = document.querySelector('#target');

// 直接获取 PNG 图片
const png = await snapdom.toPng(el);
document.body.appendChild(png);

// 获取 Blob 对象
const blob = await snapdom.toBlob(el);

API 方法

快捷方法

方法	描述
snapdom.toSvg(el, options?)	返回 SVG 图片
snapdom.toCanvas(el, options?)	返回 Canvas 对象
snapdom.toBlob(el, options?)	返回 Blob 对象
snapdom.toPng(el, options?)	返回 PNG 图片
snapdom.toJpg(el, options?)	返回 JPG 图片
snapdom.toWebp(el, options?)	返回 WebP 图片
snapdom.download(el, options?)	直接触发下载

返回对象方法

const result = await snapdom(element);
// result 包含以下方法:
{
  url: string;
  toRaw(): string;
  toSvg(): Promise<HTMLImageElement>;
  toCanvas(): Promise<HTMLCanvasElement>;
  toBlob(options?): Promise<Blob>;
  toPng(options?): Promise<HTMLImageElement>;
  toJpg(options?): Promise<HTMLImageElement>;
  toWebp(options?): Promise<HTMLImageElement>;
  download(options?): Promise<void>;
}

常用选项

await snapdom.toPng(element, {
  scale: 2,                    // 输出缩放倍数
  width: 800,                 // 输出宽度
  height: 600,                // 输出高度
  backgroundColor: '#fff',    // JPG/WebP 背景色
  quality: 0.9,               // JPG/WebP 质量 (0-1)
  embedFonts: true,           // 内嵌字体
  exclude: ['.no-capture'],   // 排除的选择器
  filter: (el) => el.id !== 'exclude', // 过滤函数
  useProxy: 'https://proxy.example.com/?' // CORS 代理
});

插件系统（测试版）

SnapDOM 提供强大的插件系统，支持自定义捕获和导出行为。

注册插件

import { snapdom } from '@zumer/snapdom';

// 全局注册
snapdom.plugins(myPlugin);

// 单次捕获注册
const result = await snapdom(element, {
  plugins: [myPlugin]
});

示例：叠加滤镜插件

function overlayFilterPlugin(options = {}) {
  const color = options.color ?? 'rgba(0,0,0,0.25)';

  return {
    name: 'overlay-filter',
    async afterClone(context) {
      const root = context.clone;
      if (getComputedStyle(root).position === 'static') {
        root.style.position = 'relative';
      }

      const overlay = document.createElement('div');
      overlay.style.cssText = `
        position: absolute;
        left: 0; top: 0; right: 0; bottom: 0;
        background: ${color};
        pointer-events: none;
      `;
      root.appendChild(overlay);
    }
  };
}

性能基准测试

SnapDOM 在性能方面表现卓越：

场景	SnapDOM	html2canvas	html-to-image
小尺寸 (200×100)	0.5 ms	67.7 ms	3.1 ms
页面视图 (1200×800)	0.5 ms	114.2 ms	3.3 ms
大滚动 (2000×1500)	0.5 ms	735.2 ms	984.2 ms

使用场景

• 截图功能 - 网页元素截图、图表导出
• 报告生成 - 将页面内容导出为图片格式
• 数据可视化 - 图表、仪表板的图片导出
• 文档生成 - 动态生成文档并导出
• UI 测试 - 视觉回归测试的截图对比
• 设计工具 - 在线设计工具的导出功能

资源链接

• 官方演示: https://snapdom.dev
• GitHub: https://github.com/zumerlab/snapdom
• NPM: https://www.npmjs.com/package/@zumer/snapdom
• 开发者: Zumerlab

总结

SnapDOM 是一个极其强大的 DOM 捕获引擎，具有超快的处理速度和极高的灵活性。其模块化架构和插件系统使其能够适应各种复杂的捕获需求，同时保持零依赖和高性能的特点。无论是简单的元素截图还是复杂的页面导出，SnapDOM 都能提供优秀的解决方案。