Lit 集成
@tsparticles/lit 包提供了一个使用 Lit 构建的 <lit-particles> 自定义元素，使你能够在任何 Lit 项目或纯 HTML 页面中声明式地使用 tsParticles。
安装
bash
npm install @tsparticles/lit tsparticles该包完全支持 TypeScript，并包含 Lit 的响应式控制器模式，用于响应式更新粒子选项。
引擎初始化
在注册 <lit-particles> 组件或将其导入应用之前，调用 initParticlesEngine。这必须且只执行一次。
typescript
import { initParticlesEngine } from "@tsparticles/lit";
import { loadFull } from "tsparticles";
void initParticlesEngine(async (engine) => {
await loadFull(engine);
});为优化打包体积，只导入项目所需的功能：
typescript
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 模板或 HTML 文件中使用 <lit-particles> 元素：
typescript
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 中使用：
html
<!DOCTYPE html>
<html>
<head>
<script type="module" src="bundle.js"></script>
</head>
<body>
<lit-particles id="tsparticles"></lit-particles>
</body>
</html>你可以将最小选项对象作为 JSON 属性传递：
html
<lit-particles
id="tsparticles"
options='{"background":{"color":"#000"},"particles":{"number":{"value":30}}}'
></lit-particles>自定义配置
将完整的 tsParticles 配置作为 Lit 属性传递：
typescript
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> `;
}
}事件处理
监听 <lit-particles> 元素触发的 particles-loaded 自定义事件：
typescript
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、响应式选项和事件处理：
typescript
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 属性会自动更新粒子：
typescript
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()，无缝地在运行时更新粒子配置。