Come Lavorare con Immagini e Grafica in TypeScript

Questa guida mostra come inserire immagini e grafiche vettoriali su una pagina PDF con Aspose.PDF FOSS per TypeScript. Page.AddImage() incorpora byte raster, Page.Graphics() restituisce un PageGraphics per il disegno di forme, e Document.OptionalContent raggruppa entrambi in livelli commutabili. Richiede Node.js 22 o versioni successive.

Guida passo-passo

Passo 1: Installa il pacchetto

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

Verifica l’installazione importando la classe Document in un nuovo file TypeScript — questa riga dovrebbe risolversi senza errori una volta che il pacchetto è installato:

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

Passo 2: Importa le classi richieste

Importa Document per aprire il file; AddImage(), Graphics() e AddBarcode() vengono chiamati direttamente sulle istanze Page che restituisce:

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

Passo 3: Inserisci un’immagine raster

Page.AddImage(data, rect, opts) inserisce byte JPEG o PNG all’interno di un rect di delimitazione, scalati per adattarsi:

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

Passo 4: Disegna grafica vettoriale

Page.Graphics() restituisce un PageGraphics che memorizza in buffer le chiamate di disegno fino a quando apply() le conferma. Concatena setStrokeColor(), setFillColor(), setLineWidth() e i metodi di forma come rect(), circle() e drawLine(), quindi 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();

Passo 5: Associa immagini e grafica a livelli di contenuto opzionale

doc.OptionalContent.AddLayer(name, opts) crea un Layer che può essere attivato/disattivato nel pannello dei livelli di un visualizzatore. Passalo come layer a AddImage(), oppure avvolgi le chiamate PageGraphics in 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 });

Passo 6: Aggiungi un codice a barre

Page.AddBarcode(spec, rect, opts) disegna un simbolo di codice a barre; spec.type seleziona la simbologia e spec.data è il payload codificato. Come AddImage(), accetta un’opzione layer:

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

Problemi comuni e soluzioni

Grafica disegnata con PageGraphics non compaiono nella pagina. Chiama il buffer fino a apply() viene chiamato — ogni PageGraphics sequenza necessita di una corrispondenza apply() prima che la pagina venga salvata.

Un livello non compare mai nel pannello dei livelli del visualizzatore. Confirm AddLayer() è stato chiamato tramite doc.OptionalContent, non creato come oggetto autonomo — i layer devono essere registrati nella configurazione del contenuto opzionale del documento per essere elencati.

Un’immagine o un codice a barre ignora l’interruttore di visibilità di un layer. Only AddImage(), AddBarcode(), e contenuto avvolto in PageGraphics.BeginLayer() / EndLayer() associa a un layer tramite /OC — l’altro contenuto di base di una pagina (testo semplice disegnato senza un’opzione di layer, per esempio) non è influenzato da alcun interruttore di layer.

Page.AddImage() distorce l’immagine. rect imposta direttamente la larghezza e l’altezza posizionate — calcolala prima dal rapporto d’aspetto dell’immagine di origine se l’immagine non deve essere allungata.

Domande frequenti

Un layer può essere impostato di default su nascosto?

Sì — passa { visible: false } a OptionalContent.AddLayer().

Un layer può annidarsi sotto un altro?

Sì — passa { parent: someLayer } quando chiami AddLayer() per annidare il nuovo layer sotto uno esistente nel /D /Order del pannello dei layer.

Quali formati immagine accetta `Page.AddImage()`?

Byte raster JPEG e PNG.

Il disegno con `PageGraphics` supporta opacità e linee tratteggiate?

Sì — setOpacity(alpha) imposta l’alpha di riempimento/traccia e setDash(pattern, phase) imposta un pattern di tratteggio; entrambi sono concatenabili come gli altri setter PageGraphics.