איך להמיר מסמכי PDF ב-TypeScript

מדריך זה מראה כיצד להמיר תוכן PDF לפורמטים אחרים באמצעות Aspose.PDF FOSS עבור TypeScript. Page מייצא דף יחיד כ-SVG או כתמונה רסטרית; Document מייצא את כל הקובץ כ-HTML, Markdown, או DOCX, ויכול לאמת ולהמיר מסמך ל-PDF/A. הוא דורש 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 כדי לפתוח את הקובץ; שיטות ההמרה המשמשות להלן נקראות ישירות על המופעים שהוחזרו של Document ו-Page, ולכן אין צורך בייבוא נוסף:

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

שלב 3: המרת דף ל-SVG או לתמונה רסטרית

Page.ToSvg() מחזיר מחרוזת <svg> עצמאית. Page.ToImage() מציג את הדף בתצורת בתים רסטרית; scale הוא ביחס ל-DPI המקורי של ה-PDF של 72, ולכן scale: 2 מציג ב-144 DPI:

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

const doc = Document.OpenFile('input.pdf');
const svg = doc.Pages[0].ToSvg(); // standalone <svg> string
const png = doc.Pages[0].ToImage({ scale: 2 }); // Uint8Array of PNG bytes @144 DPI

שלב 4: המרת מסמך ל-HTML או ל-Markdown

Document.ToHtml() במצב ברירת המחדל שלו (סמנטי) ממחזר את התוכן מעץ המבנה לכותרות ופסקאות; העבר { mode: 'fixed' } כדי לשחזר כל דף כ-SVG ממוקם וטקסט ממוקם באופן מוחלט במקום זאת. Document.ToMarkdown() מייצר GFM Markdown עבור כל המסמך:

const semanticHtml = doc.ToHtml(); // reflowable markup, all pages
const fixedHtml = doc.ToHtml({ mode: 'fixed', fonts: 'embed' }); // positioned, fonts embedded
const markdown = doc.ToMarkdown(); // GFM Markdown, all pages

מצב סמנטי קורא את עץ המבנה שנבנה על ידי Document.GetStructTree() / Document.CreateStructTree() — במסמך ללא תגיות הוא חוזר לגוף מבוסס הנחה והייצוא מאבד את מבנה הכותרות.

שלב 5: המרת מסמך ל-DOCX

Document.ToDocx() מחזיר .docx בתים עם תוכן ממוחזר ותמונות ארוזות בפנים; העבר { mode: 'textbox' } כדי לשמור על הגיאומטריה הקבועה של כל דף במקום המיחזור:

const docx = doc.ToDocx(); // .docx bytes, reflowed, images in the package
const fixed = doc.ToDocx({ mode: 'textbox' }); // .docx keeping each page's own geometry

שלב 6: אימות והמרה ל PDF/A

Document.ValidatePdfA(level), Document.ValidatePdfX(level) ו-Document.ValidatePdfUa() מחזירים ValidationReport המתאר האם המסמך עומד בתקן המוגדר. Document.ConvertToPdfA(level, opts) מחזיר ConversionReport המפרט אילו תיקונים בוצעו ואילו בעיות נותרו ללא פתרון. הפעל את ההמרה על עותק Document.ExtractPages() כאשר יש צורך לשמור את המסמך החי ללא המרה:

const report = doc.ValidatePdfA('2b');
console.log(report.Passed);

const copy = doc.ExtractPages(doc.Pages.map((_, i) => i + 1));
const conversion = copy.ConvertToPdfA('2b');
console.log(conversion.applied.length, conversion.unresolved.length, conversion.passed);
copy.Save();

בעיות נפוצות ותיקונים

Document.ToHtml() מאבד את מבנה הכותרות. מצב סמנטי הולך בעץ המבנה, ולכן הוא חייב לרוץ אחרי מעבר תיוג — או Document.AutoTag() או תיוג ידני באמצעות StructTreeRoot.Append(). ToHtml() מתקפל חזרה לגוף השערה כאשר GetStructTree() returns null.

ConvertToPdfA() משנה את הקובץ שהתכוונת להשאיר ללא המרה. הפעל את ההמרה על עותק מ Document.ExtractPages(), ואז שמור את העותק בנפרד — ConvertToPdfA() משנה את המסמך שעליו הוא נקרא.

ValidatePdfA() מדווח על תקלות בפעם הראשונה שהוא רץ. סיבה נפוצה היא גופנים סטנדרטיים שלא משולבים והיעדר /OutputIntent — בדוק report.Passed וממצאי הכללים האישיים כדי לראות אילו תנאים לא הושגו.

Page.ToImage() הפלט נראה ברזולוציה נמוכה. scale מתייחס ל-72 DPI; העלה אותו (למשל { scale: 2 } ל-144 DPI) לקבלת פלט באיכות הדפסה.

שאלות נפוצות

מה ההבדל בין ייצוא סמנטי לייצוא קבוע HTML?

מצב סמנטי משנה את זרימת המסמך מעץ המבנה שלו לתגיות שמקריאות היטב בדפדפן בכל רוחב. מצב קבוע משחזר כל עמוד כ-SVG ממוקם וטקסט ממוקם במדויק, התואם בדיוק את הפריסה המקורית.

האם `Document.ToDocx()` שומר על פריסת העמוד המקורית?

בברירת מחדל ToDocx() משנה את זרימת התוכן. העבר { mode: 'textbox' } כדי לשמור על הגאומטריה הקבועה של כל עמוד במקום זאת.

איך אני בודק אם מסמך עומד בתנאי PDF/A לפני המרה שלו?

קרא ל-Document.ValidatePdfA(level) (לדוגמה '2b') ובדוק את ה-ValidationReport שהוחזר — זה מדווח על המצב הנוכחי מבלי לשנות את המסמך.

האם אני יכול להמיר רק תת-קבוצה של עמודים?

כן — בנה תחילה תת-קבוצה Document עם Document.ExtractPages(), ואז קרא לשיטת ההמרה (ToHtml(), ToDocx(), ConvertToPdfA(), וכן הלאה) על תת-הקבוצה הזו.