Comment travailler avec les images et les graphiques en TypeScript

Ce guide montre comment placer des images et des graphiques vectoriels sur une page PDF avec Aspose.PDF FOSS pour TypeScript. Page.AddImage() intègre des octets raster, Page.Graphics() renvoie un PageGraphics pour le dessin de formes, et Document.OptionalContent regroupe le tout en calques basculables. Il nécessite Node.js 22 ou une version ultérieure.

Guide étape par étape

Étape 1: installer le package

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

Vérifiez l’installation en important la classe Document dans un nouveau fichier TypeScript — cette ligne devrait se résoudre sans erreur une fois le package installé:

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

Étape 2: importer les classes requises

Importez Document pour ouvrir le fichier; AddImage(), Graphics() et AddBarcode() sont appelés directement sur les instances Page qu’il renvoie:

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

Étape3: Intégrer une image raster

Page.AddImage(data, rect, opts) place les octets JPEG ou PNG à l’intérieur d’un rect de délimitation, redimensionnés pour s’ajuster:

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

Étape4: Dessiner des graphiques vectoriels

Page.Graphics() renvoie un(e) PageGraphics qui met en mémoire tampon les appels de dessin jusqu’à ce que apply() les valide. Enchaînez setStrokeColor(), setFillColor(), setLineWidth() et les méthodes de forme telles que rect(), circle() et drawLine(), puis 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();

Étape5: Lier les images et les graphiques aux calques de contenu optionnel

doc.OptionalContent.AddLayer(name, opts) crée un(e) Layer qui peut être activé/désactivé dans le panneau des calques d’un visualiseur. Passez-le en tant que layer à AddImage(), ou encapsulez les appels PageGraphics dans 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 });

Étape6: Ajouter un code-à-barres

Page.AddBarcode(spec, rect, opts) trace un symbole de code-barres; spec.type sélectionne la symbologie et spec.data est la charge utile encodée. Comme AddImage(), il accepte une option layer:

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

Problèmes courants et solutions

Graphiques dessinés avec PageGraphics n’apparaissent pas sur la page. Appelle le tampon jusqu’à ce que apply() soit appelé — chaque PageGraphics séquence nécessite une correspondance apply() avant que la page ne soit enregistrée.

Un calque n’apparaît jamais dans le panneau des calques du visualiseur. Confirm AddLayer() a été appelé via doc.OptionalContent, non créé comme un objet autonome — les calques doivent être enregistrés dans la configuration de contenu optionnel du document pour être répertoriés.

Une image ou un code-barres ignore le commutateur de visibilité d’un calque. Only AddImage(), AddBarcode(), et le contenu enveloppé dans PageGraphics.BeginLayer() / EndLayer() se lie à un calque via /OC — le reste du contenu de base d’une page (texte brut dessiné sans option de calque, par exemple) n’est pas affecté par un quelconque commutateur de calque.

Page.AddImage() déforme l’image. rect définit directement la largeur et la hauteur placées — calculez-la d’abord à partir du rapport d’aspect propre de l’image source si l’image ne doit pas être étirée.

Foire aux questions

Une couche peut-elle être masquée par défaut?

Oui — passez { visible: false } à OptionalContent.AddLayer().

Une couche peut-elle être imbriquée sous une autre?

Oui — passez { parent: someLayer } lors de l’appel de AddLayer() pour imbriquer la nouvelle couche sous une existante dans le /D /Order du panneau des calques.

Quels formats d’image `Page.AddImage()` accepte-t-il?

Octets raster JPEG et PNG.

Le dessin avec `PageGraphics` prend-il en charge l’opacité et les lignes pointillées?

Oui — setOpacity(alpha) définit l’alpha du remplissage/du contour et setDash(pattern, phase) définit un motif de tirets; les deux sont chaînables comme les autres PageGraphics setters.