كيفية تحويل مستندات 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 نسبة إلى الدقة الأصلية للـ PDF البالغة 72 DPI، لذا 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 الدلالي والثابت؟

يعيد وضع الوضع الدلالي (Semantic mode) تدفق المستند من شجرة هيكله إلى ترميز يُقرأ جيدًا في المتصفح بأي عرض. الوضع الثابت (Fixed mode) يعيد إنتاج كل صفحة كـ SVG موضعًا ونصًا موضعًا مطلقًا، مطابقًا تمامًا لتخطيط الصفحة الأصلي.

هل يحافظ `Document.ToDocx()` على تخطيط الصفحة الأصلي؟

بشكل افتراضي، ToDocx() يعيد تدفق المحتوى. مرّر { mode: 'textbox' } للحفاظ على الهندسة الثابتة لكل صفحة بدلاً من ذلك.

كيف أتحقق مما إذا كان المستند يفي بـ PDF/A قبل تحويله؟

استدعِ Document.ValidatePdfA(level) (مثلاً '2b') وتفقد الـ ValidationReport المرجع — هذا يُبلغ عن الحالة الحالية دون تعديل المستند.

هل يمكنني تحويل مجموعة فرعية فقط من الصفحات؟

نعم — قم بإنشاء مجموعة فرعية Document أولاً باستخدام Document.ExtractPages()، ثم استدعِ طريقة التحويل (ToHtml()، ToDocx()، ConvertToPdfA()، وما إلى ذلك) على تلك المجموعة الفرعية.