설치와 첫 번째 효과

Vanilla Disintegrate는 측정 가능한 모든 DOM 요소를 삭제하고 복원할 때 익숙한 타노스 스냅 효과를 재현합니다.

설치

지원되는 패키지 관리자 중 하나를 사용하세요.

# 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-shaking 가능한 다섯 개의 진입점을 제공합니다.

기본 진입점과 /snapdom은 같은 Disintegrator API를 내보냅니다. 모든 인스턴스는 정확히 하나의 완성된 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를 await 하세요.

같은 노드 삭제 후 복원

원본 노드가 다시 필요할 수 있을 때만 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> 또는 그 promise를 반환하는 함수입니다. 이렇게 동작하는 라이브러리라면 무엇이든 쓸 수 있습니다. 예를 들어 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를 가져오세요. 필수 런타임 의존성이 없습니다. @zumer/snapdom은 /snapdom 진입점에서만 사용하는 선택적 peer 의존성이므로 여기서는 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()를 호출하세요. 실행 중인 작업과 observer를 중지하고 스냅샷 및 보관된 DOM 참조를 해제합니다.

effects.destroy();