Puppeteer: generazione di PDF e screenshot

In questa lezione, ci concentreremo sull'utilizzo di Puppeteer per generare PDF e realizzare screenshot avanzati delle pagine web. Queste sono operazioni molto utili quando vogliamo archiviare una pagina web o creare una versione "stampabile" di un sito. Puppeteer offre un'API potente e flessibile che ci permette di generare questi contenuti in modo semplice e personalizzabile. Impareremo come eseguire entrambe le operazioni, esplorando le varie opzioni e parametri che possiamo utilizzare per adattare i risultati alle nostre esigenze specifiche.

Introduzione alla generazione di PDF e Screenshot con Puppeteer

Puppeteer ci permette di interagire con una pagina web come se fossimo un utente, ma con il controllo completo. Tra le funzionalità più utili di Puppeteer ci sono quelle che permettono di generare screenshot e PDF che sono molto richieste in vari contesti. Come la creazione di report, la documentazione automatizzata, o anche la generazione di immagini e versioni stampabili di pagine web.

In Puppeteer, la generazione di un PDF o di uno screenshot è semplice. Possiamo farlo utilizzando le funzioni page.pdf() e page.screenshot(). Tuttavia, come vedremo, queste funzioni offrono molte opzioni avanzate che permettono di personalizzare ulteriormente il risultato.

Generazione di PDF con Puppeteer

La funzione principale che utilizziamo per generare un PDF in Puppeteer è page.pdf(). Questa funzione permette di creare un PDF della pagina web, salvandola direttamente su disco o inviandola a una destinazione specificata. La sintassi di base per generare un PDF è la seguente:

await page.pdf({ path: 'example.pdf' });

Questo comando salva il PDF della pagina attualmente caricata come example.pdf nella directory corrente.

Esistono molte opzioni che possiamo passare alla funzione pdf() per personalizzare il nostro PDF. Alcune delle più utili includono:

• path: il percorso dove il PDF deve essere salvato. Se non viene fornito, il PDF verrà restituito come buffer.
• format: la dimensione del formato del PDF (es. 'A4', 'Letter', ecc.). Se non specificato, Puppeteer utilizza il formato A4.
• landscape: imposta l'orientamento della pagina su orizzontale (default è verticale).
• printBackground: indica se includere o meno il background della pagina (default è false).
• margin: definisce i margini del PDF. È possibile specificare i margini superiore, inferiore, sinistro e destro, ad esempio {top: '10px', right: '10px', bottom: '10px', left: '10px'}.
• scale: Permette di scalare il contenuto della pagina. Il valore predefinito è 1, ma può essere aumentato o diminuito per cambiare la scala del PDF.

Ecco un esempio di come utilizzare alcune di queste opzioni:

await page.pdf({
  path: 'example.pdf',
  format: 'A4',
  landscape: true,
  printBackground: true,
  margin: { top: '20mm', left: '10mm', right: '10mm', bottom: '20mm' },
  scale: 0.8
});

In questo caso stiamo generando un PDF in formato A4, orientato in orizzontale, con uno sfondo incluso, margini personalizzati, e riducendo la scala del contenuto a 0.8.

Creazione di un PDF da una sezione specifica della pagina

Se vogliamo generare un PDF solo per una sezione specifica della pagina, possiamo usare il selettore CSS per estrarre solo quella parte. Per fare ciò, dobbiamo usare la funzione page.$() per selezionare un elemento e quindi eseguire il rendering di quell'elemento come PDF.

const element = await page.$('.sezione-specifica');
await element.pdf({
  path: 'sezione.pdf',
  format: 'A4'
});

Se la sezione ha dimensioni diverse rispetto a quelle di un formato standard (come A4), possiamo anche specificare le dimensioni personalizzate nel PDF usando le proprietà width e height.

Quando generiamo il PDF è importante considerare che la libreria renderizza la pagina così com'è nel browser. Pertanto, le media queries CSS potrebbero influire sulla visualizzazione dell'elemento selezionato nel PDF, specialmente se la pagina ha stili specifici per la stampa. Se l'elemento è troppo grande per essere contenuto in una singola pagina PDF, possiamo aggiungere opzioni come landscape: true per orientare il PDF in modalità orizzontale o usare altre opzioni di personalizzazione per il layout.

Generazione di screenshot con Puppeteer

Un'altra funzionalità molto utile di Puppeteer è la possibilità di catturare screenshot di una pagina web. La funzione page.screenshot() permette di fare uno screenshot completo della pagina o di una parte specifica. La sintassi di base per generare uno screenshot è:

await page.screenshot({ path: 'example.png' });

Questo comando salva uno screenshot della pagina attualmente caricata come example.png.

Anche per la generazione degli screenshot, esistono diverse opzioni che possiamo personalizzare:

• path: il percorso dove lo screenshot deve essere salvato.
• type: il formato dell'immagine. Può essere png o jpeg. Il formato predefinito è png.
• quality: specifica la qualità dell'immagine (solo per i JPEG). Il valore è compreso tra 0 e 100, con 100 che rappresenta la qualità massima.
• fullPage: se impostato su true cattura uno screenshot dell'intera pagina, altrimenti cattura solo la parte visibile.
• clip: definisce un'area da catturare utilizzando un oggetto con le proprietà x, y, width ed height che specificano l'area da ritagliare.
• omitBackground: se impostato su true rimuove lo sfondo dall'immagine rendendola trasparente.

Ecco un esempio di come fare uno screenshot di una parte specifica della pagina:

await page.screenshot({
  path: 'example.png',
  clip: { x: 0, y: 0, width: 800, height: 600 }
});

In questo esempio, lo screenshot viene catturato solo in una sezione di 800x600 pixel, partendo dalla posizione (0, 0). Se vogliamo catturare uno screenshot dell'intera pagina, dobbiamo semplicemente passare l'opzione fullPage: true:

await page.screenshot({
  path: 'fullpage.png',
  fullPage: true
});

Screenshot di sezioni scrolling

Un caso interessante è quando vogliamo catturare uno screenshot di una pagina che ha un contenuto lungo (ad esempio, una pagina che richiede lo scroll). Con la nostra libreria possiamo catturare tutto il contenuto visibile anche se non è visibile tutto in una sola schermata. In questo caso, possiamo combinare le opzioni di fullPage con lo scroll automatico per catturare l'intera pagina.

await page.screenshot({
  path: 'scrolling_page.png',
  fullPage: true
});

Conclusioni

In questa lezione abbiamo esplorato come Puppeteer può essere utilizzato per generare PDF e screenshot avanzati. Abbiamo visto come configurare queste operazioni per personalizzare il risultato finale, inclusi aspetti come il formato, i margini, l'orientamento e l'inclusione di sfondi o altre caratteristiche. Le funzioni pdf() e screenshot() di Puppeteer offrono un ampio ventaglio di opzioni che permettono di creare contenuti visivi personalizzati e documentazione automatizzata delle pagine web.

Queste capacità sono particolarmente utili quando vogliamo archiviare, condividere o rendere disponibili versioni "statiche" delle pagine web per vari scopi, come report, documentazione o archiviazione.