限制与注意事项

Vanilla Disintegrate 基于浏览器 API 运行，无法保证所有 DOM 内容、浏览器和设备都产生完全一致的结果。选择效果和调整性能时，需要考虑以下限制。

快照并非 DOM 的逐像素副本

内置粒子效果操作的是元素的 Canvas 快照，而不是真实的 DOM 节点。截至 2026 年，Web 平台仍未提供稳定且受到广泛支持的 API，来直接复制单个 DOM 元素已经渲染完成的像素。因此，捕获引擎必须重新构建元素的外观。

vanilla-disintegrate/snapdom 入口使用 SnapDOM。它把元素的内容与样式转移到 SVG 中，再由浏览器转换为 Canvas。再次光栅化的结果可能在以下方面与原始 DOM 不同：

• 文本抗锯齿和字重；
• 边缘的亚像素位置；
• 阴影、滤镜、蒙版和变换；
• 非默认页面缩放比例或小数 devicePixelRatio 下的结果；
• 不同浏览器引擎中的表现。

在卡片、图片和其他大型元素的动画中，这些差异通常几乎无法察觉；但对于单个字形、细线以及其他要求逐像素精度的内容，差异可能比较明显。

renderQuality: 'exact' 的作用

exact 模式会关闭粒子渲染器内部的自适应降分辨率。它有助于保留现有快照中的细节，但不会提高 DOM 快照本身的准确度，也无法修正文本光栅化的差异。

换句话说，exact 控制的是后续渲染质量，而不是原始捕获的准确度。

可以替换捕获引擎

IIFE 构建使用 SnapDOM 作为现成的捕获适配器。性能是选择它时的考虑因素之一：截至 2026 年，项目发布的对比基准测试显示，它在捕获不同复杂度的 DOM 元素时具有较低的延迟。实际速度取决于内容、浏览器和设备，捕获方式也无法消除浏览器光栅化的限制。

capture 选项接受任何能够返回 <canvas> 的适配器，因此项目可以使用其他引擎或自行实现捕获逻辑。完整适配器契约请参阅捕获 API。

不过，无论 SnapDOM 还是当时可用的其他 DOM-to-Canvas 方案，都无法保证对所有内容实现逐像素一致。不同引擎处理文本、图片、SVG、表单控件、伪元素和浏览器效果的方式各不相同。

动态内容

快照记录的是元素在特定时刻的状态。 捕获后发生的 DOM、样式、尺寸或已加载资源变化不会反映在该快照中。

捕获元素之前，建议等待：

• 所用字体完成加载；
• 图片完成解码；
• 过渡和临时动画结束；
• 元素的最终尺寸计算完成。

预先准备快照可以让首次效果更快启动，但元素变化后，缓存的快照可能会过期。默认情况下，库会在尺寸变化时使缓存失效，但不会观察整个 DOM 子树。内容发生重要变化后，请调用 invalidate()；只有在额外的观察开销可以接受时，才启用 observeMutations。

WebGL2 限制

只有内置粒子效果需要 WebGL2。 库的核心和自定义效果可以使用 Web Animations API、Canvas 2D、CSS 或自定义渲染器。

如果 WebGL2 不可用，或者浏览器无法创建上下文，DOM 操作仍然会执行，但视觉效果会以 skipped 状态结束，并通过 onError 传出原因。

每个并发运行的内置效果都使用一个 WebGL2 上下文。效果结束后，库会复用上下文并限制共享池的大小；但浏览器、GPU 或驱动程序可能设置更严格的上限。

性能开销

对于常见的界面元素和少量并发效果，现代设备上的负载持续时间很短，通常几乎无法察觉。CPU 参与创建快照，内置粒子动画则通过 WebGL2 在 GPU 上运行。操作结束后，临时纹理会被删除，WebGL2 上下文会返回容量受限的资源池中复用。

捕获大型元素、使用高像素密度、同时运行大量效果或启用 exact 模式时，开销会更加明显。**auto 模式适用于包括低性能设备在内的大多数界面：**它会限制工作分辨率。exact 应仅用于额外清晰度确实可见的小型元素。

浏览器支持

运行时以 ES2020 格式输出，并依赖 Canvas、Web Animations API（Animation.finished 和 Element.getAnimations()）、AbortController 以及 requestAnimationFrame。内置预设还需要 WebGL2。

库中不包含 polyfill。这些版本定义的是 API 兼容性的最低基线，但不保证所有 GPU、驱动程序或浏览器设置都允许创建 WebGL2 上下文。

浏览器受支持也不代表不同渲染引擎、页面缩放比例和设备能够生成完全一致的 DOM 快照。

只在浏览器中创建 Disintegrator，不要在服务端渲染期间创建。跨域图片、字体与样式表必须允许 CORS，或通过捕获适配器的代理选项加载，否则可能不会出现在 Canvas 快照中。

实践建议

为了获得最自然的过渡效果：

• 优先为完整元素和区块添加动画，而不是单个字形；
• 在所有目标浏览器中检查结果；
• 仅在确有必要时使用 exact；
• 捕获期间不要更改元素内容；
• 分别测试视频、<iframe>、Canvas、WebGL 和跨域资源；
• 必要时提供专用的 capture 适配器。