چگونه با تصاویر و گرافیک‌ها در TypeScript کار کنیم

این راهنما نشان می‌دهد چگونه تصاویر و گرافیک‌های برداری را بر روی یک صفحه PDF با Aspose.PDF FOSS برای TypeScript قرار دهید. Page.AddImage() بایت‌های رستر را جاسازی می‌کند، Page.Graphics() یک PageGraphics برای رسم شکل‌ها برمی‌گرداند، و Document.OptionalContent هر دو را در لایه‌های قابل تغییر گروه‌بندی می‌کند. نیاز به Node.js 22 یا بالاتر دارد.

راهنمای گام به گام

مرحله ۱: نصب بسته

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';

مرحله ۲: وارد کردن کلاس‌های مورد نیاز

برای باز کردن فایل، Document را وارد کنید؛ AddImage()، Graphics() و AddBarcode() مستقیماً بر روی نمونه‌های Page که باز می‌گرداند فراخوانی می‌شوند:

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

مرحله ۳: درج یک تصویر رستری

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

مرحله ۴: رسم گرافیک‌های برداری

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

مرحله ۵: اتصال تصاویر و گرافیک‌ها به لایه‌های محتوای اختیاری

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

مرحله ۶: افزودن بارکد

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() بدهید.

آیا می‌توان یک لایه را زیر لایه‌ای دیگر تو در تو کرد؟

بله — هنگام فراخوانی AddLayer()، { parent: someLayer } را پاس کنید تا لایهٔ جدید را زیر لایهٔ موجود در /D /Order پنل لایه‌ها تو در تو کنید.

چه فرمت‌های تصویری توسط `Page.AddImage()` پذیرفته می‌شوند؟

بایت‌های رستر JPEG و PNG.

آیا رسم با `PageGraphics` از شفافیت و خطوط نقطه‌دار پشتیبانی می‌کند؟

بله — setOpacity(alpha) مقدار آلفای پر/خط را تنظیم می‌کند و setDash(pattern, phase) الگوی نقطه‌دار را تنظیم می‌کند؛ هر دو می‌توانند به‌صورت زنجیره‌ای مانند سایر تنظیم‌کننده‌های PageGraphics استفاده شوند.