API частиц

Встроенный рендерер частиц доступен из корневого entry point, /snapdom и /particles. Импортируйте /particles, когда нужен только рендерер и его типы — без Disintegrator, захвата и встроенного аудио.

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.

alphaThreshold, convergence, releaseRandomness, fadeStart и layoutRelease ограничиваются диапазоном 0–1. Отрицательные duration, stagger, horizontalDrift, swirl, waveTurns и endScale приводятся к нулю. Границы диапазона в обратном порядке автоматически сортируются.

Кривые

Явно заданные 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 сохраняет полное разрешение снимка и отключает программное уменьшение. Режим не может превысить ограничения устройства на текстуру или viewport WebGL; неподдерживаемая поверхность сообщается через onError. Пользовательский бюджет позволяет приложению самостоятельно выбрать баланс между чёткостью, памятью и работой GPU.

renderQuality влияет только на WebGL-рендерер. Количество пикселей в исходном canvas независимо определяет адаптер захвата.

Низкоуровневые фабрики фаз

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

createParticleAnimation() создаёт фабрику анимации удаления, а createParticleRestoreAnimation() — соответствующую фабрику восстановления. Используйте их при ручной сборке EffectDefinition; если обе фазы работают на встроенном рендерере, удобнее createParticleEffect().

Обе фабрики требуют снимок. Если AnimationContext.snapshot равен null, они возвращают null: при настроенном fallback операция попробует его, иначе пропустит анимацию.

particlePresets

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

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

particlePresets содержит только глубоко замороженные визуальные конфигурации. В них нет аудио: они предназначены для createParticleEffect() или низкоуровневых фабрик. Экспортируемые корневым entry point и /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 всё равно выполняется. При настроенном fallback запустится он; иначе finished завершается со status: 'skipped', а ошибка передаётся в onError.