איך לעבוד עם תמונות וגרפיקה ב-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.