Jak pracować z obrazami i grafiką w TypeScript

Ten przewodnik pokazuje, jak umieścić obrazy i grafiki wektorowe na stronie PDF przy użyciu Aspose.PDF FOSS dla TypeScript. Page.AddImage() osadza bajty rastrowe, Page.Graphics() zwraca PageGraphics do rysowania kształtów, a Document.OptionalContent grupuje je w przełączalne warstwy. Wymaga Node.js 22 lub nowszej wersji.

Przewodnik krok po kroku

Krok 1: Zainstaluj pakiet

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

Zweryfikuj instalację, importując klasę Document w nowym pliku TypeScript — ta linia powinna zostać rozwiązana bez błędu po zainstalowaniu pakietu:

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

Krok 2: Zaimportuj wymagane klasy

Importuj Document, aby otworzyć plik; AddImage(), Graphics() i AddBarcode() są wywoływane bezpośrednio na zwróconych przez niego instancjach Page:

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

Krok 3: Osadź obraz rastrowy

Page.AddImage(data, rect, opts) umieszcza bajty JPEG lub PNG wewnątrz ograniczającego rect, skalowane do dopasowania:

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

Krok 4: Rysuj grafikę wektorową

Page.Graphics() zwraca PageGraphics, który buforuje wywołania rysowania, aż apply() je zatwierdzi. Łącz setStrokeColor(), setFillColor(), setLineWidth() oraz metody kształtów, takie jak rect(), circle() i drawLine(), a następnie 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();

Krok 5: Powiąż obrazy i grafikę z warstwami opcjonalnej zawartości

doc.OptionalContent.AddLayer(name, opts) tworzy Layer, który można przełączać w panelu warstw przeglądarki. Przekaż go jako layer do AddImage(), lub otocz wywołania PageGraphics w 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 });

Krok 6: Dodaj kod kreskowy

Page.AddBarcode(spec, rect, opts) rysuje symbol kodu kreskowego; spec.type wybiera symbologię, a spec.data jest zakodowanym ładunkiem. Podobnie jak AddImage(), przyjmuje opcję layer:

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

Typowe problemy i rozwiązania

Grafika rysowana przy użyciu PageGraphics nie pojawiają się na stronie. Wywołuje bufor aż do apply() jest wywoływany — każdy PageGraphics sekwencja wymaga dopasowanego apply() przed zapisaniem strony.

Warstwa nigdy nie pojawia się w panelu warstw przeglądarki. Confirm AddLayer() został wywołany przez doc.OptionalContent, nie utworzony jako samodzielny obiekt — warstwy muszą być zarejestrowane w konfiguracji zawartości opcjonalnej dokumentu, aby były wymienione.

Obraz lub kod kreskowy ignoruje przełącznik widoczności warstwy. Only AddImage(), AddBarcode(), oraz treść otoczona w PageGraphics.BeginLayer() / EndLayer() wiąże się z warstwą przez /OC — inna podstawowa zawartość strony (np. zwykły tekst rysowany bez opcji warstwy) nie jest wpływana przez żaden przełącznik warstwy.

Page.AddImage() zniekształca obraz. rect ustawia bezpośrednio umieszczoną szerokość i wysokość — najpierw oblicz je na podstawie własnego stosunku boków obrazu źródłowego, jeśli obraz nie ma być rozciągany.

Najczęściej zadawane pytania

Czy warstwa może domyślnie być ukryta?

Tak — przekaż { visible: false } do OptionalContent.AddLayer().

Czy jedna warstwa może być zagnieżdżona pod inną?

Tak — przekaż { parent: someLayer } przy wywoływaniu AddLayer(), aby zagnieździć nową warstwę pod istniejącą w /D /Order panelu warstw.

Jakie formaty obrazów akceptuje `Page.AddImage()`?

Bajty rastrowe JPEG i PNG.

Czy rysowanie przy użyciu `PageGraphics` obsługuje przezroczystość i linie przerywane?

Tak — setOpacity(alpha) ustawia fill/stroke alpha i setDash(pattern, phase) ustawia wzór przerywania; oba są łańcuchowe jak pozostałe PageGraphics settery.