واجهات برمجة التطبيقات الأساسية للمستند والصفحة في Aspose.PDF FOSS for TypeScript

المقدمة

كل قدرة في Aspose.PDF FOSS لـ TypeScript تُتحقق من خلال فئتين: Document وPage. Document تمتلك مجموعة الصفحات وكل ما يخص المستند — البيانات الوصفية، الإشارات المرجعية، تسميات الصفحات، والحفظ/التحميل — بينما كل Page في doc.Pages تمتلك كل ما يخص تلك الصفحة الواحدة: المحتوى، التعليقات التوضيحية، وحقول النماذج. بمجرد أن تصبح هاتان الفئتان مألوفتين، فإن بقية سطح المكتبة — التحويل، التعليقات التوضيحية، النماذج، الأمان — هي في الواقع مجرد مزيد من الطرق على نفس الكائنين.

هذه المشاركة نظرة أقرب على أجزاء ذلك السطح الأساسي التي يذكرها المشاركة التمهيدية بشكل عابر فقط: تجميع المستندات من مستندات أخرى، إنشاء صفحات من لا شيء، إضافة شجرة إشارات مرجعية للتنقل، ووضع وسوم للمحتوى لتسهيل الوصول. جميع الأربعة هي نداءات طرق عادية — لا وحدة منفصلة للاستيراد، ولا تبعية إضافية بخلاف حزمة @asposefoss/pdf نفسها.

هذه هي العمليات التي تظهر بمجرد أن يتخطى خط أنابيب PDF مرحلة “فتح ملف واحد، تعديلّه، حفظه”: دمج تقارير من عدة مصادر في مستند واحد، إنشاء صفحات برمجياً بدلاً من البدء من قالب، وجعل الناتج قابلًا للتنقل وسهل الوصول إليه بدلاً من كونه صحيحًا بصريًا فقط.

ما هو المتضمن

تجميع وإعادة تنظيم المستندات

Document.Split() يقسّم المستند إلى Document جديد صفحة واحدة لكل صفحة، بترتيب الصفحات. Document.ExtractPages() ينسخ مجموعة محددة من أرقام الصفحات التي تبدأ من 1 إلى Document جديد مستقل، بالترتيب المذكور — يمكن تكرار نفس الصفحة. يمكن أيضًا نسخ صفحات من مستند واحد إلى آخر: Document.Append() ينسخ كل صفحة من المستند المصدر إلى نهاية الهدف، وDocument.InsertPage() ينسخ صفحة واحدة عبر المستندات في موضع محدد يبدأ من 1.

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

const report = Document.OpenFile('report.pdf');

const parts = report.Split();                      // one Document per page
const chapter = report.ExtractPages([3, 4, 5]);     // subset (1-based, repeats allowed) as a new Document

const cover = Document.OpenFile('cover.pdf');
report.InsertPage(1, cover.Pages[0]);               // copy a single page across documents
report.Append(chapter);                             // copy chapter's pages onto report

report.WriteTo('assembled.pdf');

يمكن أيضًا دمج عدة مستندات في مستند واحد في استدعاء واحد باستخدام Document.Merge()، والذي يبني Document جديدًا من نسخ كل صفحة من كل مستند يتم تمريره إليه، بترتيب.

إنشاء صفحات من الصفر

Document.New() ينشئ مستندًا من لا شيء: صفر صفحات عندما يُحذف التنسيق، أو صفحة فارغة واحدة من PageFormat المحدد عندما يتم تمريره. الصفحات الفارغة الإضافية تأتي من Document.AddPage()، التي تقبل أيضًا PageFormat (أو Page موجودًا لنسخ حجمه). يتم رسم النص على صفحة باستخدام Page.AddText()، موضعًا عند نقطة (x, y) في مساحة مستخدم PDF.

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

const doc = Document.New(PageFormat.A4);          // one blank A4 page
doc.Pages[0].AddText('Hello', 72, 720, { fontSize: 14 });
doc.AddPage(PageFormat.A4.landscape());           // append more as you go
doc.WriteTo('scratch.pdf');

الإشارات المرجعية وتنقل المستند

يتم قراءة مخطط المستند (لوحة الإشارات المرجعية التي يظهرها معظم قارئات PDF بجوار الصفحة) باستخدام Document.GetOutlines() ويتم استبداله بالكامل بـ Document.SetOutlines()، كل منها يعمل مع شجرة من قيم OutlineItem. كل OutlineItem يحمل Title، ووجهة Dest، وباختياري Children للإدخالات المتداخلة، بالإضافة إلى تلميحات العرض مثل Open (موسعة افتراضيًا) وBold.

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

const items: OutlineItem[] = [
  { Title: 'Introduction', Dest: { name: 'intro' } },
  {
    Title: 'Chapters',
    Open: true,
    Children: [
      { Title: 'Chapter 1', Dest: { name: 'ch1' } },
      { Title: 'Chapter 2', Dest: { name: 'ch2' } },
    ],
  },
];
doc.SetOutlines(items);

تُحل الوجهات المُسماة بهذه الطريقة ({ name: 'intro' }) عبر جدول الوجهات المسماة في المستند، الذي يديره Document.GetNamedDestinations() وDocument.SetNamedDestination() مباشرةً عندما تحتاج إشارة مرجعية إلى الإشارة إلى وجهة غير مرتبطة بمحتوى الصفحة.

النص المُنظم ووضع العلامات للقدرة على الوصول

Document.GetStructTree() يُعيد شجرة البنية المنطقية للمستند (أو null عندما لا يكون المستند مُعلَّمًا)، وDocument.CreateStructTree() يبني واحدة، مُعلِّمًا المستند كـ Tagged. بمجرد وجود شجرة بنية، Page.GetStructuredText() يُعيد نص الصفحة كقيم TextBlock — قطع موضوعة مُجَمَّعة مسبقًا في أسطر وكتل شبيهة بالفقرات — وهو الإدخال الذي يعمل منه تمرير وضع العلامات يدويًا: تجول عبر الكتل، وتحديد أيها عناوين مقابل نص الجسم، وإضافة العناصر المقابلة إلى الشجرة.

function handTagPage(doc: Document, page: Page, heading: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('handTagPage: the document is not tagged yet');
  for (const block of page.GetStructuredText()) {
    const text = block.text.trim();
    if (text.length === 0) continue;
    const el = root.Append(text.startsWith(heading) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

شجرة البنية الموسومة هي ما تبني عليه الميزات اللاحقة: تصدير HTML الدلالي يعيد تدفق المحتوى منها بدلاً من الرجوع إلى تخطيط استدلالي بسيط، وتقوم Document.ValidatePdfUa() بفحص المستند مقابل مجموعة فرعية من معيار الوصول PDF/UA الذي يعتمد على وجود العلامات.

البدء السريع

قم بتثبيت الحزمة، ثم افتح مستندًا، استخرج وأعد دمج مجموعة فرعية من صفحاته، واحفظ النتيجة:

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

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

const doc = Document.OpenFile('report.pdf');

const chapter = doc.ExtractPages([3, 4, 5]);   // subset (1-based, repeats allowed) as a new Document
const cover = Document.OpenFile('cover.pdf');

doc.InsertPage(1, cover.Pages[0]);             // copy a single page across documents
doc.Append(chapter);                           // copy chapter's pages onto doc

doc.WriteTo('assembled.pdf');

الصيغ المدعومة

المصدر المفتوح والترخيص

Aspose.PDF FOSS لـ TypeScript مُصدرة تحت رخصة MIT، مع نشر الشيفرة المصدرية على GitHub. لا توجد علامة مائية للتقييم، ولا حد للاستخدام، ولا ملف ترخيص منفصل لإدارته، ويمكن استخدام المكتبة في المنتجات التجارية دون رسوم ملكية.

الحزمة حالياً في الإصدار 0.1.0، مما يعكس تطويرًا نشطًا في مرحلة مبكرة. Node.js (>=22) هو المتطلب الوحيد في بيئة التشغيل، ولا تحتوي الحزمة على أي تبعيات طرف ثالث أخرى.

البدء

• البدء
• دليل المطور
• مقالات قاعدة المعرفة
• API Reference

الموارد ذات الصلة

• Aspose.PDF Enterprise Product Family
• Aspose.PDF — Enterprise Blog