Интеграция с Astro

Используйте tsParticles на своём сайте Astro с официальным интеграционным пакетом @tsparticles/astro.

Установка

Установите интеграцию Astro и ядро tsParticles через ваш менеджер пакетов:

npm install @tsparticles/astro tsparticles

pnpm add @tsparticles/astro tsparticles

yarn add @tsparticles/astro tsparticles

Инициализация движка

tsParticles использует модульную архитектуру. Перед рендерингом частиц необходимо инициализировать движок с нужными вам функциями. Создайте клиентский скрипт (например, src/scripts/particles-init.ts) или используйте встроенный <script> в вашем компоненте Astro:

import { initParticlesEngine } from "@tsparticles/astro";

void initParticlesEngine(async (engine) => {
  const { loadFull } = await import("tsparticles");
  await loadFull(engine);
});

initParticlesEngine — это обёртка вокруг tsParticles.init(), которая гарантирует готовность движка до монтирования компонента <Particles>. Она возвращает Promise, который разрешается после завершения инициализации.

Базовое использование

Разместите компонент <Particles /> в любом шаблоне .astro. Передайте конфигурацию через проп options:

---
import Particles from "@tsparticles/astro";
import type { ISourceOptions } from "@tsparticles/engine";

const options: ISourceOptions = {
  background: {
    color: "#000000",
  },
  particles: {
    number: { value: 80 },
    links: { enable: true, color: "#ffffff" },
    move: { enable: true, speed: 2 },
  },
};
---

<Particles id="tsparticles" options={options} />

<script>
  import { initParticlesEngine } from "@tsparticles/astro";

  void initParticlesEngine(async (engine) => {
    const { loadFull } = await import("tsparticles");
    await loadFull(engine);
  });
</script>

Проп id передаётся базовому контейнеру <div> canvas. Используйте его для стилизации или императивного доступа через document.getElementById().

Поддержка TypeScript

Интеграция поставляется с полными объявлениями TypeScript. Используйте ISourceOptions из @tsparticles/engine для типизации конфигурации:

import type { ISourceOptions } from "@tsparticles/engine";

const options: ISourceOptions = {
  background: { color: "#0d47a1" },
  fpsLimit: 60,
  particles: {
    color: {
      value: ["#ff0000", "#00ff00", "#0000ff"],
    },
    move: {
      enable: true,
      speed: 3,
      outModes: "bounce",
    },
    number: {
      value: 50,
      density: { enable: true },
    },
    opacity: { value: 0.5 },
    shape: { type: "circle" },
    size: { value: { min: 2, max: 6 } },
  },
  interactivity: {
    events: {
      onHover: { enable: true, mode: "repulse" },
    },
    modes: {
      repulse: { distance: 200 },
    },
  },
};

Пользовательская конфигурация

Ниже представлена более детальная конфигурация, которую можно вставить на любую страницу Astro:

---
import Particles from "@tsparticles/astro";
import type { ISourceOptions } from "@tsparticles/engine";

const options: ISourceOptions = {
  autoPlay: true,
  background: {
    color: "#0d47a1",
    image: "",
    position: "50% 50%",
    repeat: "no-repeat",
    size: "cover",
  },
  backgroundMode: {
    enable: true,
    zIndex: -1,
  },
  fpsLimit: 120,
  particles: {
    color: {
      value: "#ffffff",
      animation: {
        enable: true,
        speed: 20,
        sync: false,
      },
    },
    links: {
      enable: true,
      distance: 150,
      color: "#ffffff",
      opacity: 0.4,
      width: 1,
      triangles: {
        enable: true,
        opacity: 0.1,
      },
    },
    move: {
      enable: true,
      speed: 3,
      direction: "none",
      random: true,
      straight: false,
      outModes: "out",
      attract: { enable: false },
    },
    number: {
      value: 80,
      density: {
        enable: true,
      },
    },
    opacity: {
      value: 0.5,
      animation: {
        enable: true,
        speed: 1,
        sync: false,
      },
    },
    shape: {
      type: "circle",
    },
    size: {
      value: { min: 1, max: 5 },
      animation: {
        enable: true,
        speed: 3,
        sync: false,
      },
    },
  },
  interactivity: {
    events: {
      onHover: {
        enable: true,
        mode: "grab",
      },
      onClick: {
        enable: true,
        mode: "push",
      },
      resize: true,
    },
    modes: {
      grab: {
        distance: 200,
        links: { opacity: 0.5 },
      },
      push: { quantity: 4 },
    },
  },
  detectRetina: true,
};
---

<Particles id="tsparticles" options={options} />

<script>
  import { initParticlesEngine } from "@tsparticles/astro";

  void initParticlesEngine(async (engine) => {
    const { loadFull } = await import("tsparticles");
    await loadFull(engine);
  });
</script>

Использование пресетов

Вместо ручного создания конфигурации загрузите пресет во время инициализации движка и укажите его в опциях:

---
import Particles from "@tsparticles/astro";
import type { ISourceOptions } from "@tsparticles/engine";

const options: ISourceOptions = {
  preset: "stars",
  background: { color: "#000000" },
};
---

<Particles id="tsparticles" options={options} />

<script>
  import { initParticlesEngine } from "@tsparticles/astro";

  void initParticlesEngine(async (engine) => {
    const { loadStarsPreset } = await import("tsparticles-preset-stars");
    await loadStarsPreset(engine);
  });
</script>

Интеграция с другими фреймворками

Поскольку Astro поддерживает UI-фреймворки, такие как React, Vue, Svelte и Solid, вы можете использовать фреймворк-специфичный компонент tsParticles внутри файлов .astro:

React в Astro

---
import Particles from "@tsparticles/react";
import type { ISourceOptions } from "@tsparticles/engine";

const options: ISourceOptions = {
  background: { color: "#000" },
  particles: {
    number: { value: 60 },
    links: { enable: true },
    move: { enable: true },
  },
};
---

<Particles client:load id="tsparticles" options={options} />

Vue в Astro

---
import Particles from "@tsparticles/vue3";
import type { ISourceOptions } from "@tsparticles/engine";

const options: ISourceOptions = {
  background: { color: "#000" },
  particles: {
    number: { value: 60 },
    links: { enable: true },
    move: { enable: true },
  },
};
---

<Particles client:load id="tsparticles" :options="options" />

Директива client:load указывает Astro гидратировать компонент сразу после загрузки страницы. Используйте client:visible для отложенной загрузки.

Полный пример страницы

Полная страница Astro с частицами в качестве анимированного фона:

---
import Layout from "../layouts/Layout.astro";
import Particles from "@tsparticles/astro";
import type { ISourceOptions } from "@tsparticles/engine";

const options: ISourceOptions = {
  background: { color: "#0d47a1" },
  fpsLimit: 60,
  particles: {
    number: { value: 100 },
    color: { value: "#ffffff" },
    links: {
      enable: true,
      distance: 150,
      color: "#ffffff",
      opacity: 0.4,
    },
    move: {
      enable: true,
      speed: 2,
      outModes: "out",
    },
    size: {
      value: { min: 1, max: 4 },
    },
  },
  interactivity: {
    events: {
      onHover: { enable: true, mode: "grab" },
      onClick: { enable: true, mode: "push" },
    },
    modes: {
      grab: { distance: 200, links: { opacity: 0.5 } },
      push: { quantity: 4 },
    },
  },
};
---

<Layout title="Фон с частицами">
  <main>
    <h1>Добро пожаловать</h1>
    <p>Эта страница имеет фон с частицами на базе tsParticles.</p>
  </main>
  <Particles id="bg-particles" options={options} />
</Layout>

<style is:global>
  #bg-particles {
    position: fixed;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
    z-index: -1;
  }
  main {
    position: relative;
    z-index: 1;
    color: white;
    text-align: center;
    padding-top: 20vh;
  }
</style>

<script>
  import { initParticlesEngine } from "@tsparticles/astro";

  void initParticlesEngine(async (engine) => {
    const { loadFull } = await import("tsparticles");
    await loadFull(engine);
  });
</script>

Reactive Behavior

The <Particles> component reacts to prop changes at runtime:

• id, options, or url change → the existing container is destroyed and particles are reloaded with the new values.
• theme change → loadTheme is called on the existing container. This requires the optional @tsparticles/plugin-themes package to be loaded (otherwise it is a safe no-op).

On component unmount, the particles container is automatically destroyed — no orphan animations remain.

Свойства компонента

Свойство	Тип	По умолчанию	Описание
id	string	"tsparticles"	ID DOM-элемента для контейнера
options	ISourceOptions	{}	Полный объект конфигурации tsParticles
url	string	—	Загрузить конфигурацию из удалённого JSON URL
particlesClassName	string	"tsparticles-canvas-el"	CSS-класс для элемента canvas
container	object	—	Существующий экземпляр Container (продвинутое)
theme	string	—	Theme name (requires @tsparticles/plugin-themes; safe no-op otherwise).