파티클 API · Vanilla Disintegrate

이 페이지에서

내장 파티클 렌더러는 루트, /snapdom, /particles 엔트리 포인트에서 사용할 수 있습니다. Disintegrator, 캡처, 내장 오디오 없이 렌더러와 타입만 필요하면 /particles를 가져오세요.

import {
  configureParticleContexts,
  createParticleAnimation,
  createParticleEffect,
  createParticleRestoreAnimation,
  particlePresets,
} from 'vanilla-disintegrate/particles';

`createParticleEffect`(options?)

삭제와 복원 단계를 독립적으로 설정할 수 있는 완전한 EffectDefinition을 만듭니다.

interface ParticleEffectOptions {
  remove?: ParticleOptions;
  restore?: ParticleOptions;
}

const effect = createParticleEffect({
  remove: { ...particlePresets.vapor, release: 'top' },
  restore: { ...particlePresets.scatter, release: 'center' },
});

restore를 생략하면 remove와 같은 설정을 사용합니다. 두 필드를 모두 생략하면 양쪽 단계 모두 파티클 기본값을 사용합니다. 이 팩토리는 시각 효과만 설정합니다. sound를 별도로 추가하거나 효과와 오디오를 완전한 프리셋으로 묶으세요.

`ParticleOptions`

거리와 파티클 크기는 CSS 픽셀, 시간은 밀리초, 회전은 도 단위이며 정규화된 설정은 0–1 범위를 사용합니다.

옵션	타입	기본값	제어 대상
`renderQuality`	`'auto' \| 'exact' \| ParticleRenderBudget`	`'auto'`	WebGL 렌더러의 해상도와 리소스 제한
`particleSize`	`'auto' \| number`	`'auto'`	파티클 한 변의 최소 길이. 숫자는 최소 `0.25`로 제한됨
`alphaThreshold`	`number`	`0`	이 알파 값 이하의 원본 픽셀은 파티클을 만들지 않음
`curve`	`'settle' \| 'float' \| 'burst' \| 'drift'`	`'settle'`	이동, 가속 및 복원 프로필
`duration`	`number`	`720`	단계의 기본 재생 시간
`stagger`	`number`	`180`	파티클 사이에 분산되는 최대 추가 시작 지연
`release`	`'left' \| 'right' \| 'top' \| 'bottom' \| 'center' \| 'edges' \| 'random'`	`'left'`	요소에서 파티클이 먼저 방출되는 영역
`releaseRandomness`	`number`	`0.22`	선택한 방출 순서(`0`)와 무작위 순서(`1`)의 혼합 비율
`fadeStart`	`number`	`curve`에 따라 다름	각 파티클의 수명 중 페이드가 시작되는 시점
`layoutRelease`	`number`	`0.6`	주변 레이아웃이 움직이기 전에 방출되어야 하는 파티클 비율
`horizontalDrift`	`number`	`42`	각 경로에 더해지는 무작위 가로 편차
`horizontalTravel`	`readonly [number, number]`	`[0, 0]`	방향성 가로 이동의 최솟값과 최댓값
`verticalTravel`	`readonly [number, number]`	`[-100, -45]`	세로 이동의 최솟값과 최댓값. 음수는 위쪽 이동
`convergence`	`number`	`0`	요소의 가로 중앙으로 끌어당기는 정도
`swirl`	`number`	`0`	경로를 따라 생기는 세로 파동의 진폭
`waveTurns`	`number`	`curve`에 따라 다름	경로를 따라 발생하는 진동 횟수
`endScale`	`number`	`0.92`	삭제가 끝날 때의 파티클 크기 비율
`rotation`	`readonly [number, number]`	`[0, 0]`	파티클에 지정되는 최종 회전의 최솟값과 최댓값

alphaThreshold, convergence, releaseRandomness, fadeStart, layoutRelease는 0–1로 제한됩니다. 음수인 duration, stagger, horizontalDrift, swirl, waveTurns, endScale은 0으로 제한됩니다. 범위의 두 끝값이 반대로 주어지면 자동으로 정렬됩니다.

커브

커브	특성	기본 `fadeStart`	기본 `waveTurns`
`settle`	균형 잡힌 움직임과 부드러운 마무리	`0.3`	`1`
`float`	더 부드러운 부유 움직임	`0.3`	`1.6`
`burst`	더 빠른 초기 가속	`0.12`	`1`
`drift`	긴 방향성 움직임	`0.32`	`1.25`

fadeStart와 waveTurns를 직접 지정하면 커브 기본값보다 우선합니다.

방출 순서

left, right, top, bottom은 해당 가장자리부터 파티클을 방출합니다. center는 중앙에서 바깥쪽으로, edges는 바깥 가장자리에서 안쪽으로 진행합니다. random에는 기하학적 순서가 없습니다. releaseRandomness를 사용하면 선택한 방향을 바꾸지 않고도 정렬된 패턴에 무작위성을 섞을 수 있습니다.

레이아웃 전환

layoutRelease는 삭제 중 DOM 리플로 애니메이션이 시작되는 시점을 정합니다. 0이면 레이아웃이 즉시 움직일 수 있고, 1이면 모든 파티클이 방출될 때까지 기다립니다. 렌더러는 생성된 파티클 필드에서 실제 layoutDelay를 계산하므로 release 및 releaseRandomness와 동기화됩니다.

렌더링 품질

type ParticleRenderQuality = 'auto' | 'exact' | ParticleRenderBudget;

interface ParticleRenderBudget {
  maxSourcePixels: number;
  maxSourceDimension: number;
  maxRenderPixels: number;
}

auto는 다음 소프트웨어 제한을 사용합니다.

{
  maxSourcePixels: 2_000_000,
  maxSourceDimension: 2048,
  maxRenderPixels: 4_000_000,
}

exact는 캡처의 전체 해상도를 유지하고 소프트웨어 다운스케일링을 끕니다. 장치의 WebGL 텍스처 또는 뷰포트 제한을 넘을 수는 없으며, 지원할 수 없는 표면은 onError로 보고됩니다. 사용자 지정 예산을 사용하면 선명도, 메모리, GPU 작업량 사이의 균형을 애플리케이션이 직접 정할 수 있습니다.

renderQuality는 WebGL 렌더러에만 영향을 줍니다. 원본 canvas의 픽셀 수는 캡처 어댑터가 별도로 결정합니다.

저수준 단계 팩토리

function createParticleAnimation(options?: ParticleOptions): AnimationFactory;
function createParticleRestoreAnimation(options?: ParticleOptions): AnimationFactory;

createParticleAnimation()은 삭제 단계 애니메이션 팩토리를 만들고, createParticleRestoreAnimation()은 대응하는 복원 단계 팩토리를 만듭니다. EffectDefinition을 직접 조합할 때 사용하세요. 두 단계 모두 내장 렌더러를 사용한다면 createParticleEffect()가 더 적합합니다.

두 팩토리 모두 스냅샷이 필요합니다. AnimationContext.snapshot이 null이면 null을 반환하며, 작업은 일반적인 애니메이션 건너뛰기 대체 경로를 따릅니다.

`particlePresets`

type BuiltInPreset = 'dust' | 'scatter' | 'vapor' | 'wind';

const particlePresets: Readonly<Record<BuiltInPreset, Readonly<ParticlePreset>>>;

particlePresets에는 깊게 동결된 시각 설정만 들어 있습니다. 오디오는 포함하지 않으며 createParticleEffect() 또는 저수준 팩토리용입니다. 루트와 /snapdom 엔트리에서 내보내는 builtInPresets는 Disintegrator를 위한 완전한 시각·오디오 프리셋입니다.

`configureParticleContexts`(limits?)

interface ParticleContextLimits {
  maxContexts?: number;
  maxIdleContexts?: number;
}

const applied = configureParticleContexts({
  maxContexts: 2,
  maxIdleContexts: 1,
});

이 설정은 페이지 전체에 적용되며 일반적으로 효과가 시작되기 전에 한 번 지정해야 합니다. 기본적으로 최대 네 개의 활성 WebGL2 컨텍스트와 재사용을 위한 최대 두 개의 유휴 컨텍스트를 유지합니다. 유휴 컨텍스트는 30초 후 해제되고, 유휴 제한을 넘는 컨텍스트는 즉시 해제됩니다.

maxContexts는 최소 1인 정수로 정규화됩니다. maxIdleContexts는 음수가 아닌 정수로 정규화되며 maxContexts를 넘을 수 없습니다. 함수는 현재 적용된 제한을 반환합니다.

렌더러가 컨텍스트를 얻지 못해도 DOM 작업은 커밋되고, finished는 status: 'skipped'로 완료되며, 실패는 onError로 전달됩니다.

GitHub에서 이 페이지 편집

createParticleEffect(options?)

ParticleOptions

커브