tsParticles: libreria Javascript per creare animazioni particellari

tsParticles è una libreria Javascript per creare animazioni particellari dinamiche per il proprio sito web. Le particelle usate per le animazioni sono completamente configurabili (dimensioni, colore, velocità, forma, …). Sono consultabili alcuni esempi qui, dove sarà possibile anche sperimentare nuove configurazioni che potranno essere esportate in un JSON pronto all’uso.

Animazioni particellari: cosa sono?

Le animazioni particellari sono il risultato di una tecnica di computer grafica che utilizza un vasto numero di sprites (particelle) per simulare fenomeni particolarmente complessi e caratterizzati da un certo grado di casualità (come neve, pioggia, fuoco, vapore e fumo).

All’interno di questo tipo di animazioni le particelle vengono generate specificando dei parametri iniziali (ad esempio forma e dimensione) e poi vengono modificate e spostate secondo determinati schemi e a determinate velocità al fine di produrre l’effetto desiderato.

Installazione

Installare tsParticles è molto semplice e per farlo potete scegliere diverse strade.

jsDelivr

Questa è l’installazione più semplice, basterà cercare la libreria su jsDelivr

Cliccando sul file tsparticles.min.js verrà aperto il file dal browser e basterà salvarlo sul computer oppure usare tasto degli appunti (quello col foglio per intendersi) che ci darà 4 opzioni:

• URL: questo restituirà l’url al file
• SRI: è il controllo integrità ma è trascurabile
• HTML: preparerà un tag script pronto all’uso
• HTML + SRI: preparerà un tag script col controllo integrità, la soluzione più sicura

Scelto uno di questi metodi sarà sufficiente includere lo script nell’HTML della pagina, o delle pagine, in cui vogliamo aggiungere le animazioni.

CDNJS

L’installazione tramite CDNJS è molto simile a quella presentata tramite jsDelivr.

Anche in questo caso sarà sufficiente includere il link alla libreria ospitata in remoto per essere subito operativi.

NPM

Per chi utilizza npm sarà sufficiente utilizzare

npm install tsparticles

e la libreria sarà pronta all’uso.

YARN

Per chi utilizza yarn sarà sufficiente utilizzare

yarn add tsparticles

e la libreria sarà pronta all’uso.

Compilazione manuale

Per i più avventurosi sarà possibile scaricare la libreria direttamente dal sito che però richiederà una compilazione manuale. Per compilare la libreria è richiesto npm.

Una volta scaricato lo zip, estraetelo ed eseguite il seguente comando

npm install && npm run build

Questo preparerà nella cartella dist i file presenti anche su jsDelivr. Basterà copiarli nel proprio sito ed usarli come specificato sopra.

Il pacchetto dei sorgenti contiene anche un’ulteriore pagina di esempi, per eseguirla basterà eseguire il comando

npm run start

e andare all’indirizzo

http://localhost:3000

Configurazione

Una volta aggiunto il tag script alla propria pagina si procederà alla configurazione.

Per prima cosa dovremo creare un contenitore per le nostre particelle, come ad esempio:

<div id="tsparticles"></div>

La configurazione è molto semplice, per usare le particelle con la configurazione di default sarà sufficiente includere nella pagina questo codice

var container = tsParticles.load('tsparticles');

container contiene il gestore delle particelle, vedremo più avanti come usarlo.

Per chi volesse personalizzare l’animazione esiste un secondo parametro per il metodo load dove impostare le varie opzioni. E’ opportuno precisare che non sarà necessario specificarle tutte, basterà personalizzare soltanto quelle che ci interessano. Facciamo qualche esempio:

/*
  Stabilisco il numero delle particelle
*/
tsParticles.load('tsparticles', {
  particles: {
    number: 150
  }
});

/*
  Stabilisco la forma delle particelle
*/
tsParticles.load('tsparticles', {
  particles: {
    shape: {
      type: 'square'
    }
  }
});

/*
  Stabilisco la dimensione delle particelle
*/
tsParticles.load('tsparticles', {
  particles: {
    size: {
      value: 3
    }
  }
});

/*
  Stabilisco l'opacità delle particelle
*/
tsParticles.load("tsparticles", {
  particles: {
    opacity: {
      value: 0.8
    }
  }
});

Sono delle semplici configurazioni che si possono applicare. Il consiglio è di provarle per testare con mano l’effetto raggiunto. NB: Eseguire lo script resetterà ogni volta il contenitore e quindi anche le particelle.

Le configurazioni più articolate richiederanno più di una proprietà per volta. Facciamo un esempio più complesso:

tsParticles.load("tsparticles", {
  particles: {
    color: { 
      value: "#ffffff"
    },
    lineLinked: {
      color: "#ffffff",
      distance: 150,
      enable: true,
      opacity: 0.4,
      width: 1
    },
    move: {
      bounce: false,
      direction: "none",
      enable: true,
      outMode: "out",
      random: false,
      speed: 2,
      straight: false
    },
    number: { 
      density: { enable: false },
      value: 80
    },
    opacity: {
      animation: { enable: false },
      random: false,
      value: 0.5
    },
    shape: {
      type: "circle"
    },
    size: {
      anim: { enable: false },
      random: true,
      value: 5
    }
  }
});

Questa configurazione crea 80 particelle circolari, di raggio 5, opacità 0.5 che si muovono a una velocità 2 e hanno una linea che le collega fino a una distanza di 160 larga 1.

Ovviamente poitete personalizzare a picaimento secondo i vostri gusti ed esigenze.

Se avete scaricato un export dal sito degli esempi, in quel file potete trovare tutte le opzioni disponibili. Nel caso in cui abbiate un file JSON esportato avete 2 possibilità:

• Caricarlo tramite AJAX
• Copiare il contenuto nel Javascript nel secondo parametro della funzione load

Configurazione tramite JSON e AJAX

Per utilizzare i file JSON tramite AJAX la configurazione iniziale è leggermente differente

tsParticles.loadJSON('tsparticles', 'percorso al file.json');

Il metodo loadJSON è asincrono, avete quindi due scelte che illustrerò di seguito

1. State usando già gli async/await di Javascript
2. Non sapete cosa sia una funzione asincrona, async/await o siete costretti alle versioni di Javascript senza questa funzionalità

Nel primo caso potete usare tranquillamente

const container = await tsParticles.loadJSON('tsparticles', 'percorso al file.json');

dove container è l’oggetto che gestisce particelle appena caricato.

Altrimenti possiamo usare il metodo then disponibile per i metodi asincroni.

await tsParticles.loadJSON('tsparticles', 'percorso al file.json').then(function (container) {
// eseguito dopo il caricamento
});

Il metodo then aspetta l’esecuzione di un metodo asincrono ed esegue la funzione parametro. Anche in questo caso container contiene l’oggetto che gestisce le particelle.

Usare il container

Più di una volta ho parlato dell’oggetto che gestisce le particelle, sempre chiamato container negli esempi precedenti.

Quell’oggetto ha delle funzioni per interagire con le animazioni pronte all’uso.

container.pause();
container.play();

container.stop();

// se usate await 
await container.start();
// se usate then
container.start().then(function () {
// avviate
});

I due start alla fine riassumono la sintassi descritta nel caricamento dei JSON con AJAX.

Migrare da particles.js

Se avete già un’installazione della vecchia libreria particles.js non disperate, tsParticles è compatibile al 100%, sarà sufficiente sostituire lo script come descritto nella sezione installazione. La vecchia sintassi continuerà a funzionare anche se restituirà uno warning nella console. Per rimuoverlo dovrete cambiare il codice di configurazione come descritto qui sopra.

Esempi

Oltre ai già citati esempi su CodePen preparo esempi di utilizzo della libreria con varie animazioni e configurazioni pronte all’uso.

La collection è pubblica e disponibile qui

Contribuire

Il progetto è attualmente in fase di sviluppo, se qualcuno volesse contribuire è ben accetto. Vi prego di seguire le linee guida presenti su GitHub.

https://github.com/matteobruni/tsparticles