安装并运行第一个效果

Vanilla Disintegrate 为任意可测量的 DOM 元素添加 灭霸响指粒子删除效果。入口 vanilla-disintegrate/snapdom 已接好 SnapDOM 截图，且不需要导入 CSS。

安装

使用任意受支持的包管理器：

# npm
npm install vanilla-disintegrate @zumer/snapdom

# Yarn
yarn add vanilla-disintegrate @zumer/snapdom

# pnpm
pnpm add vanilla-disintegrate @zumer/snapdom

# Bun
bun add vanilla-disintegrate @zumer/snapdom

库会在元素碎裂前捕获其当前外观，而截图库由你选择。包提供两个入口：

入口	内容	依赖
vanilla-disintegrate	核心：效果、生命周期、布局、声音。capture 由你提供。	无
vanilla-disintegrate/snapdom	相同 API，并以 SnapDOM 作为默认 capture。	@zumer/snapdom

两个入口导出完全相同的 Disintegrator API。@zumer/snapdom 是可选 peer 依赖：只有使用 /snapdom 入口时才需要安装，核心入口永远不会引用它。

import Disintegrator from 'vanilla-disintegrate/snapdom';

const effects = new Disintegrator();
const card = document.querySelector<HTMLElement>('.card');

if (card) {
  effects.remove(card, { effect: 'dust' });
}

remove() 会立即返回操作对象；只有后续逻辑必须等待动画结束时，才需要等待 operation.finished。

删除并恢复同一个节点

const removal = effects.remove(card, {
  effect: 'dust',
  retain: true,
});

await removal.finished;

if (removal.removalId) {
  const retained = effects.take(removal.removalId);

  if (retained) {
    list.append(retained);
    await effects.restore(retained).finished;
  }
}

应用负责决定节点插入位置。若 restore() 未指定新效果，将使用删除时记住的效果对。

使用其他捕获库

capture 是开放的适配器接口。例如可以接入 html2canvas：

import html2canvas from 'html2canvas';
import Disintegrator from 'vanilla-disintegrate';

const effects = new Disintegrator({
  capture: (element, context) => {
    context.signal.throwIfAborted();

    return html2canvas(element, {
      backgroundColor: null,
      logging: false,
      scale: 1,
      useCORS: true,
      onclone: (_document, clone) => {
        if (context.restoreRootOpacity !== undefined) {
          clone.style.setProperty('opacity', context.restoreRootOpacity, 'important');
        }
      },
    });
  },
});

传入的函数会完全替代截图行为。此路径请导入核心入口 vanilla-disintegrate：它没有运行时依赖，SnapDOM 也不会进入模块图。

清理

所属页面永久销毁时调用 effects.destroy()。它会停止操作和观察器，并释放快照与所有保留的 DOM 引用。

浏览器支持

核心需要 ES2020 产物、Canvas、Web Animations、AbortController 与 requestAnimationFrame。四种内置效果使用 WebGL2 绘制粒子，因此基线为：Chrome 80+、Firefox 74+、Edge 80+、Opera 67+ 与 Safari 15+。

在缺少 WebGL2 或无法创建上下文时，内置效果会降级而不是报错：remove() 仍会移除元素，restore() 仍会显示元素，操作以 skipped 状态结束，原因通过 onError 传出。基于 WAAPI、CSS 或 Canvas 2D 的自定义效果在旧引擎上照常播放。

每个运行中的内置效果只占用一个 WebGL2 上下文，并在操作结束时立即释放，因此删除长列表也不会触及浏览器的每页上下文上限。