So fügen Sie Bilder zu einer PDF in JavaScript (React) hinzu

Wenn Ihre React-App PDFs spontan erstellt – eine Rechnung mit Firmenlogo, ein Bericht mit eingebettetem Diagramm, ein Zertifikat mit Signatur – müssen Sie Rasterbilder programmatisch auf der Seite platzieren. Reines JavaScript kann nicht in die interne Struktur einer PDF-Datei schreiben, und nur für das Aufbringen eines Logos einen Backend-Server aufzusetzen, ist für eine eigentlich clientseitige Aufgabe übertrieben.

Spire.PDF for JavaScript kompiliert eine vollständige PDF-Engine zu WebAssembly, sodass Ihre React-App PDFs vollständig im Browser erstellen, bearbeiten und speichern kann. Dateien werden über ein In-Browser-Virtual-Dateisystem (VFS) bewegt, sodass kein Netzwerk-Roundtrip nötig ist. Mit PdfImage und der DrawImage-Methode der Seiten-Canvas legen Sie genau fest, wo und in welcher Größe jedes Bild erscheint.

In diesem Artikel erfahren Sie, wie Sie:

• Ein Bild in das VFS laden und in ein PdfImage-Objekt umwandeln
• Es an einer gewählten Position und Größe auf einer PDF-Seite zeichnen
• Bilder sowohl zu brandneuen als auch zu vorhandenen PDF-Dokumenten hinzufügen
• Bilder über mehrere Seiten hinweg skalieren, zentrieren und wiederholen
• Einen Browser-Download des fertigen PDFs auslösen

Warum PDFs im Browser erzeugen

Die übliche Alternative ist eine serverseitige Bibliothek (iText, PDFBox und Ähnliche): Der Browser lädt die Assets hoch, der Server rendert und das Ergebnis kommt zurück. Das funktioniert, bringt aber beim Aufbringen von Bildern zusätzliche Hürden mit sich:

• Latenz – jedes Rendern wartet auf einen Roundtrip, was bei großen Dateien oder langsamen Verbindungen schmerzt.
• Datenschutz – Quelldokumente und Bilder verlassen den Rechner des Benutzers, ein Problem bei sensiblen Inhalten.
• Kosten – PDF-Rendering ist rechenintensiv und lässt sich nicht kostenlos skalieren.

Mit Spire.PDF for JavaScript läuft die gesamte Aufgabe per WebAssembly im Browser. Sobald das WASM-Modul geladen ist, erfolgt das Rendern lokal und sofort; die Datei verlässt das Gerät nicht und Sie zahlen keine Serverzeit.

Voraussetzungen

Dieser Leitfaden setzt voraus, dass Sie bereits ein React-Projekt mit installiertem Spire.PDF for JavaScript und initialisiertem WASM-Modul haben. Falls nicht, folgen Sie zuerst Integrieren von Spire.PDF for JavaScript in ein React-Projekt.

Sie benötigen:

• Die Dateien spire.pdf.base.js und spire.pdf.base.wasm im public-Ordner Ihres Projekts
• Das über window.wasmModule.spirepdf erreichbare WASM-Modul
• Ein einzubettendes Bild (PNG, JPEG usw.), das an einem Ort abgelegt ist, von dem das VFS es laden kann

Ein Bild zu einem neuen PDF hinzufügen

Das einfachste Szenario: Erstellen Sie ein brandneues PDF-Dokument und zeichnen Sie ein Bild auf seine erste Seite. Die wichtigsten Schritte sind:

1. Laden Sie das Bild in das VFS mit window.spire.FetchFileToVFS
2. Erstellen Sie ein PdfDocument und fügen Sie eine leere Seite hinzu
3. Erstellen Sie aus der geladenen Datei ein PdfImage mit PdfImage.FromFile
4. Zeichnen Sie das Bild mit page.Canvas.DrawImage auf die Seiten-Canvas
5. Speichern und laden Sie das Ergebnis herunter

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;

PDF-Dokument, das nach dem Hinzufügen eines Bildes erzeugt wurde

Was der Code bewirkt:

• PdfImage.FromFile(inputImageName) liest das Bild aus dem VFS und erstellt ein PdfImage-Objekt. Die ursprünglichen Pixelmaße sind über image.Width und image.Height verfügbar.
• page.Canvas.DrawImage(...) rendert das Bild auf die Seite. Die Parameter x und y setzen die Position der oberen linken Ecke, und width und height steuern die Anzeigegröße.
• Das Bild wird auf 60 % seiner Originalgröße skaliert (* 0.6) und mit (page.Canvas.ClientSize.Width - width) / 2 horizontal zentriert.

Ein Bild zu einem vorhandenen PDF hinzufügen

Das Hinzufügen eines Bilds zu einem vorhandenen Dokument folgt demselben Muster – der einzige Unterschied besteht darin, dass Sie statt eines neuen PdfDocument ein vorhandenes aus dem VFS laden und die Zielseite auswählen.

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

Hauptunterschied zum Beispiel für neue Dokumente: doc.LoadFromFile('Report.pdf') lädt ein vorhandenes PDF, statt bei null zu beginnen, und doc.Pages.get_Item(0) ruft eine Seite aus dem geladenen Dokument ab. Die übrige Zeichenlogik ist identisch.

Wenn die Seite bereits ein Bild enthält, das Sie ändern müssen, statt ein neues darüberzulegen, lesen Sie Ersetzen und Entfernen von Bildern aus PDFs in JavaScript (React).

Skalierung und Positionierung

Die DrawImage-Methode bietet Ihnen volle Kontrolle darüber, wo und wie groß das Bild erscheint. Hier sind die gängigsten Muster:

Proportionale Skalierung – multiplizieren Sie beide Abmessungen mit demselben Faktor, um das Seitenverhältnis beizubehalten:

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

Feste Breite, automatische Höhe – Breite festlegen und Höhe so berechnen, dass das Seitenverhältnis erhalten bleibt:

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

Horizontale Zentrierung – Bild mit gleichem Abstand zu den linken und rechten Seitenrändern platzieren:

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

Vertikale Zentrierung – Bild mit gleichem Abstand zu oben und unten auf der Seite platzieren:

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

Benutzerdefinierte Position – absolute Koordinaten verwenden (Ursprung ist oben links, Einheiten sind Punkte; 1 Punkt = 1/72 Zoll):

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

Bilder zu mehreren Seiten hinzufügen

Um dasselbe Bild (z. B. ein Logo oder Wasserzeichen) auf jeder Seite eines Dokuments zu platzieren, durchlaufen Sie die Pages-Auflistung in einer Schleife:

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

Dieses Muster ist nützlich, um Wasserzeichen, Firmenlogos oder Seitenstempel gleichmäßig über ein mehrseitiges Dokument zu verteilen.

Ergebnis herunterladen

Nachdem Sie das PDF mit doc.SaveToFile() im VFS gespeichert haben, müssen Sie es zurücklesen und einen Browser-Download auslösen. Dieses zweistufige Muster – erst ins VFS speichern, dann aus dem VFS lesen – wird in jedem Spire.PDF-for-JavaScript-Beispiel verwendet:

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

Das gleiche Muster gilt beim Speichern von Bildern (verwenden Sie type: 'image/png' oder type: 'image/jpeg' im Blob-Konstruktor).

FAQ

Wie kann ich Position und Größe eines Bildes präzise steuern?

Die Parameter x und y von DrawImage legen die Koordinaten der oberen linken Ecke des Bildes fest (in Punkten, wobei 1 Punkt = 1/72 Zoll). Die Parameter width und height bestimmen die Anzeigegröße. Für eine proportionale Skalierung lesen Sie image.Width und image.Height und multiplizieren beide mit demselben Faktor. Für die horizontale Zentrierung berechnen Sie x = (page.Canvas.ClientSize.Width - width) / 2.

Kann ich einer Seite mehrere Bilder hinzufügen?

Ja. Rufen Sie page.Canvas.DrawImage(...) für jedes Bild einmal mit unterschiedlichen x/y-Koordinaten auf. Die Bilder werden in der Reihenfolge gezeichnet, in der Sie die Methode aufrufen, sodass spätere Bilder über früheren liegen, wenn sie sich überlappen.

Welche Bildformate werden unterstützt?

Spire.PDF for JavaScript unterstützt gängige Rasterformate wie PNG, JPEG, BMP und GIF. Verwenden Sie PdfImage.FromFile(filename), um eines dieser Formate aus dem VFS zu laden.

Beeinflusst das Hinzufügen eines Bildes vorhandene Inhalte auf der Seite?

Nein. DrawImage fügt der Seite ein neues Bildobjekt hinzu, ohne vorhandenen Text, Grafiken oder andere Bilder zu verändern. Das Bild wird an den angegebenen Koordinaten über den vorhandenen Inhalt gezeichnet. Wenn Sie ein Bild aus einem vorhandenen PDF herauslösen möchten, um es anderweitig wiederzuverwenden, lesen Sie Bilder aus einem PDF in JavaScript (React) extrahieren.

Siehe auch

• Ersetzen und Entfernen von Bildern aus PDFs in JavaScript (React)
• Bilder aus einem PDF in JavaScript (React) extrahieren
• Integrieren von Spire.PDF for JavaScript in ein React-Projekt
• Produktseite von Spire.PDF for JavaScript