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 یا حاشیه‌نویسی پیوند می‌تواند با نام به‌جای شماره صفحه صریح ارجاع دهد.

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) به یک صفحهٔ صریح با شمارهٔ ۱-پایه اشاره می‌کند. یک مقصد نام‌دار (NamedDest) به نامی اشاره می‌کند که نمایشگر آن را از طریق جدول‌های مقصد-نام‌دار سند حل می‌کند — که زمانی مفید است که صفحهٔ هدف ممکن است جابجا شود.

API Reference خلاصه

همچنین ببینید:

• Aspose.PDF — Enterprise Documentation