Come aggiungere immagini a un PDF in JavaScript (React)

Quando la tua app React genera PDF al volo — una fattura che necessita del logo aziendale, un report con un grafico incorporato, un certificato con una firma — devi inserire le immagini raster sulla pagina in modo programmatico. Il semplice JavaScript non può scrivere nella struttura interna di un PDF, e configurare un backend solo per apporre un logo è eccessivo per quello che è in realtà un compito lato client.

Spire.PDF for JavaScript compila un motore PDF completo in WebAssembly, quindi la tua app React può creare, modificare e salvare PDF interamente nel browser. I file passano attraverso un Virtual File System (VFS) nel browser, quindi non c'è alcun viaggio di rete. Con PdfImage e il metodo DrawImage dell'area di disegno della pagina, puoi controllare esattamente dove e quanto grande appare ogni immagine.

In questo articolo imparerai come:

• Caricare un'immagine nel VFS e trasformarla in un oggetto PdfImage
• Disegnarla su una pagina PDF in una posizione e dimensione scelte
• Aggiungere immagini sia a nuovi documenti PDF sia a documenti esistenti
• Ridimensionare, centrare e ripetere immagini su più pagine
• Attivare il download nel browser del PDF finale

Perché generare PDF nel browser

L'alternativa usuale è una libreria lato server (iText, PDFBox e simili): il browser carica le risorse, il server esegue il rendering e il risultato torna indietro. Funziona, ma per l'aggiunta di immagini introduce attriti:

• Latenza — ogni rendering attende un viaggio di andata e ritorno, il che è penalizzante per file di grandi dimensioni o connessioni lente.
• Privacy — i documenti e le immagini sorgente lasciano la macchina dell'utente, un problema per qualsiasi dato sensibile.
• Costo — il rendering PDF richiede molta CPU e non scala gratuitamente.

Con Spire.PDF for JavaScript l'intero lavoro viene eseguito nel browser tramite WebAssembly. Una volta caricato il modulo WASM, il rendering è locale e immediato, il file non lascia mai il dispositivo e non paghi nulla in termini di tempo di elaborazione server.

Prerequisiti

Questa guida presuppone che tu abbia già un progetto React con Spire.PDF for JavaScript installato e il modulo WASM inizializzato. In caso contrario, segui prima Integrazione di Spire.PDF for JavaScript in un progetto React.

Avrai bisogno di:

• I file spire.pdf.base.js e spire.pdf.base.wasm nella cartella public del tuo progetto
• Il modulo WASM raggiungibile tramite window.wasmModule.spirepdf
• Un'immagine da incorporare (PNG, JPEG, ecc.) posizionata dove il VFS possa caricarla

Aggiungere un'immagine a un nuovo PDF

Il caso più semplice: creare un documento PDF nuovo di zecca e disegnare un'immagine sulla sua prima pagina. I passaggi principali sono:

1. Carica l'immagine nel VFS usando window.spire.FetchFileToVFS
2. Crea un PdfDocument e aggiungi una pagina vuota
3. Crea un PdfImage dal file caricato con PdfImage.FromFile
4. Disegna l'immagine sull'area di disegno della pagina con page.Canvas.DrawImage
5. Salva e scarica il risultato

function App() {
  const addImageToPdf = async () => {
    // Get the Spire.PDF WASM module
    const pdfModule = window.wasmModule?.spirepdf;

    // Check if the WASM module is ready
    if (!pdfModule) {
      alert('Spire.PDF is not ready yet');
      return;
    }

    // Load the image into VFS
    const inputImageName = 'TreePic.png';
    await window.spire.FetchFileToVFS(inputImageName, "", `${process.env.PUBLIC_URL}/data/`);

    // Create a PdfDocument object
    let doc = new pdfModule.PdfDocument();

    // Add a page
    let page = doc.Pages.Add();

    // Load the image and scale its display size proportionally
    let image = pdfModule.PdfImage.FromFile(inputImageName);
    let width = image.Width * 0.6;
    let height = image.Height * 0.6;

    // Calculate the horizontal center position and set the vertical position
    let x = (page.Canvas.ClientSize.Width - width) / 2;
    let y = 60;

    // Draw the image at the specified position on the page
    page.Canvas.DrawImage({ image: image, x: x, y: y, width: width, height: height });

    // Define the output file name in PDF format
    const outputFileName = 'AddImage.pdf';

    // Save as PDF format
    doc.SaveToFile({ fileName: outputFileName });
    doc.Close();

    // Read the generated PDF file from VFS and trigger download
    const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
    const blob = new Blob([fileArray], { type: 'application/pdf' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = outputFileName;
    a.click();
    URL.revokeObjectURL(url);
  };

  return (
    <div style={{ textAlign: 'center', height: '300px' }}>
      <h1>Add Image To PDF</h1>
      <button onClick={addImageToPdf}>
        Generate
      </button>
    </div>
  );
}

export default App;

Documento PDF generato dopo l'aggiunta di un'immagine

Cosa fa il codice:

• PdfImage.FromFile(inputImageName) legge l'immagine dal VFS e crea un oggetto PdfImage. Le dimensioni originali in pixel sono disponibili tramite image.Width e image.Height.
• page.Canvas.DrawImage(...) esegue il rendering dell'immagine sulla pagina. I parametri x e y impostano la posizione dell'angolo superiore sinistro, mentre width e height controllano le dimensioni di visualizzazione.
• L'immagine viene ridimensionata al 60% della sua dimensione originale (* 0.6) e centrata orizzontalmente usando (page.Canvas.ClientSize.Width - width) / 2.

Aggiungere un'immagine a un PDF esistente

Aggiungere un'immagine a un documento esistente segue lo stesso schema — l'unica differenza è che, invece di creare un nuovo PdfDocument, ne carichi uno dal VFS e selezioni la pagina di destinazione.

const addImageToExistingPdf = async () => {
  const pdfModule = window.wasmModule?.spirepdf;
  if (!pdfModule) return;

  // Load both the PDF and the image into VFS
  await window.spire.FetchFileToVFS('Report.pdf', "", `${process.env.PUBLIC_URL}/data/`);
  await window.spire.FetchFileToVFS('Logo.png', "", `${process.env.PUBLIC_URL}/data/`);

  // Load the existing PDF
  let doc = new pdfModule.PdfDocument();
  doc.LoadFromFile('Report.pdf');

  // Get the first page (or any page you want)
  let page = doc.Pages.get_Item(0);

  // Load the image and draw it at the top-right corner
  let image = pdfModule.PdfImage.FromFile('Logo.png');
  let imgWidth = 80;
  let imgHeight = 40;
  let x = page.Canvas.ClientSize.Width - imgWidth - 30; // 30pt margin from right edge
  let y = 30; // 30pt from top

  page.Canvas.DrawImage({ image: image, x: x, y: y, width: imgWidth, height: imgHeight });

  // Save and download
  const outputFileName = 'ReportWithLogo.pdf';
  doc.SaveToFile({ fileName: outputFileName });
  doc.Close();

  const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
  const blob = new Blob([fileArray], { type: 'application/pdf' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = outputFileName;
  a.click();
  URL.revokeObjectURL(url);
};

Differenza principale rispetto all'esempio del nuovo documento: doc.LoadFromFile('Report.pdf') carica un PDF esistente invece di partire da zero, e doc.Pages.get_Item(0) recupera una pagina dal documento caricato. Il resto della logica di disegno è identico.

Quando la pagina contiene già un'immagine che devi modificare anziché sovrapporne una nuova, consulta Sostituire e rimuovere immagini da PDF in JavaScript (React).

Ridimensionamento e posizionamento

Il metodo DrawImage ti dà il pieno controllo su dove e quanto grande appare l'immagine. Ecco gli schemi più comuni:

Ridimensionamento proporzionale — moltiplica entrambe le dimensioni per lo stesso fattore per preservare le proporzioni:

let scale = 0.5; // 50% of original size
let width = image.Width * scale;
let height = image.Height * scale;

Larghezza fissa, altezza automatica — imposta la larghezza e calcola l'altezza per preservare le proporzioni:

let targetWidth = 200;
let width = targetWidth;
let height = image.Height * (targetWidth / image.Width);

Centratura orizzontale — posiziona l'immagine equidistante dai margini sinistro e destro della pagina:

let x = (page.Canvas.ClientSize.Width - width) / 2;

Centratura verticale — posiziona l'immagine equidistante dalla parte superiore e inferiore della pagina:

let y = (page.Canvas.ClientSize.Height - height) / 2;

Posizione personalizzata — usa coordinate assolute (l'origine è in alto a sinistra, le unità sono punti; 1 punto = 1/72 di pollice):

let x = 72;  // 1 inch from left
let y = 144; // 2 inches from top

Aggiungere immagini a più pagine

Per aggiungere la stessa immagine (ad es. un logo o una filigrana) a ogni pagina di un documento, scorri la raccolta Pages:

const addImageToAllPages = async () => {
  const pdfModule = window.wasmModule?.spirepdf;
  if (!pdfModule) return;

  await window.spire.FetchFileToVFS('Business_Data_Overview.pdf', "", `${process.env.PUBLIC_URL}/data/`);
  await window.spire.FetchFileToVFS('Logo.png', "", `${process.env.PUBLIC_URL}/data/`);

  let doc = new pdfModule.PdfDocument();
  doc.LoadFromFile('Business_Data_Overview.pdf');

  let image = pdfModule.PdfImage.FromFile('Logo.png');
  let imgWidth = 60;
  let imgHeight = 30;

  // Loop through all pages and draw the logo in the top-right corner
  for (let i = 0; i < doc.Pages.Count; i++) {
    let page = doc.Pages.get_Item(i);
    let x = page.Canvas.ClientSize.Width - imgWidth - 20;
    let y = 20;
    page.Canvas.DrawImage({ image: image, x: x, y: y, width: imgWidth, height: imgHeight });
  }

  const outputFileName = 'AllPagesWithLogo.pdf';
  doc.SaveToFile({ fileName: outputFileName });
  doc.Close();

  const fileArray = window.dotnetRuntime.Module.FS.readFile(outputFileName);
  const blob = new Blob([fileArray], { type: 'application/pdf' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = outputFileName;
  a.click();
  URL.revokeObjectURL(url);
};

Questo schema è utile per aggiungere filigrane, loghi aziendali o timbri in modo uniforme su tutte le pagine di un documento multipagina.

Scaricare il risultato

Dopo aver salvato il PDF nel VFS con doc.SaveToFile(), devi rileggerlo e attivare il download nel browser. Questo schema in due passaggi — salva nel VFS, poi leggi dal VFS — è usato in ogni esempio Spire.PDF for JavaScript:

// 1. Save the PDF to the VFS
doc.SaveToFile({ fileName: 'Output.pdf' });
doc.Close();

// 2. Read the file from VFS as a byte array
const fileArray = window.dotnetRuntime.Module.FS.readFile('Output.pdf');

// 3. Create a Blob and trigger download
const blob = new Blob([fileArray], { type: 'application/pdf' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'Output.pdf';
a.click();
URL.revokeObjectURL(url);

Lo stesso schema si applica quando salvi immagini (usa type: 'image/png' o type: 'image/jpeg' nel costruttore Blob).

FAQ

Come posso controllare con precisione posizione e dimensione di un'immagine?

I parametri x e y di DrawImage impostano le coordinate dell'angolo superiore sinistro dell'immagine (in punti, dove 1 punto = 1/72 di pollice). I parametri width e height impostano le dimensioni di visualizzazione. Per ridimensionare in modo proporzionale, leggi image.Width e image.Height e moltiplica entrambi per lo stesso fattore. Per centrare orizzontalmente, calcola x = (page.Canvas.ClientSize.Width - width) / 2.

Posso aggiungere più immagini alla stessa pagina?

Sì. Chiama page.Canvas.DrawImage(...) una volta per ogni immagine, con coordinate x/y diverse. Le immagini vengono disegnate nell'ordine in cui chiami il metodo, quindi le immagini successive appaiono sopra quelle precedenti se si sovrappongono.

Quali formati di immagine sono supportati?

Spire.PDF for JavaScript supporta i comuni formati raster, inclusi PNG, JPEG, BMP e GIF. Usa PdfImage.FromFile(filename) per caricarne uno qualsiasi dal VFS.

Aggiungere un'immagine influisce sul contenuto esistente della pagina?

No. DrawImage aggiunge un nuovo oggetto immagine alla pagina senza modificare testo, grafica o altre immagini esistenti. L'immagine viene disegnata sopra il contenuto esistente alle coordinate specificate. Per estrarre un'immagine da un PDF esistente e riutilizzarla altrove, consulta Estrarre immagini da un PDF in JavaScript (React).

Vedi anche

• Sostituire e rimuovere immagini da PDF in JavaScript (React)
• Estrarre immagini da un PDF in JavaScript (React)
• Integrazione di Spire.PDF for JavaScript in un progetto React
• Pagina del prodotto Spire.PDF for JavaScript