README

English | 简体中文

 SnapDOM

SnapDOM 是一个高性能 DOM 引擎：在浏览器中捕获已渲染的元素，并将其导出为 PNG、SVG 或 Canvas。插件可将同一次捕获转换为自包含的 HTML、PDF、可编辑矢量图、GIF、视频或供智能体使用的上下文。整个过程在页面内运行，核心引擎零依赖。

文档与演示 · 技术功能 · 官方插件 · English

 为什么选择 SnapDOM

- 速度。 在浏览器中运行实时基准测试：首次捕获与重复捕获，与 html2canvas 等库按实测时间排序。未变化的元素会复用上一次捕获。
- 保真度。 输出与浏览器实际绘制的结果一致。每个版本发布前都会在真实演示页面上运行像素测试套件。
- 灵活性。 一次捕获，导出多种格式。官方插件提供更多输出，同样的插件钩子也可用来编写你自己的插件。
- 持续维护。 过去一年大约每周发布一个版本，采用 MIT 许可证，更新日志公开。

 快速开始

sh
npm i @zumer/snapdom


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

const card = document.querySelector('card');
const image = await snapdom.toPng(card);
document.body.appendChild(image);


需要多种输出时，捕获一次即可：

js
const result = await snapdom(card);

const image = await result.toPng();
const canvas = await result.toCanvas();
const blob = await result.toBlob({ format: 'png' });
await result.download({ format: 'jpg', filename: 'card' });


即使源元素随后发生变化，结果对象仍保留这次捕获。再次调用 snapdom(card) 才会捕获新状态。

 可以用它做什么

| 用途 | 输出 | 提供方 |
| --- | --- | --- |
| 分享卡片、图表、发票或仪表盘 | SVG、PNG、JPG、WebP、Canvas 或 Blob | 核心引擎 |
| 将捕获结果用于纹理、覆盖层或过渡效果 | Canvas 与捕获几何信息 | 核心引擎 |
| 保存页面片段，供以后展示 | 包含捕获样式和字体的 HTML | html-export 插件 |
| 为智能体或日志提供页面内容 | 文本/JSON 上下文，或附带元素映射的图片 | context-export / agent-map 插件 |
| 下载文档或录制变化中的内容 | 可搜索、可分页的 PDF、动画 GIF 或浏览器编码的视频 | pdf / gif-export / video-export 插件 |
| 导出可编辑图形或复制到 Figma | 原生 SVG 形状与文本，或 Figma 剪贴板数据 | vector 插件 |

图片、HTML 和上下文导出使用捕获时保存的状态。GIF 和视频插件则在一段时间内持续捕获当前元素。

 安装

安装核心，并按需安装官方插件：

sh
npm i @zumer/snapdom@latest @zumer/snapdom-plugins@latest


所有插件包都要求 SnapDOM 3.4.0 或更高的 3.x 版本。@zumer/snapdom-plugins 5.x 是包含十一个小插件的工具箱；PDF、Vector 和 Stream 是独立的包：@zumer/snapdom-pdf、@zumer/snapdom-vector 和 @zumer/snapdom-stream。全部采用 MIT 许可证，源码位于 packages/。

也可以在浏览器中加载：

html


  snapdom.toPng(document.querySelector('card')).then(image = {
    document.body.appendChild(image);
  });



以 ES Module 形式从 CDN 加载：

js
import { snapdom } from 'https://esm.sh/@zumer/snapdom@latest';
import { htmlExport } from 'https://esm.sh/@zumer/snapdom-plugins@latest/html-export';


https://unpkg.com/@zumer/snapdom@latest/dist/snapdom.mjs 提供同一份模块。这些示例加载核心和插件的最新发布版本。

 构建产物

| 文件 | 用途 |
| --- | --- |
| dist/snapdom.mjs | 用于导入和打包工具的 ES Module |
| dist/snapdom.js | 通过 script 标签加载，提供 window.snapdom |
| types/snapdom.d.ts | TypeScript 类型声明 |

没有 CommonJS 构建产物。@zumer/snapdom/plugins 与包的主入口共用同一份运行时和插件注册表。

 基本用法

 选择输出格式

| 结果对象的方法 | 返回 |
| --- | --- |
| toPng()、toJpg()、toWebp() | HTMLImageElement |
| toSvg() | 以 SVG 为数据源的 HTMLImageElement |
| toCanvas() | HTMLCanvasElement |
| toBlob() | 若捕获或导出时未显式指定格式，则返回 SVG Blob |
| toRaw() / url | 捕获结果的 SVG Data URL |
| download() | 下载所选格式 |
| to(name, options?) | 按名称调用核心或插件导出器 |

snapdom.toPng(element, options) 等快捷方法在一次调用中完成捕获和导出。结果对象还提供 toJpeg()，作为 toJpg() 的别名。toImg() 仍然可用；导出 SVG 图片时建议使用 toSvg()。

 设置尺寸与排除内容

js
const result = await snapdom(card, {
  width: 800,
  dpr: 1,
  backgroundColor: 'ffffff',
  exclude: '.capture-ignore',
  excludeMode: 'remove'
});


width 和 height 指定输出尺寸；只设置一个时保持宽高比。只有两者都未设置时才应用 scale，最终像素尺寸还会乘以 dpr。downlo