Structure

Structure

Această pagină acoperă navigarea în document și structura logică: schițe (marcaje), cuprins, destinații denumite și arborele de structură etichetat utilizat pentru accesibilitate și rearanjare.

Schițe (Marcaje)

Document.GetOutlines() returnează arborele curent de schițe ca OutlineItem[] ([] când nu există /Outlines); Document.SetOutlines() îl înlocuiește — trecând [] elimină complet schița. Fiecare OutlineItem are un Title, un Dest (un număr de pagină sau o destinație denumită), Children opțional pentru imbricare, și stilizare (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);

Cuprins

Page.AddTOC() redă o listă de obiecte TOCEntry — fiecare cu un title și un număr page țintă — într-un dreptunghi pe o pagină, cu titluri înfășurate, linii cu puncte și etichete de pagină aliniate la dreapta. Returnează un AddTOCResult care raportează câte intrări au fost desenate și, când cutia este prea mică, remainder care nu au încăpat.

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

Destinații Denumite

Document.GetNamedDestinations() returnează fiecare destinație numită — îmbinând arborele de nume /Names /Dests și dicționarul moștenit /Dests — ca perechi { name, dest }, unde dest este un PageDest ({ page, view }). Acestea sunt aceleași ținte numite pe care un OutlineItem.Dest sau o adnotare de link le poate referenția prin nume în loc de un număr de pagină explicit.

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

Arbore de Structură Etichetată

Document.AutoTag() deduce și creează un /StructTreeRoot din aspectul paginii — titluri prin gruparea dimensiunii fontului, paragrafe prin blocuri de text, tabele prin geometria liniilor și decizii /Figure vs. /Artifact per imagine — și returnează un AutoTagReport cu numărări pentru fiecare tip de element. Document.GetStructTree() citește înapoi StructTreeRoot rezultat, sau null când documentul este neetichetat.

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

Conținutul adăugat după ce AutoTag() a rulat deja — de exemplu o pagină completată ulterior — nu este acoperit de acel pas și nu va fi etichetat dublu. StructTreeRoot.Append() și StructElement.MarkContent() sunt API de autor manual alături de cel euristic: Append() adaugă un element copil de tipul specificat, iar MarkContent() marchează o regiune de pagină ca aparținând acelui element.

Sfaturi și cele mai bune practici

• Rulați Document.AutoTag() o singură dată, după ce conținutul paginii este final — nu re-etichetează conținutul adăugat ulterior, așa că etichetați manual orice adăugat mai târziu cu StructTreeRoot.Append() / StructElement.MarkContent().
• Transmiteți opts.title către AutoTag() — setează și /ViewerPreferences /DisplayDocTitle, pe care PDF/UA îl solicită alături de titlul documentului.
• Un OutlineItem.Dest poate viza fie o pagină explicită, fie o destinație numită ({ name: '...' }) — folosiți destinații numite când numărul paginii țintă ar putea să se schimbe pe măsură ce conținutul se modifică.
• Verificați AddTOCResult.remainder când paginarea automată este dezactivată — o casetă a cuprinsului prea mică pentru fiecare intrare se oprește în tăcere în loc să depășească caseta.

Probleme comune

FAQ

Cum adaug semne de carte la un PDF?

Construiți un tablou de obiecte OutlineItem (Title, Dest, Children opțional) și transmiteți-l către Document.SetOutlines().

Poate un cuprins să se întindă pe mai multe pagini?

Da — transmiteți autoPaginate: true în opțiunile lui Page.AddTOC(), sau verificați AddTOCResult.remainder și apelați din nou AddTOC() pe o pagină nouă pentru ceea ce nu a încăput.

Cum fac un PDF accesibil (etichetat)?

Apelă Document.AutoTag(), care deduce titluri, paragrafe, tabele și figuri din aspectul paginii. Pentru conținut adăugat ulterior sau acolo unde rezultatul euristic trebuie corectat, folosește direct StructTreeRoot.Append() și StructElement.MarkContent().

Care este diferența dintre o destinație cu număr de pagină și o destinație denumită?

O destinație cu număr de pagină (PageDest) vizează o pagină explicită numerotată de la 1. O destinație denumită (NamedDest) vizează un nume pe care un vizualizator îl rezolvă prin tabelele de destinații denumite ale documentului — utilă când pagina țintă s-ar putea muta.

API Reference Rezumat

Vezi și:

• Aspose.PDF — Enterprise Documentation