كيفية العمل مع الصور والرسومات في 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.