SnapDOM v3 功能特性全解析捕获、导出、插件与缓存机制技术指南【免费下载链接】snapdomHigh-performance engine for capturing, modifying, and converting DOM elements into any format.项目地址: https://gitcode.com/GitHub_Trending/sn/snapdom导读本文是 SnapDOM v3 的官方技术特性参考全面覆盖从 DOM 捕获克隆、样式快照、资源内联到多格式导出、插件系统、缓存与跨浏览器处理的完整技术栈。SnapDOM 在浏览器中捕获渲染后的界面状态核心产物是可复用的图像与 canvas 导出插件则进一步提供 HTML、结构化上下文、元素地图、PDF 与录制能力。读完本文你将掌握 SnapDOM 每个核心能力的行为边界、关键配置项的语义与默认值以及它们背后的源码实现依据能够据此为实际项目做出正确的捕获方案选型。捕获与克隆Capture CloneSnapDOM 的核心流程是克隆选中的子树 → 快照计算样式 → 内联子树所需资源最终产出一个自包含、可独立渲染的克隆。整个管线在 src/core/capture.js 中实现入口captureDOM负责element → clone渲染引擎再负责clone → pixels。snapdom.fromString()提供了一条脱离页面挂载的捕获路径它接受一段 HTML 字符串将标记离屏挂载到当前文档因此页面 CSS 与字体同样生效完成捕获后自动清理。需要注意其安全边界——标记会经innerHTML写入真实文档并按页面标记的方式激活img onerror等内联处理器会在调用方源中执行因此传入前必须自行消毒不可信的 HTML。该行为在 src/api/snapdom.js 中有明确注释这不是可修复的 bug而是捕获需要真实布局的必然代价安全责任在调用方。单根元素时该元素即捕获目标否则以包装层为目标混合文本片段如Hello strongworld/strong会保留整体包装。另外fromString强制burst: false因为一次性挂载销毁后无法再被复用。各类内容的捕获行为内容捕获行为开放 Shadow DOM展平 shadow root作用域化样式并解析分配的 slot同源 iframe连同其自身文档中的资源与字体一起捕获跨域 iframe使用有尺寸的占位符placeholders: false时使用不可见的间隔占位Canvas捕获当前位图及固有尺寸与 CSS 尺寸Video在可读时捕获当前帧否则回退到 poster音频控件使用绘制的播放器表示表单控件保留当前值、checked/indeterminate 状态、选区及状态相关样式图片与 picture冻结选中的响应式源与渲染尺寸包括object-fit与object-position内联 SVG保留绘制样式并内联引用的外部定义与 symbol滚动容器保留滚动位置、裁剪与定位后代核心会遮罩密码框其他可见输入值默认保持可见除非插件或排除规则将其移除。Firefox 的复选框与单选钮使用绘制的替代物原生 SVG 渲染差异所致。scripts、template等不渲染的节点会被跳过克隆根的外边距会被中和对应 capture.js 中的neutralizeRootMarginCollapse修复 #426屏幕外content-visibility内容会被强制可用以完成捕获。样式处理Styles样式的核心机制是计算样式被复制并去重为生成的类class 级联作者!important规则与内联优先级得以保留。在 src/core/capture.js 中prepareClone负责克隆与样式快照styleShareSafe决定是否启用同一性共享快速路径identity-share当样式表不可扫描或存在运行中的动画时自动回退到完整读取。伪元素、文本装饰、文本描边、字体变体与 OpenType 设置均被捕获。伪元素内容中的 CSS 计数器支持 reset、increment、嵌套与 counter 样式。行数截断line clamping与省略号ellipsis会在 SVG 渲染需要处转换为捕获文本lineClampTree见 src/core/capture.js。根变换包含独立的translate、rotate与scale并做 origin-aware 边界计算。根平移被归一化outerTransforms: false还会移除旋转但保留scale与skew。outerShadows: false移除根的阴影、轮廓与drop-shadow()但保留 blurtrue包含根效果subtree额外包含后代绘制到根盒之外的阴影墨迹。显式裁剪边界永不扩展。背景、遮罩、border-image、clip-path 与混合模式均保留其捕获样式。捕获路径支持时包含自定义滚动条样式滚动内容本身按不含自定义滚动条的状态捕获。reconcile: true会在文档中测量已样式化的克隆并与源比对修正发散盒子可修复文本换行或布局差异代价是额外一次测量往返注释明确为 roughly doubles capture time。excludeStyleProps通过 RegExp 或谓词排除指定属性如/^--/排除 CSS 变量见 src/core/context.js 中 #348 的说明。图片与背景Images Backgrounds图片、SVG 图片引用、CSS 背景层、遮罩与 border-image 都会被内联。多层背景保留定位、尺寸、重复与混合设置image-set()候选项跟随页面的设备像素比。响应式图片使用选中的源而非回退的src常见懒加载属性也会被解析。图片抓取共享进行中的请求并缓存资源。useProxy支持代理 URL 或模板用于跨域资源抓取。fallbackURL为加载失败的图片提供替换资源。内联的栅格图片会被降采样到捕获所需的分辨率尽量保留源编码格式且仅当更小的图片确实节省字节时才采用compress机制见 src/core/capture.js 中compressCloneAssets。更大尺寸的导出可以恢复捕获时的原始图——它不会重新读取实时图片的后续版本即冻结原图语义restoreCompressedAssets从__compressedSnapshot恢复。Canvas 尺寸受浏览器安全限制约束超大的导出可能被降采样并给出警告。字体与图标字体Fonts Icon FontsembedFonts: auto默认值只嵌入捕获子树实际使用的文档声明的 Web 字体系统字体页面的捕获跳过整个嵌入阶段零成本。true与false则显式启用或禁用 Web 字体嵌入。字体管线的两半在 src/modules/fonts.js 中collectFontUsage遍历子树一次记录每个使用的 family/weight/style/stretch 以及展示的每个码点embedCustomFonts扫描文档样式表同源经 CSSOM、跨域抓取、嵌套import展平保留匹配使用变体且命中使用码点的 face并把所有url()转为 data: URL。选项用途localFonts提供带 family 与 source 的字体描述符可附加 weight/style/stretchexcludeFonts排除指定字体家族、域或子集fontStylesheetDomains向跨域样式表扫描添加域iconFonts用家族名或模式扩展图标字体检测被识别的图标字体会渲染为图片包括连字图标因为图标字体从不嵌入——SVG 内部无法加载其字形。资源访问仍取决于浏览器权限与 CORS。仅通过 JavaScript 创建的字体可能需要显式提供localFonts源CSSOM 不可见。导出格式Export Formats一次捕获结果可以被多次导出而无需重新克隆实时元素。所有导出方法由 src/api/snapdom.js 的buildResult统一构建核心导出器按类型惰性加载导出调用按结果串行排队runExport内部_exportQueueafterSnap在首次成功导出后触发一次。方法返回toRaw()/urlSVG data URLtoSvg()SVG 支撑的HTMLImageElementtoCanvas()HTMLCanvasElementtoBlob()SVGBlob除非捕获或导出显式选择格式toPng()PNGHTMLImageElementtoJpg()/toJpeg()JPEGHTMLImageElementtoWebp()WebPHTMLImageElement浏览器无法编码 WebP 时回退 PNGdownload()下载请求的格式to(name, options?)调用核心或插件导出器静态快捷方式包括snapdom.toPng(element)、snapdom.toCanvas(element)、snapdom.download(element)等它们内部均先执行snapdom(el, options)再调用对应导出方法。toImg()为兼容性保留SVG 图片请使用toSvg()。JPEG 与 WebP 默认白色背景normalizeExportOptions中当无背景色时强制#ffffff。iOS 上下载可使用 Web Share API。重要语义SVG 捕获将 HTML 放在foreignObject内非浏览器 SVG 查看器可能无法渲染。result.meta暴露冻结的捕获几何信息w0/h0/vbW/vbH/targetW/targetH/contentX/contentY用于叠加层与图片定位result.warnings报告捕获诊断如reconcile-risk、shrink-failed。选项系统Options每个公开选项在 src/core/context.js 的createContext中完成归一化——默认值、别名与编译后的排除策略只在此处决定因此新增选项也是从这里开始。尺寸width/height优先于scaledpr乘以像素尺寸。注意 v3 规则width/height是绝对输出尺寸两者任一设置时scale被忽略并给出调试警告。内容filter/filterMode与exclude/excludeMode可同时使用且模式独立clipviewport或页面坐标矩形与captureSelection进一步控制捕获内容。排除优先于过滤shouldExclude中先判 exclude 再判 filter。渲染backgroundColor、quality默认 0.92、outerTransforms、outerShadows、reconcile控制输出。资源字体选项、useProxy、fallbackURL、placeholders控制内联与回退。复用canvas接受现有渲染目标循环捕获时避免整画布拷贝见 #494 的 iframe canvas 处理invalidate在无浏览器信号的更改后刷新。插件系统Plugin System插件可以修改克隆、解析源节点或定义导出器。它们通过snapdom.plugins(...)全局注册或通过plugins选项局部传入。局部插件先运行并按名称覆盖全局插件attachSessionPlugins的 local-first 语义插件导出覆盖核心导出。官方插件输出或效果html-export带内嵌样式与字体的捕获 HTMLcontext-export文本大纲或 JSON 页面上下文agent-map带角色、名称、状态与边界框的图片和元素地图pdf-image含 JPEG 捕获的可下载 PDFgif-export/video-export实时元素随时间变化的录制ascii-export图片的文本表示filter/color-tint/timestamp-overlay对捕获克隆的视觉改变replace-text/redact-inputs文本替换与表单值遮罩官方插件的安装与完整参数见 packages/plugins/README.md如filter的preset、gif-export的fps/duration/maxColors、agent-map的fields/semantic/maxImageWidth等。阶段Stage与needs捕获是一条链element → [clone] → [render] → exports。每个插件声明自己需要走多远needs: clone | render默认render捕获运行到所有附着插件声明的最大深度src/core/stages.js 的resolveStage。声明needs: clone的插件可跳过渲染此时核心图片导出不可用url、toPng()等访问会抛出错误指明是哪些插件降低了阶段——因为重新捕获将返回另一个瞬间的像素克隆本身就是冻结而插件仍可返回自己的数据。全局注册拒绝 clone-only 插件阶段降低只允许 per-capture。未知的needs值会直接抛错而非静默取默认。影响捕获的钩子render 相关会禁用自动记忆化除非插件声明pure: true仅导出型插件保留记忆化。导出调用按结果串行化afterSnap在首次成功导出后触发一次。核心导出在 src/api/snapdom.js 中与插件导出合并插件同名覆盖核心。缓存与记忆化Caching Memoizationv3 的性能核心是burst 记忆化src/core/burst.js符合条件的未变化元素从首次捕获复用结果安全的局部变化可重建受影响子树差异路径diff.js不确定的变化走完整管线。Canvas、video、iframe 与已识别的动画总是新鲜捕获。函数值的filter、exclude、excludeStyleProps、fallbackURL需要新鲜捕获回调可能读取外部状态身份不变也不代表结果不变。适用回调决策包括样式与回退决策在每次新捕获时重新评估改变闭包无需invalidate已返回的结果保留其原始捕获状态。DOM 变更、交互状态、滚动、尺寸变化与资源事件会使相关缓存失效。程序化 CSSOM 编辑如sheet.insertRule()没有变更信号需为下一次捕获传入invalidate: true。资源/样式缓存与结果记忆化相互独立。cache: soft是默认normalizeCachePolicy将遗留的auto、full映射到它cache: disabled或false会清空并绕过持久缓存供调试使用。记忆化引擎维护一个作用域MutationObserver与每元素最近结果缓存采用有界 64 条目的 LRU超出后最久未服务的 memo 被拆除其元素下次新鲜捕获。失效矩阵覆盖 DOM 变更、滚动composed:false 事件、表单控件属性写入、:hover、窗口 resize、headCSS、同 tick 的style、CSS/WAAPI 动画运行中绝不服务也不持久化 memo、以及捕获中途的外部编辑hasTornMutation净效果判定。开放 shadow root 各自配备一个 observer 与局部事件监听因为MutationObserver不跨 shadow 边界。snapdom.preCapture()按意图预准备捕获src/api/preCapture.js它学习在某个控件的 press/click 事件期间开始的合格捕获然后在后续 pointer-enter 或 focus 事件上重复执行。它不接受参数、不轮询页面在掌握任何控件之前首次意图事件会捕获可见视口一次并丢弃用于预热样式快照、字体与图片源码注释记录的实测数据预热后可见元素捕获为稳态的 1.1x冷启动为 3.3x。跨浏览器处理Cross-browser HandlingSafari 的 SVG 图片路径会等待内嵌图片与字体绘制完成才返回栅格结果见 src/api/snapdom.js 中 Safari pre-step等待实际使用的字体就绪并poke GPU 支撑的canvas存储避免toDataURL空白——WebKit #219770。Firefox 表单控件在原生 SVG 渲染不同处使用替代物。编码与 canvas 尺寸限制仍取决于浏览器。SnapDOM 有两个渲染引擎。SVG 是默认引擎src/engines/svg.jsbase reset、bbox 与 bleed 数学、foreignObject 组装、SVG data URL 编码还会对重复内联样式做属性选择器 intern 优化。第二个是html-in-canvas通过浏览器原生 canvas API 绘制同一个完成的克隆以engine: html-in-canvas选择。该引擎仍属实验性质需要兼容浏览器且启用其 canvas 绘图标志构建时需SNAPDOM_CANVAS_ENGINE1包含默认构建仅含 SVG不支持的捕获回退到 SVG。上述导出表描述的是 SVG 捕获。原生画布捕获成功时产生位图url与toRaw()返回 PNG data URLtoSvg()与toImg()返回 PNG 支撑的图片toBlob()默认 PNG显式请求 SVG Blob 会失败因为该引擎不序列化 SVG。位图被延迟 mint首次读取时才编码 PNG避免像素导出付出 15–22 倍的编码成本。节点级控制属性Node-level Control Attributes属性效果data-captureexclude使用所选excludeMode排除节点data-captureplaceholder用占位符替换它data-placeholder-text设置占位符文本data-captureexclude在shouldExcludesrc/core/context.js中优先于一切选择器与谓词判定。SnapDOM 自身的捕获脚手架markInternalNode标记的内部节点如fromString的挂载层与#snapdom-sandbox总是被排除不会出现在任何导出中。实践建议小结安全第一fromString只接受已消毒的 HTMLhtml-export输出保留事件处理属性的原始标记也不做消毒。性能默认burst记忆化与cache: soft开箱即用高频轮询界面直接复用捕获结果。若存在 CSSOM 编辑或关闭的 shadow root使用invalidate: true。忠实度文本换行不确定时启用reconcile: true根阴影与变换按需用outerShadows/outerTransforms控制敏感表单值用redact-inputs插件或data-captureexclude处理。扩展仅需结构化数据时用needs: clone插件如contextExport、agentMap避免无谓渲染但注意此时url与图片导出不可用。相关深入资料插件钩子完整契约见 PLUGIN_SPEC.md官方插件参考见 packages/plugins/README.md架构总览见 ARCHITECTURE.md社区插件贡献指南见 CONTRIBUTING_PLUGINS.md。【免费下载链接】snapdomHigh-performance engine for capturing, modifying, and converting DOM elements into any format.项目地址: https://gitcode.com/GitHub_Trending/sn/snapdom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考