Intégration Lit
Le package @tsparticles/lit fournit un élément personnalisé <lit-particles> construit avec Lit, vous permettant d'utiliser tsParticles de manière déclarative dans tout projet Lit ou page HTML simple.
Installation
npm install @tsparticles/lit tsparticlesLe package est entièrement typé et inclut les modèles de contrôleur réactif de Lit pour mettre à jour de manière réactive les options des particules.
Initialisation du moteur
Appelez initParticlesEngine avant d'enregistrer le composant <lit-particles> ou de l'importer dans votre application. Cela doit se produire exactement une fois.
import { initParticlesEngine } from "@tsparticles/lit";
import { loadFull } from "tsparticles";
void initParticlesEngine(async (engine) => {
await loadFull(engine);
});Pour des tailles de bundle optimisées, importez uniquement les fonctionnalités dont votre projet a besoin :
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);
});Utilisation de base
Après l'initialisation du moteur, utilisez l'élément <lit-particles> dans n'importe quel template Lit ou fichier 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> `;
}
}La syntaxe .options (avec point) est la liaison de propriété Lit, garantissant que l'objet est passé par référence plutôt que sérialisé en attribut.
Utilisation HTML simple
Une fois que @tsparticles/lit est intégré ou chargé, l'élément fonctionne aussi en HTML simple :
<!DOCTYPE html>
<html>
<head>
<script type="module" src="bundle.js"></script>
</head>
<body>
<lit-particles id="tsparticles"></lit-particles>
</body>
</html>Vous pouvez passer un objet d'options minimal comme attribut JSON :
<lit-particles
id="tsparticles"
options='{"background":{"color":"#000"},"particles":{"number":{"value":30}}}'
></lit-particles>Configuration personnalisée
Passez une configuration tsParticles complète comme propriété 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> `;
}
}Gestion des événements
Écoutez l'événement personnalisé particles-loaded émis par l'élément <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("Particules chargées :", container);
container?.refresh();
}
render() {
return html` <lit-particles id="tsparticles" @particles-loaded="${this.handleParticlesLoaded}"> </lit-particles> `;
}
}Exemple TypeScript
Un élément Lit entièrement typé avec initParticlesEngine, options réactives et gestion d'événements :
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("Conteneur prêt :", 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.
Mises à jour dynamiques
Comme <lit-particles> utilise les propriétés réactives de Lit, changer la propriété options met automatiquement à jour les particules :
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}">Passer en ${this.theme === "dark" ? "Clair" : "Sombre"}</button>
<lit-particles id="tsparticles" .options="${this.options}"> </lit-particles>
`;
}
}Le composant surveille la propriété options et appelle refresh() en interne à chaque changement, mettant à jour en continu la configuration des particules à l'exécution.