Πώς να εργαστείτε με εικόνες και γραφικά σε TypeScript

Αυτός ο οδηγός δείχνει πώς να τοποθετήσετε εικόνες και διανυσματικά γραφικά σε μια σελίδα PDF με Aspose.PDF FOSS για TypeScript. Το Page.AddImage() ενσωματώνει ραστερά bytes, το Page.Graphics() επιστρέφει ένα PageGraphics για σχεδίαση σχημάτων, και το Document.OptionalContent ομαδοποιεί οποιοδήποτε σε εναλλάξιμα στρώματα. Απαιτεί Node.js 22 ή νεότερο.

Οδηγός βήμα-βήμα

Βήμα 1: Εγκατάσταση του πακέτου

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

Επιβεβαιώστε την εγκατάσταση εισάγοντας την κλάση Document σε ένα νέο αρχείο TypeScript — αυτή η γραμμή θα πρέπει να λυθεί χωρίς σφάλμα μόλις το πακέτο εγκατασταθεί:

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

Βήμα 2: Εισαγωγή των απαιτούμενων κλάσεων

Εισάγετε Document για να ανοίξετε το αρχείο· AddImage(), Graphics() και AddBarcode() καλούνται απευθείας στα στιγμιότυπα Page που επιστρέφει:

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

Βήμα 3: Ενσωμάτωση Raster Image

Page.AddImage(data, rect, opts) τοποθετεί τα byte JPEG ή PNG μέσα σε ένα περιβάλλον rect, κλιμακωμένα ώστε να ταιριάζουν:

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

Βήμα 4: Σχεδίαση Vector Graphics

Page.Graphics() επιστρέφει ένα PageGraphics που αποθηκεύει στην προσωρινή μνήμη κλήσεις σχεδίασης μέχρι το apply() να τις επιβεβαιώσει. Συνδέστε τα setStrokeColor(), setFillColor(), setLineWidth() και τις μεθόδους σχήματος όπως rect(), circle() και drawLine(), έπειτα 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();

Βήμα 5: Σύνδεση Εικόνων και Γραφικών με Optional-Content Layers

doc.OptionalContent.AddLayer(name, opts) δημιουργεί ένα Layer που μπορεί να εναλλάσσεται στον πίνακα επιπέδων του προβολέα. Περάστε το ως layer στο AddImage(), ή τυλίξτε τις κλήσεις PageGraphics σε BeginLayer() / EndLayer():

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

Βήμα 6: Προσθήκη Barcode

Page.AddBarcode(spec, rect, opts) σχεδιάζει ένα σύμβολο barcode· spec.type επιλέγει τη συμβολική και spec.data είναι το κωδικοποιημένο payload. Όπως το AddImage(), δέχεται μια επιλογή layer:

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

Κοινά Προβλήματα και Διορθώσεις

Γραφικά που σχεδιάζονται με PageGraphics δεν εμφανίζονται στη σελίδα. Καλεί το buffer μέχρι apply() καλείται — κάθε PageGraphics ακολουθία χρειάζεται ένα αντίστοιχο apply() πριν αποθηκευτεί η σελίδα.

Ένα στρώμα δεν εμφανίζεται ποτέ στον πίνακα στρωμάτων του προβολέα. Confirm AddLayer() καλέστηκε μέσω doc.OptionalContent, δεν δημιουργείται ως αυτόνομο αντικείμενο — τα στρώματα πρέπει να καταγραφούν στη ρύθμιση προαιρετικού περιεχομένου του εγγράφου για να εμφανιστούν.

Μία εικόνα ή barcode αγνοεί την εναλλαγή ορατότητας ενός στρώματος. Only AddImage(), AddBarcode(), και περιεχόμενο τυλιγμένο σε PageGraphics.BeginLayer() / EndLayer() δεσμεύεται σε ένα στρώμα μέσω /OC — το υπόλοιπο βασικό περιεχόμενο μιας σελίδας (απλό κείμενο που σχεδιάζεται χωρίς επιλογή στρώματος, για παράδειγμα) δεν επηρεάζεται από καμία εναλλαγή στρώματος.

Page.AddImage() παραμορφώνει την εικόνα. rect ορίζει άμεσα το τοποθετημένο πλάτος και ύψος — υπολογίστε το από την αναλογία διαστάσεων της αρχικής εικόνας πρώτα, εάν η εικόνα δεν πρέπει να τεντωθεί.

Συχνές Ερωτήσεις

Μπορεί ένα στρώμα να είναι προεπιλεγμένα κρυφό;

Ναι — περάστε { visible: false } στο OptionalContent.AddLayer().

Μπορεί ένα στρώμα να τοποθετηθεί κάτω από άλλο;

Ναι — περάστε { parent: someLayer } όταν καλείτε το AddLayer() για να τοποθετήσετε το νέο στρώμα κάτω από ένα υπάρχον στο /D /Order του πίνακα στρωμάτων.

Ποια φορμά εικόνας δέχεται το `Page.AddImage()`;

JPEG και PNG raster bytes.

Η σχεδίαση με το `PageGraphics` υποστηρίζει τη διαφάνεια και τις διακεκομμένες γραμμές;

Ναι — setOpacity(alpha) ορίζει το alpha γεμίσματος/περιγράμματος και setDash(pattern, phase) ορίζει ένα μοτίβο παύλας· και τα δύο είναι συνδεόμενα όπως οι άλλοι PageGraphics setters.