Comment ajouter des images à un PDF en JavaScript (React)

Lorsque votre application React génère des PDF à la volée — une facture qui doit comporter le logo d’une entreprise, un rapport avec un graphique intégré, un certificat portant une signature — vous devez placer des images raster sur la page par programmation. Le JavaScript standard ne peut pas écrire dans la structure interne d’un PDF, et mettre en place un backend uniquement pour ajouter un logo est excessif pour ce qui est en réalité une tâche côté client.

Spire.PDF pour JavaScript compile un moteur PDF complet en WebAssembly, ce qui permet à votre application React de créer, modifier et enregistrer des PDF entièrement dans le navigateur. Les fichiers transitent par un système de fichiers virtuel (VFS) dans le navigateur, ce qui évite tout aller-retour réseau. Avec PdfImage et la méthode DrawImage du canevas de la page, vous contrôlez précisément où et comment chaque image apparaît.

Dans cet article, vous apprendrez à :

• Charger une image dans le VFS et la transformer en objet PdfImage
• La dessiner sur une page PDF à une position et une taille choisies
• Ajouter des images à des documents PDF entièrement nouveaux et existants
• Mettre à l’échelle, centrer et répéter des images sur plusieurs pages
• Déclencher le téléchargement du PDF final dans le navigateur

Pourquoi générer des PDF dans le navigateur

L’alternative habituelle est une bibliothèque côté serveur (iText, PDFBox, etc.) : le navigateur envoie les ressources, le serveur effectue le rendu, puis le résultat revient. Cela fonctionne, mais pour l’ajout d’images, cela ajoute des frictions :

• Latence — chaque rendu attend un aller-retour, ce qui est pénalisant pour les fichiers volumineux ou les connexions lentes.
• Confidentialité — les documents et images sources quittent la machine de l’utilisateur, un problème pour toute donnée sensible.
• Coût — le rendu PDF est très gourmand en CPU et ne passe pas à l’échelle sans frais.

Avec Spire.PDF pour JavaScript, tout le travail s’exécute dans le navigateur via WebAssembly. Une fois le module WASM chargé, le rendu est local et instantané, le fichier ne quitte jamais l’appareil et aucun temps serveur n’est facturé.

Prérequis

Cette procédure suppose que vous disposez déjà d’un projet React avec Spire.PDF pour JavaScript installé et le module WASM initialisé. Dans le cas contraire, suivez d’abord Intégrer Spire.PDF pour JavaScript dans un projet React.

Vous aurez besoin de :

• Les fichiers spire.pdf.base.js et spire.pdf.base.wasm dans le dossier public de votre projet
• Le module WASM accessible via window.wasmModule.spirepdf
• Une image à incorporer (PNG, JPEG, etc.) placée là où le VFS peut la charger

Ajouter une image à un nouveau PDF

Le scénario le plus simple consiste à créer un tout nouveau document PDF et à dessiner une image sur sa première page. Les étapes clés sont :

1. Charger l’image dans le VFS à l’aide de window.spire.FetchFileToVFS
2. Créer un PdfDocument et ajouter une page vierge
3. Créer un PdfImage à partir du fichier chargé avec PdfImage.FromFile
4. Dessiner l’image sur le canevas de la page avec page.Canvas.DrawImage
5. Enregistrer et télécharger le résultat

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;

Document PDF généré après ajout d’une image

Ce que fait ce code :

• PdfImage.FromFile(inputImageName) lit l’image depuis le VFS et crée un objet PdfImage. Les dimensions d’origine en pixels sont disponibles via image.Width et image.Height.
• page.Canvas.DrawImage(...) rend l’image sur la page. Les paramètres x et y définissent la position du coin supérieur gauche, et width et height contrôlent la taille d’affichage.
• L’image est mise à l’échelle à 60 % de sa taille d’origine (* 0.6) et centrée horizontalement à l’aide de (page.Canvas.ClientSize.Width - width) / 2.

Ajouter une image à un PDF existant

L’ajout d’une image à un document existant suit le même modèle — la seule différence est qu’au lieu de créer un nouveau PdfDocument, vous en chargez un depuis le VFS et sélectionnez la page cible.

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);
};

Principale différence avec l’exemple du nouveau document : doc.LoadFromFile('Report.pdf') charge un PDF existant au lieu de partir de zéro, et doc.Pages.get_Item(0) récupère une page du document chargé. Le reste de la logique de dessin est identique.

Lorsque la page contient déjà une image que vous devez modifier plutôt que d’en superposer une nouvelle, consultez Remplacer et supprimer des images dans des PDF en JavaScript (React).

Mise à l’échelle et positionnement

La méthode DrawImage vous donne un contrôle total sur l’emplacement et la taille de l’image. Voici les modèles les plus courants :

Mise à l’échelle proportionnelle — multipliez les deux dimensions par le même facteur pour préserver le ratio hauteur/largeur :

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

Largeur fixe, hauteur automatique — définissez la largeur et calculez la hauteur pour préserver le ratio :

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

Centrage horizontal — placez l’image à égale distance des marges gauche et droite de la page :

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

Centrage vertical — placez l’image à égale distance du haut et du bas de la page :

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

Position personnalisée — utilisez des coordonnées absolues (l’origine est en haut à gauche, les unités sont des points ; 1 point = 1/72 pouce) :

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

Ajouter des images à plusieurs pages

Pour ajouter la même image (par exemple, un logo ou un filigrane) à chaque page d’un document, parcourez la collection 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);
};

Ce modèle est utile pour ajouter uniformément des filigranes, des logos d’entreprise ou des tampons de page à un document multipage.

Télécharger le résultat

Après avoir enregistré le PDF dans le VFS avec doc.SaveToFile(), vous devez le relire et déclencher son téléchargement dans le navigateur. Ce modèle en deux étapes — enregistrer dans le VFS, puis lire depuis le VFS — est utilisé dans chaque exemple Spire.PDF pour 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);

Le même modèle s’applique lors de l’enregistrement d’images (utilisez type: 'image/png' ou type: 'image/jpeg' dans le constructeur Blob).

FAQ

Comment contrôler précisément la position et la taille d’une image ?

Les paramètres x et y de DrawImage définissent les coordonnées du coin supérieur gauche de l’image (en points, où 1 point = 1/72 pouce). Les paramètres width et height définissent la taille d’affichage. Pour une mise à l’échelle proportionnelle, lisez image.Width et image.Height et multipliez les deux par le même facteur. Pour centrer horizontalement, calculez x = (page.Canvas.ClientSize.Width - width) / 2.

Puis-je ajouter plusieurs images sur la même page ?

Oui. Appelez page.Canvas.DrawImage(...) une fois pour chaque image, avec des coordonnées x/y différentes. Les images sont dessinées dans l’ordre où vous appelez la méthode ; ainsi, si elles se chevauchent, les images suivantes apparaissent au-dessus des précédentes.

Quels formats d’image sont pris en charge ?

Spire.PDF pour JavaScript prend en charge les formats raster courants, notamment PNG, JPEG, BMP et GIF. Utilisez PdfImage.FromFile(filename) pour charger l’un de ces formats depuis le VFS.

L’ajout d’une image affecte-t-il le contenu existant de la page ?

Non. DrawImage ajoute un nouvel objet image à la page sans modifier le texte, les graphiques ou les autres images existants. L’image est dessinée par-dessus le contenu existant aux coordonnées spécifiées. Pour extraire une image d’un PDF existant afin de la réutiliser ailleurs, consultez Extraire des images d’un PDF en JavaScript (React).

Voir aussi

• Remplacer et supprimer des images dans des PDF en JavaScript (React)
• Extraire des images d’un PDF en JavaScript (React)
• Intégrer Spire.PDF pour JavaScript dans un projet React
• Page produit de Spire.PDF pour JavaScript