نحوه کار با ساختار 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