Wie man mit Bildern und Grafiken in TypeScript arbeitet

Dieser Leitfaden zeigt, wie man Bilder und Vektorgrafiken auf einer PDF-Seite mit Aspose.PDF FOSS für TypeScript platziert. Page.AddImage() bettet Rasterbytes ein, Page.Graphics() liefert ein PageGraphics zum Zeichnen von Formen, und Document.OptionalContent gruppiert beides in umschaltbare Ebenen. Es erfordert Node.js 22 oder höher.

Schritt-für-Schritt-Anleitung

Schritt 1: Paket installieren

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

Überprüfen Sie die Installation, indem Sie die Document-Klasse in einer neuen TypeScript-Datei importieren — diese Zeile sollte nach der Installation des Pakets fehlerfrei aufgelöst werden:

import { Document } from '@asposefoss/pdf';

Schritt 2: Erforderliche Klassen importieren

Importieren Sie Document, um die Datei zu öffnen; AddImage(), Graphics() und AddBarcode() werden direkt an den von ihr zurückgegebenen Page-Instanzen aufgerufen:

import { Document } from '@asposefoss/pdf';

Schritt 3: Rasterbild einbetten

Page.AddImage(data, rect, opts) platziert JPEG- oder PNG-Bytes in ein begrenzendes rect, skaliert, um zu passen:

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

const imgW = 300;
const imgH = 237; // aspect preserved from a 1280x1014 source
page.AddImage(imageBytes, [150, 400, 150 + imgW, 400 + imgH]);

Schritt 4: Vektorgrafiken zeichnen

Page.Graphics() gibt ein PageGraphics zurück, das Zeichenaufrufe puffert, bis apply() sie ausführt. Verketten Sie setStrokeColor(), setFillColor(), setLineWidth() und Formmethoden wie rect(), circle() und drawLine(), dann stroke() / fill() / fillStroke():

const g = page.Graphics();

g.save()
  .setStrokeColor([0.55, 0.60, 0.75])
  .setLineWidth(1)
  .rect(80, 300, 435, 340)
  .stroke()
  .restore();

g.setFillColor([0.88, 0.91, 0.98])
  .setStrokeColor([0.45, 0.52, 0.75])
  .setLineWidth(1)
  .circle(120, 340, 13)
  .fillStroke();

g.apply();

Schritt 5: Bilder und Grafiken an optionale Inhaltsebenen binden

doc.OptionalContent.AddLayer(name, opts) erstellt ein Layer, das im Ebenen-Panel eines Viewers ein- und ausgeschaltet werden kann. Übergeben Sie es als layer an AddImage(), oder wickeln Sie PageGraphics-Aufrufe in BeginLayer() / EndLayer() ein:

const oc = doc.OptionalContent;
const grid = oc.AddLayer('Grid', { visible: false }); // default off
const branding = oc.AddLayer('Branding');

const g2 = page.Graphics();
g2.BeginLayer(grid);
g2.save().setStrokeColor([0.72, 0.76, 0.88]).setLineWidth(0.4).setDash([3, 3]);
g2.drawLine(80, 300, 515, 300);
g2.stroke().restore();
g2.EndLayer();
g2.apply();

page.AddImage(logoBytes, [370, 606, 480, 640], { layer: branding });

Schritt 6: Barcode hinzufügen

Page.AddBarcode(spec, rect, opts) zeichnet ein Barcode-Symbol; spec.type wählt die Symbologie aus und spec.data ist die kodierte Nutzlast. Wie AddImage() akzeptiert es eine layer-Option:

page.AddBarcode({ type: 'code128', data: 'ROOM-204' }, [370, 340, 500, 384], {
  layer: branding,
  text: true, // draw the human-readable payload beneath the symbol
});

Häufige Probleme und Lösungen

Grafiken, die gezeichnet werden mit PageGraphics werden nicht auf der Seite angezeigt. Ruft den Puffer bis apply() aufgerufen wird — jeder PageGraphics Sequenz benötigt ein passendes apply() bevor die Seite gespeichert wird.

Ein Layer erscheint nie im Ebenen-Panel des Viewers. Confirm AddLayer() wurde aufgerufen über doc.OptionalContent, nicht als eigenständiges Objekt erstellt — Ebenen müssen in der Optional-Content-Konfiguration des Dokuments registriert werden, um aufgeführt zu werden.

Ein Bild oder Barcode ignoriert die Sichtbarkeitsumschaltung einer Ebene. Only AddImage(), AddBarcode(), und Inhalt, der eingeschlossen ist in PageGraphics.BeginLayer() / EndLayer() an eine Ebene binden über /OC — anderer Basisinhalt einer Seite (z.B. Klartext, der ohne Ebenenoption gezeichnet wird) wird von keiner Ebenenumschaltung beeinflusst.

Page.AddImage() verzerrt das Bild. rect setzt die platzierte Breite und Höhe direkt — berechne sie zuerst aus dem Seitenverhältnis des Quellbildes, wenn das Bild nicht gedehnt werden soll.

Häufig gestellte Fragen

Kann eine Ebene standardmäßig ausgeblendet sein?

Ja — übergebe { visible: false } an OptionalContent.AddLayer().

Kann eine Ebene unter einer anderen verschachtelt werden?

Ja — übergebe { parent: someLayer } beim Aufruf von AddLayer(), um die neue Ebene unter einer bestehenden im /D /Order des Ebenen-Panels zu verschachteln.

Welche Bildformate akzeptiert `Page.AddImage()`?

JPEG- und PNG-Rasterbytes.

Unterstützt das Zeichnen mit `PageGraphics` Transparenz und gestrichelte Linien?

Ja — setOpacity(alpha) legt die Alpha-Werte für Füllung/Strich fest und setDash(pattern, phase) legt ein Strichmuster fest; beide sind verkettbar wie die anderen PageGraphics-Setzer.