Structure

Structure

דף זה מכסה ניווט במסמך ובנייה לוגית: מתוות (סימניות), תוכניות תוכן, יעדים בשם, ועץ המבנה המתויג המשמש לנגישות ולשינוי גודל.

מתוות (סימניות)

Document.GetOutlines() מחזיר את עץ המתווה הנוכחי כ־OutlineItem[] ([] כאשר אין /Outlines); Document.SetOutlines() מחליף אותו — העברת [] מסירה את המתווה לחלוטין. לכל OutlineItem יש Title, Dest (מספר עמוד או יעד בשם), Children אופציונלי לקינון, ועיצוב (Color, Bold, Italic, Open).

const items: OutlineItem[] = sections.map((s) => {
  const item: OutlineItem = { Title: s.title, Dest: { name: s.dest } };
  if (s.subtype === 'sales') {
    item.Open = true;
    item.Children = ['Pasta', 'Pizza', 'Antipasti']
      .map((cat) => ({ Title: cat, Dest: { name: s.dest } }));
  }
  return item;
});
doc.SetOutlines(items);

תוכן עניינים

Page.AddTOC() מציג רשימת עצמים של TOCEntry — כל אחד עם title ומספר יעד page — בתוך מלבן בעמוד, עם כותרות מקופלות, קווי נקודות, ותוויות עמוד מיושרות לימין. הוא מחזיר AddTOCResult המדווח כמה ערכים נציירו וכאשר התיבה קטנה מדי, את remainder שלא התאימו.

page.AddTOC(
  sections.map((s, i) => ({ title: `${i + 1}. ${s.title}`, page: s.page.Number })),
  [72, 160, 400, 400],
  { font: 'Helvetica', fontSize: 13, rowGap: 18 },
);

יעדים בשם

Document.GetNamedDestinations() מחזיר כל יעד בשם — ממזג את עץ השמות /Names /Dests ואת מילון ה-/Dests הישן — כזוגות { name, dest }, כאשר dest הוא PageDest ({ page, view }). אלו הם אותם היעדים בשם ש-OutlineItem.Dest או a link annotation יכולים להתייחס אליהם בשם במקום מספר עמוד מפורש.

const destNames = new Set(doc.GetNamedDestinations().map((d) => d.name));
for (const { name, dest } of doc.GetNamedDestinations()) {
  console.log(name, '-> page', dest.page);
}

עץ מבנה מתוייג

Document.AutoTag() מניח ויוצר /StructTreeRoot מתוך פריסת העמוד — כותרות על-פי קיבוץ לפי גודל גופן, פסקאות על-פי בלוקי טקסט, טבלאות על-פי גאומטריית קו הפרדה, והחלטות /Figure מול /Artifact לכל תמונה — ומחזיר AutoTagReport עם ספירות לכל סוג רכיב. Document.GetStructTree() קורא חזרה את ה-StructTreeRoot שנוצר, או null כאשר המסמך אינו מתוייג.

const report = doc.AutoTag({ lang: 'en-US', title: 'Quarterly Report', tables: true });
console.log(report.headings, report.paragraphs, report.tables, report.figures);

const tree = doc.GetStructTree();
console.log(tree ? tree.GetText() : '(no structure tree)');

תוכן שנוסף לאחר ש-AutoTag() כבר פועל — לדוגמה, עמוד שממתין לתוכן לאחר מכן — אינו נכלל בריצה זו ולא יתויג פעמיים. StructTreeRoot.Append() ו-StructElement.MarkContent() הם API עריכה ידנית לצד ההיוריסטית: Append() מוסיף אלמנט ילד מסוג נתון, ו-MarkContent() מסמן אזור עמוד כשתלוי באלמנט זה.

טיפים ושיטות מומלצות

• הפעל את Document.AutoTag() פעם אחת, אחרי שתוכן העמוד סופי — הוא אינו מתייג מחדש תוכן שנוסף אחרי זה, ולכן יש לתייג ידנית כל מה שהתווסף מאוחר יותר עם StructTreeRoot.Append() / StructElement.MarkContent().
• העבר את opts.title ל-AutoTag() — הוא גם מגדיר את /ViewerPreferences /DisplayDocTitle, שה-PDF/UA דורש יחד עם כותרת המסמך.
• OutlineItem.Dest יכול למקם או עמוד מפורש או יעד בשם ({ name: '...' }) — השתמש ביעדים בשם כאשר מספר העמוד היעד עשוי להשתנות עם שינויי תוכן.
• בדקו את AddTOCResult.remainder כאשר ההפעלה האוטומטית של העימוד כבויה — תיבת תוכן עניינים קטנה מדי לכל רשומה מפסיקה לצייר בשקט במקום לחרוג מהתיבה.

בעיות נפוצות

FAQ

איך מוסיפים סימניות לקובץ PDF?

בנו מערך של עצמים OutlineItem (Title, Dest, Children אופציונלי) והעבירו אותו ל-Document.SetOutlines().

האם תוכן עניינים יכול להימשך על פני מספר עמודים?

כן — העבירו את autoPaginate: true באפשרויות של Page.AddTOC(), או בדקו את AddTOCResult.remainder וקראו ל-AddTOC() שוב בעמוד חדש עבור מה שלא התאימה.

איך להפוך קובץ PDF לנגיש (מתויג)?

קרא Document.AutoTag(), אשר ניבא כותרות, פסקאות, טבלאות וציורים מתצורת העמוד. עבור תוכן שנוסף לאחר מכן, או כאשר תוצאת ההיוריסטיקה דורשת תיקון, השתמש ב-StructTreeRoot.Append() וב-StructElement.MarkContent() ישירות.

מה ההבדל בין יעד מספר עמוד ליעד בעל שם?

יעד מספר עמוד (PageDest) מתייחס לעמוד ספציפי המונה מ-1. יעד בעל שם (NamedDest) מתייחס לשם שהצופה פותר באמצעות טבלאות היעדים בעל שם של המסמך עצמו — שימושי כאשר העמוד היעד עשוי לזוז.

API Reference סיכום

ראה גם

• Aspose.PDF — Enterprise Documentation