Como trabalhar com imagens e gráficos em TypeScript

Este guia mostra como colocar imagens e gráficos vetoriais em uma página PDF com Aspose.PDF FOSS para TypeScript. Page.AddImage() incorpora bytes raster, Page.Graphics() retorna um PageGraphics para desenho de formas, e Document.OptionalContent agrupa ambos em camadas alternáveis. Requer Node.js 22 ou superior.

Guia passo a passo

Etapa 1: Instalar o pacote

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 a instalação importando a classe Document em um novo arquivo TypeScript — esta linha deve ser resolvida sem erros assim que o pacote for instalado:

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

Etapa 2: Importar classes necessárias

Importe Document para abrir o arquivo; AddImage(), Graphics() e AddBarcode() são chamados diretamente nas instâncias Page que ele devolve:

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

Etapa 3: Incorporar uma Imagem Raster

Page.AddImage(data, rect, opts) insere bytes JPEG ou PNG dentro de um rect delimitador, dimensionado para se ajustar:

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

Etapa 4: Desenhar Gráficos Vetoriais

Page.Graphics() devolve um PageGraphics que armazena em buffer as chamadas de desenho até que apply() as confirme. Encadeie setStrokeColor(), setFillColor(), setLineWidth() e métodos de forma como rect(), circle() e drawLine(), então 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();

Etapa 5: Vincular Imagens e Gráficos a Camadas de Conteúdo Opcional

doc.OptionalContent.AddLayer(name, opts) cria um Layer que pode ser alternado no painel de camadas de um visualizador. Passe-o como layer para AddImage(), ou envolva chamadas PageGraphics em 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 });

Etapa 6: Adicionar um Código de Barras

Page.AddBarcode(spec, rect, opts) desenha um símbolo de código de barras; spec.type seleciona a simbologia e spec.data é a carga útil codificada. Como AddImage(), aceita uma opção 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 comuns e soluções

Gráficos desenhados com PageGraphics não aparecem na página. Chama o buffer até apply() é chamado — cada PageGraphics sequência precisa de um correspondente apply() antes que a página seja salva.

Uma camada nunca aparece no painel de camadas do visualizador. Confirm AddLayer() foi chamado através de doc.OptionalContent, não criado como um objeto independente — as camadas devem ser registradas na configuração de conteúdo opcional do documento para serem listadas.

Uma imagem ou código de barras ignora a alternância de visibilidade de uma camada. Only AddImage(), AddBarcode(), e conteúdo envolto em PageGraphics.BeginLayer() / EndLayer() vincular a uma camada via /OC — o outro conteúdo base de uma página (texto simples desenhado sem uma opção de camada, por exemplo) não é afetado por nenhuma alternância de camada.

Page.AddImage() distorce a imagem. rect define a largura e altura posicionadas diretamente — calcule-a a partir da proporção de aspecto da imagem original primeiro se a imagem não deve ser esticada.

Perguntas frequentes

Uma camada pode ser definida como oculta por padrão?

Sim — passe { visible: false } para OptionalContent.AddLayer().

Uma camada pode ser aninhada sob outra?

Sim — passe { parent: someLayer } ao chamar AddLayer() para aninhar a nova camada sob uma existente no /D /Order do painel de camadas.

Quais formatos de imagem `Page.AddImage()` aceita?

Bytes raster JPEG e PNG.

Desenhar com `PageGraphics` suporta opacidade e linhas tracejadas?

Sim — setOpacity(alpha) define o alpha de preenchimento/traço e setDash(pattern, phase) define um padrão de traço; ambos são encadeáveis como os outros PageGraphics setters.