Интеграция с Lit
Пакет @tsparticles/lit предоставляет пользовательский элемент <lit-particles>, созданный с помощью Lit, позволяющий использовать tsParticles декларативно в любом проекте на Lit или на простой HTML-странице.
Установка
npm install @tsparticles/lit tsparticlesПакет полностью типизирован и включает реактивные контроллеры Lit для реактивного обновления опций частиц.
Инициализация движка
Вызовите initParticlesEngine перед регистрацией компонента <lit-particles> или импортом его в ваше приложение. Это должно произойти ровно один раз.
import { initParticlesEngine } from "@tsparticles/lit";
import { loadFull } from "tsparticles";
void initParticlesEngine(async (engine) => {
await loadFull(engine);
});Для оптимизации размера сборки импортируйте только те функции, которые нужны вашему проекту:
import { initParticlesEngine } from "@tsparticles/lit";
import { loadBasic } from "@tsparticles/basic";
import { loadConfettiPreset } from "@tsparticles/preset-confetti";
void initParticlesEngine(async (engine) => {
await loadBasic(engine);
await loadConfettiPreset(engine);
});Базовое использование
После инициализации движка используйте элемент <lit-particles> в любом шаблоне Lit или HTML-файле:
import { LitElement, html } from "lit";
import { customElement } from "lit/decorators.js";
import "@tsparticles/lit";
@customElement("my-app")
class MyApp extends LitElement {
private options = {
background: {
color: "#0d1117",
},
particles: {
number: { value: 60 },
color: { value: "#58a6ff" },
links: {
enable: true,
color: "#58a6ff",
},
move: { enable: true, speed: 2 },
},
};
render() {
return html` <lit-particles id="tsparticles" .options="${this.options}"> </lit-particles> `;
}
}Синтаксис .options (с точкой) — это привязка свойства Lit, гарантирующая, что объект передаётся по ссылке, а не сериализуется как атрибут.
Использование в простом HTML
После сборки или загрузки @tsparticles/lit элемент работает и в простом HTML:
<!DOCTYPE html>
<html>
<head>
<script type="module" src="bundle.js"></script>
</head>
<body>
<lit-particles id="tsparticles"></lit-particles>
</body>
</html>Вы можете передать минимальный объект опций как JSON-атрибут:
<lit-particles
id="tsparticles"
options='{"background":{"color":"#000"},"particles":{"number":{"value":30}}}'
></lit-particles>Пользовательская конфигурация
Передайте полную конфигурацию tsParticles как свойство Lit:
import { LitElement, html } from "lit";
import { customElement, property } from "lit/decorators.js";
import type { ISourceOptions } from "@tsparticles/engine";
import "@tsparticles/lit";
@customElement("my-particles")
class MyParticles extends LitElement {
@property({ type: Object })
options: ISourceOptions = {
background: {
color: "#0d1117",
},
fpsLimit: 120,
fullScreen: {
enable: true,
zIndex: -1,
},
particles: {
color: {
value: ["#ff5733", "#33ff57", "#3357ff"],
},
links: {
color: "#ffffff",
enable: true,
opacity: 0.3,
distance: 150,
},
move: {
enable: true,
speed: 1.5,
direction: "none",
random: true,
},
number: {
value: 100,
density: {
enable: true,
},
},
opacity: {
value: 0.6,
animation: {
enable: true,
speed: 0.5,
minimumValue: 0.1,
},
},
size: {
value: { min: 1, max: 5 },
animation: {
enable: true,
speed: 2,
minimumValue: 1,
},
},
},
interactivity: {
events: {
onHover: {
enable: true,
mode: "grab",
},
onClick: {
enable: true,
mode: "push",
},
},
modes: {
grab: {
distance: 180,
links: {
opacity: 0.5,
},
},
push: {
quantity: 4,
},
},
},
};
render() {
return html` <lit-particles id="tsparticles" .options="${this.options}"> </lit-particles> `;
}
}Обработка событий
Слушайте пользовательское событие particles-loaded, которое генерируется элементом <lit-particles>:
import { LitElement, html } from "lit";
import { customElement } from "lit/decorators.js";
import type { Container } from "@tsparticles/engine";
import "@tsparticles/lit";
@customElement("my-app")
class MyApp extends LitElement {
private handleParticlesLoaded(e: CustomEvent<Container>) {
const container = e.detail;
console.log("Частицы загружены:", container);
container?.refresh();
}
render() {
return html` <lit-particles id="tsparticles" @particles-loaded="${this.handleParticlesLoaded}"> </lit-particles> `;
}
}Пример на TypeScript
Полностью типизированный элемент Lit с initParticlesEngine, реактивными опциями и обработкой событий:
import { LitElement, html } from "lit";
import { customElement, property } from "lit/decorators.js";
import { initParticlesEngine } from "@tsparticles/lit";
import type { Container, ISourceOptions } from "@tsparticles/engine";
import { loadFull } from "tsparticles";
import "@tsparticles/lit";
void initParticlesEngine(async (engine) => {
await loadFull(engine);
});
@customElement("particles-background")
class ParticlesBackground extends LitElement {
@property({ type: Object })
options: ISourceOptions = {};
@property({ type: Boolean, attribute: "fullscreen" })
fullscreen = true;
protected onParticlesLoaded(e: CustomEvent<Container>) {
console.log("Контейнер готов:", e.detail.id);
}
render() {
return html`
<lit-particles
id="particles-bg"
.options="${this.options}"
?fullScreen="${this.fullscreen}"
@particles-loaded="${this.onParticlesLoaded}"
>
</lit-particles>
`;
}
}Reactive Behavior
The <Particles> component reacts to prop changes at runtime:
id,options, orurlchange → the existing container is destroyed and particles are reloaded with the new values.themechange →loadThemeis called on the existing container. This requires the optional@tsparticles/plugin-themespackage to be loaded (otherwise it is a safe no-op).
On component unmount, the particles container is automatically destroyed — no orphan animations remain.
Динамические обновления
Поскольку <lit-particles> использует реактивные свойства Lit, изменение свойства options автоматически обновляет частицы:
import { LitElement, html } from "lit";
import { customElement, state } from "lit/decorators.js";
import type { ISourceOptions } from "@tsparticles/engine";
import "@tsparticles/lit";
@customElement("dynamic-particles")
class DynamicParticles extends LitElement {
@state()
private theme: "light" | "dark" = "dark";
private get options(): ISourceOptions {
return this.theme === "dark"
? {
background: { color: "#0d1117" },
particles: { color: { value: "#58a6ff" } },
}
: {
background: { color: "#ffffff" },
particles: { color: { value: "#0969da" } },
};
}
private toggleTheme() {
this.theme = this.theme === "dark" ? "light" : "dark";
}
render() {
return html`
<button @click="${this.toggleTheme}">Переключить на ${this.theme === "dark" ? "светлую" : "тёмную"}</button>
<lit-particles id="tsparticles" .options="${this.options}"> </lit-particles>
`;
}
}Компонент отслеживает свойство options и вызывает refresh() внутри при каждом его изменении, плавно обновляя конфигурацию частиц во время выполнения.