Cómo trabajar con imágenes y gráficos en TypeScript

Esta guía muestra cómo colocar imágenes y gráficos vectoriales en una página PDF con Aspose.PDF FOSS para TypeScript. Page.AddImage() incrusta bytes raster, Page.Graphics() devuelve un PageGraphics para dibujar formas, y Document.OptionalContent agrupa ambos en capas conmutables. Requiere Node.js 22 o posterior.

Guía paso a paso

Paso 1: Instalar el paquete

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

Verifique la instalación importando la clase Document en un nuevo archivo TypeScript — esta línea debería resolverse sin error una vez que el paquete esté instalado:

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

Paso 2: Importar clases requeridas

Importa Document para abrir el archivo; AddImage(), Graphics() y AddBarcode() se llaman directamente sobre las instancias de Page que devuelve:

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

Paso 3: Insertar una imagen raster

Page.AddImage(data, rect, opts) coloca bytes JPEG o PNG dentro de un rect delimitador, escalado para ajustarse:

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

Paso 4: Dibujar gráficos vectoriales

Page.Graphics() devuelve un PageGraphics que almacena en búfer las llamadas de dibujo hasta que apply() las confirma. Encadena setStrokeColor(), setFillColor(), setLineWidth() y métodos de forma como rect(), circle() y drawLine(), luego 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();

Paso 5: Vincular imágenes y gráficos a capas de contenido opcional

doc.OptionalContent.AddLayer(name, opts) crea un Layer que puede alternarse en el panel de capas de un visor. Pásalo como layer a AddImage(), o envuelve las llamadas a PageGraphics en 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 });

Paso 6: Añadir un código de barras

Page.AddBarcode(spec, rect, opts) dibuja un símbolo de código de barras; spec.type selecciona la simbología y spec.data es la carga útil codificada. Al igual que AddImage(), acepta una opción layer:

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

Problemas comunes y soluciones

Gráficos dibujados con PageGraphics no aparecen en la página. Llama al búfer hasta apply() se llama — cada PageGraphics secuencia necesita un/a correspondiente apply() antes de que la página se guarde.

Una capa nunca aparece en el panel de capas del visor. Confirm AddLayer() fue llamado a través de doc.OptionalContent, no creado como un objeto independiente — las capas deben registrarse en la configuración de contenido opcional del documento para que se enumeren.

Una imagen o código de barras ignora el conmutador de visibilidad de una capa. Only AddImage(), AddBarcode(), y contenido envuelto en PageGraphics.BeginLayer() / EndLayer() se vinculan a una capa mediante /OC — el resto del contenido base de una página (texto plano dibujado sin una opción de capa, por ejemplo) no se ve afectado por ningún conmutador de capa.

Page.AddImage() distorsiona la imagen. rect establece directamente el ancho y alto colocados — calcúlelo primero a partir de la relación de aspecto original de la imagen si la imagen no debe estirarse.

Preguntas frecuentes

¿Puede una capa estar oculta por defecto?

Sí — pasa { visible: false } a OptionalContent.AddLayer().

¿Puede una capa anidarse bajo otra?

Sí — pasa { parent: someLayer } al llamar a AddLayer() para anidar la nueva capa bajo una existente en el /D /Order del panel de capas.

¿Qué formatos de imagen acepta `Page.AddImage()`?

Bytes raster JPEG y PNG.

¿El dibujo con `PageGraphics` admite opacidad y líneas discontinuas?

Sí — setOpacity(alpha) establece la alfa de relleno/trazo y setDash(pattern, phase) establece un patrón de guiones; ambos son encadenables como los otros PageGraphics setters.