כיצד לעבוד עם מבנה PDF ב-TypeScript

מדריך זה מציג כיצד לבנות ניווט במסמך ומבנה לוגי בקבצי PDF עם Aspose.PDF קוד פתוח עבור 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 נוספים כדי לבנות עץ נפתח מרובה רמות.

ראה גם

• Core API
• Installation
• FAQ
• API Reference
• Aspose.PDF — Enterprise Knowledge Base