كيفية العمل مع بنية PDF في TypeScript

هذا الدليل يوضح كيفية بناء تنقل المستند والبنية المنطقية في ملفات PDF باستخدام Aspose.PDF FOSS لـ TypeScript: جدول محتويات قابل للنقر على صفحة، مخطط علامات مرجعية على مستوى المستند، وجهات مسماة، وشجرة بنية موسومة لإمكانية الوصول. يتطلب Node.js 22 أو أحدث.

دليل خطوة بخطوة

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';

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

const page = doc.Pages[0];

page.AddTOC(
  [
    { title: '1.  Introduction', page: 2 },
    { title: '2.  Methodology', page: 5 },
    { title: '3.  Results', page: 9 },
  ],
  [72, 160, 400, 600],
  { font: 'Helvetica', fontSize: 13, color: [0.1, 0.1, 0.15], rowGap: 18 },
);

const items: OutlineItem[] = [
  { Title: 'Sales', Dest: { name: 'section.sales' }, Open: true, Color: [0.1, 0.4, 0.1] },
  { Title: 'Appendix', Dest: { name: 'section.appendix' } },
];

doc.SetOutlines(items);

const destNames = new Set(doc.GetNamedDestinations().map((d) => d.name));

const walk = (nodes: OutlineItem[]): void => {
  for (const item of nodes) {
    if (item.Dest && 'name' in item.Dest) {
      console.log(destNames.has(item.Dest.name), item.Title);
    }
    if (item.Children) walk(item.Children);
  }
};
walk(doc.GetOutlines());

function tagPage(doc: Document, page: Page, headingText: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('tagPage: 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(headingText) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

المشكلات الشائعة والحلول

Document.GetStructTree() returns null. المستند لم يتم وسمه بعد — اتصل Document.CreateStructTree() (أو Document.AutoTag()) قبل إنشاء العناصر يدويًا باستخدام StructTreeRoot.Append() / StructElement.MarkContent().

عنصر المخطط لا ينتقل إلى الصفحة الصحيحة. OutlineItem.Dest يجب أن يحدد اسم وجهة موجودة فعليًا — تحقق من ذلك item.Dest.name against Document.GetNamedDestinations() قبل الحفظ، كما هو موضح في الخطوة 5.

Page.AddTOC() الإدخالات تشير إلى الصفحة الخاطئة. page في كل إدخال في جدول المحتويات هو رقم صفحة الهدف نفسه — تأكد منه مقابل page.Number على الهدف الفعلي Page, ليس فهرس مصفوفة مفترض.

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

الأسئلة الشائعة

هل يمكن للعلامة المرجعية أن تُفتح مُوسَّعة مسبقًا؟

نعم — اضبط Open: true على OutlineItem لجعل الأطفال الخاصين بهذه العقدة مرئيين افتراضيًا في لوحة العلامات المرجعية.

ما الفرق بين العلامة المرجعية والوجهة المسماة؟

العلامة المرجعية (OutlineItem) هي إدخال مرئي في لوحة التنقل؛ الوجهة المسماة (Document.GetNamedDestinations() / SetNamedDestination()) هي هدف صفحة داخلي قابل لإعادة الاستخدام يمكن أن تشير إليه العلامة المرجعية أو إدخال فهرس المحتويات أو توضيح رابط بالاسم.

هل يؤثر وضع وسوم على المستند في مظهره؟

لا — شجرة الهيكل (StructTreeRoot, StructElement) هي طبقة منطقية موازية تصف ترتيب القراءة والدلالات؛ فهي لا تغيّر المحتوى المرئي للصفحة.

هل يمكنني تعشيق العلامات المرجعية؟

نعم — اضبط Children على OutlineItem إلى مصفوفة من كائنات OutlineItem إضافية لإنشاء شجرة قابلة للطي ومتعددة المستويات.

انظر أيضاً

• النواة API
• Installation
• FAQ
• API Reference
• Aspose.PDF — Enterprise Knowledge Base