Как работать с изображениями и графикой в TypeScript

Это руководство показывает, как размещать изображения и векторную графику на странице PDF с помощью Aspose.PDF FOSS для TypeScript. Page.AddImage() внедряет растровые байты, Page.Graphics() возвращает PageGraphics для рисования фигур, а Document.OptionalContent объединяет их в переключаемые слои. Требуется Node.js 22 или новее.

Пошаговое руководство

Шаг 1: Установите пакет

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

Проверьте установку, импортировав класс Document в новый файл TypeScript — эта строка должна разрешаться без ошибок после установки пакета:

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

Шаг 2: Импортируйте необходимые классы

Импортируйте Document, чтобы открыть файл; AddImage(), Graphics() и AddBarcode() вызываются непосредственно у экземпляров Page, которые он возвращает:

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

Шаг 3: Вставить растровое изображение

Page.AddImage(data, rect, opts) помещает байты JPEG или PNG внутри ограничивающего rect, масштабируя под размер:

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

Шаг 4: Рисовать векторную графику

Page.Graphics() возвращает PageGraphics, который буферизует вызовы рисования до тех пор, пока apply() не зафиксирует их. Сцепляйте setStrokeColor(), setFillColor(), setLineWidth() и методы фигур, такие как rect(), circle() и drawLine(), затем 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();

Шаг 5: Привязать изображения и графику к слоям дополнительного содержания

doc.OptionalContent.AddLayer(name, opts) создаёт Layer, который можно переключать в панели слоёв просмотрщика. Передайте его как layer в AddImage(), либо оберните вызовы PageGraphics в 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 });

Шаг 6: Добавить штрих-код

Page.AddBarcode(spec, rect, opts) рисует символ штрихкода; spec.type выбирает символьную схему, а spec.data — это закодированная нагрузка. Как и AddImage(), он принимает параметр layer:

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

Общие проблемы и решения

Графика, нарисованная с помощью PageGraphics не появляются на странице. Вызов буфера до apply() вызывается — каждый PageGraphics последовательность требует соответствующего apply() перед сохранением страницы.

Слой никогда не появляется в панели слоёв просмотрщика. Confirm AddLayer() был вызван через doc.OptionalContent, не создаётся как отдельный объект — слои должны быть зарегистрированы в конфигурации дополнительного содержимого документа, чтобы их можно было отобразить в списке.

Изображение или штрих-код игнорирует переключатель видимости слоя. Only AddImage(), AddBarcode(), и содержимое, обёрнутое в PageGraphics.BeginLayer() / EndLayer() привязывается к слою через /OC — другое базовое содержимое страницы (например, простой текст, отрисованный без опции слоя) не зависит от переключения любого слоя.

Page.AddImage() искажает изображение. rect устанавливает размещённую ширину и высоту напрямую — сначала вычислите их из собственного соотношения сторон исходного изображения, если изображение не должно растягиваться.

Часто задаваемые вопросы

Может ли слой по умолчанию быть скрытым?

Да — передайте { visible: false } в OptionalContent.AddLayer().

Можно ли вложить один слой в другой?

Да — передайте { parent: someLayer } при вызове AddLayer(), чтобы вложить новый слой под существующим в /D /Order панели слоёв.

Какие форматы изображений принимает `Page.AddImage()`?

JPEG и PNG растровые байты.

Поддерживает ли рисование с помощью `PageGraphics` прозрачность и пунктирные линии?

Да — setOpacity(alpha) задаёт альфа-канал заливки/контура, а setDash(pattern, phase) задаёт шаблон пунктиров; оба можно цепочкой вызывать, как и другие сеттеры PageGraphics.