Установка и первый эффект

Установка

Используйте любой поддерживаемый пакетный менеджер:

# 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

Библиотека снимает внешний вид элемента до распада на частицы, а движок захвата выбираете вы. Пакет содержит пять tree-shakable точек входа:

Корневой вход и /snapdom экспортируют одинаковый API Disintegrator. Каждый экземпляр обязан получить ровно один полный preset или один пользовательский effect; неявного значения по умолчанию нет.

/core экспортирует Disintegrator, defineEffect, definePreset и публичные типы. /particles экспортирует createParticleEffect, particlePresets, обе фабрики анимации частиц и их типы, но не создаёт экземпляр. Так можно вручную собрать только нужные слои. В примере встроенная геометрия используется как бесшумный пользовательский эффект, а captureElement обозначает адаптер из следующего раздела:

import Disintegrator from 'vanilla-disintegrate/core';
import { createParticleEffect, particlePresets } from 'vanilla-disintegrate/particles';

const effects = new Disintegrator({
  capture: captureElement,
  effect: createParticleEffect({ remove: particlePresets.dust }),
});

Для самого короткого подключения импортируйте /snapdom и выберите один полный пресет:

import Disintegrator from 'vanilla-disintegrate/snapdom';

const effects = new Disintegrator({ preset: 'dust' });
const card = document.querySelector<HTMLElement>('.card');

if (card) {
  effects.remove(card);
}

remove() сразу возвращает объект операции. Ожидайте operation.finished, только если следующему действию нужно дождаться конца визуального эффекта.

Удаление с возможностью восстановить узел

Задавайте retain: true, только если исходный узел может понадобиться снова. Место повторной вставки по-прежнему выбирает приложение.

const removal = effects.remove(card, {
  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() не передан другой preset или пользовательский effect, библиотека использует полную конфигурацию, запомненную при удалении.

Другой движок захвата

capture — функция: принимает элемент, возвращает <canvas> или промис с ним. Подойдёт любая библиотека, которая это умеет, например html2canvas:

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

const effects = new Disintegrator({
  preset: 'dust',
  capture: (element, context) => {
    if (context.signal.aborted) throw new DOMException('Capture aborted.', 'AbortError');

    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: у него нет обязательных runtime-зависимостей. @zumer/snapdom — необязательная peer-зависимость, которая нужна только входу /snapdom, поэтому здесь SnapDOM не попадёт в граф модулей.

Контекст адаптера, контракт отмены и значения createSnapdomCapture() по умолчанию описаны в API захвата.

Подключение локально или через CDN

Если нужно быстро интегрировать Vanilla Disintegrate без сборщика или пакетного менеджера, подключите библиотеку через CDN либо скачайте архив с актуальной версией для локального использования.

IIFE-сборка уже содержит SnapDOM и создаёт глобальный объект VanillaDisintegrate:

<script src="https://cdn.jsdelivr.net/npm/vanilla-disintegrate@latest/dist/vanilla-disintegrate.iife.min.js"></script>
<script>
  const effects = new VanillaDisintegrate.Disintegrator({ preset: 'dust' });
  effects.remove(document.querySelector('.card'));
</script>

В архиве уже находятся минимальный index.html, IIFE-сборка, лицензии и все встроенные звуки. Запускайте распакованный каталог через локальный HTTP-сервер, чтобы браузер мог загрузить аудио. Если копируете IIFE вручную, оставьте каталог sounds рядом со скриптом; CDN-версия найдёт соответствующие ресурсы автоматически.

Очистка

Когда владеющий экран окончательно уничтожен, вызовите effects.destroy(). Метод остановит операции, фоновые задачи и observers, освободит снимки и все сохранённые DOM-ссылки.

effects.destroy();