Structure

Structure

Ta strona opisuje nawigację po dokumencie i strukturę logiczną: konspekty (zakładki), spisy treści, nazwane cele oraz oznaczony drzewo struktury używane do dostępności i przepływu tekstu.

Konspekty (Zakładki)

Document.GetOutlines() zwraca bieżące drzewo konspektu jako OutlineItem[] ([] gdy nie ma /Outlines); Document.SetOutlines() zastępuje je — przekazanie [] usuwa konspekt całkowicie. Każdy OutlineItem ma Title, Dest (numer strony lub nazwany cel), opcjonalny Children dla zagnieżdżania oraz stylizację (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);

Spis treści

Page.AddTOC() renderuje listę obiektów TOCEntry — każdy z title i docelowym numerem page — w prostokącie na stronie, z zawiniętymi tytułami, kropkowanymi wiodącymi oraz prawostronnie wyrównanymi etykietami stron. Zwraca AddTOCResult informujący, ile wpisów zostało narysowanych i, gdy pole jest za małe, remainder, które nie zmieściły się.

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 },
);

Nazwane cele

Document.GetNamedDestinations() zwraca każde nazwane miejsce docelowe — łącząc drzewo nazw /Names /Dests i starszy słownik /Dests — jako pary { name, dest }, gdzie dest jest PageDest ({ page, view }). Są to te same nazwane cele, które OutlineItem.Dest lub adnotacja linku może odwoływać się po nazwie zamiast wyraźnego numeru strony.

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

Drzewo Struktury Tagowanej

Document.AutoTag() wnioskuje i tworzy /StructTreeRoot na podstawie układu strony — nagłówki przez grupowanie rozmiaru czcionki, akapity przez bloki tekstu, tabele przez geometrię linii oraz decyzje /Figure vs. /Artifact dla każdego obrazu — i zwraca AutoTagReport z liczbami dla każdego typu elementu. Document.GetStructTree() odczytuje powstały StructTreeRoot, lub null gdy dokument jest nieoznaczony.

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

Treść dodana po uruchomieniu AutoTag() — na przykład strona wypełniona później — nie jest objęta tym przebiegiem i nie zostanie podwójnie otagowana. StructTreeRoot.Append() i StructElement.MarkContent() są ręcznym API tworzenia obok heurystycznego: Append() dodaje element potomny określonego typu, a MarkContent() oznacza region strony jako należący do tego elementu.

Wskazówki i Najlepsze Praktyki

• Uruchom Document.AutoTag() raz, po zakończeniu treści strony — nie otagowuje ponownie treści dodanej później, więc ręcznie otaguj wszystko, co zostanie dodane później, przy użyciu StructTreeRoot.Append() / StructElement.MarkContent().
• Przekaż opts.title do AutoTag() — ustawia również /ViewerPreferences /DisplayDocTitle, które PDF/UA wymaga razem z tytułem dokumentu.
• OutlineItem.Dest może być skierowane zarówno do wyraźnej strony, jak i do nazwanego celu ({ name: '...' }) — używaj nazwanych celów, gdy numer docelowej strony może się przesunąć w miarę zmian treści.
• Sprawdź AddTOCResult.remainder, gdy automatyczna paginacja jest wyłączona — pole spisu treści zbyt małe dla każdego wpisu cicho przestaje rysować zamiast przepełniać pole.

Typowe problemy

FAQ

Jak dodać zakładki do pliku PDF?

Utwórz tablicę obiektów OutlineItem (Title, Dest, opcjonalnie Children) i przekaż ją do Document.SetOutlines().

Czy spis treści może rozciągać się na wiele stron?

Tak — przekaż autoPaginate: true w opcjach Page.AddTOC(), albo sprawdź AddTOCResult.remainder i ponownie wywołaj AddTOC() na nowej stronie dla tego, co nie zmieściło się.

Jak uczynić plik PDF dostępny (oznaczony)?

Wywołaj Document.AutoTag(), które wyprowadza nagłówki, akapity, tabele i rysunki z układu strony. Dla treści dodanej później lub gdy wynik heurystyki wymaga korekty, użyj bezpośrednio StructTreeRoot.Append() i StructElement.MarkContent().

Jaka jest różnica między miejscem docelowym określonym numerem strony a nazwanym miejscem docelowym?

Miejsce docelowe określone numerem strony (PageDest) wskazuje konkretną stronę numerowaną od 1. Nazwane miejsce docelowe (NamedDest) odwołuje się do nazwy, którą przeglądarka rozwiązuje za pomocą własnych tabel nazwanych miejsc w dokumencie — przydatne, gdy docelowa strona może się przemieścić.

API Reference Podsumowanie

Zobacz także

• Aspose.PDF — Enterprise Documentation