Structure

Structure

Diese Seite behandelt die Dokumentennavigation und logische Struktur: Gliederungen (Lesezeichen), Inhaltsverzeichnisse, benannte Ziele und den getaggten Strukturbaum, der für Barrierefreiheit und Umbruch verwendet wird.

Gliederungen (Lesezeichen)

Document.GetOutlines() gibt den aktuellen Gliederungsbaum als OutlineItem[] zurück ([], wenn es keinen /Outlines gibt); Document.SetOutlines() ersetzt ihn — das Übergeben von [] entfernt die Gliederung vollständig. Jede OutlineItem hat ein Title, ein Dest (eine Seitenzahl oder ein benanntes Ziel), optional ein Children für Verschachtelung und Styling (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);

Inhaltsverzeichnis

Page.AddTOC() rendert eine Liste von TOCEntry-Objekten — jedes mit einem title und einer Ziel-page-Nummer — in ein Rechteck auf einer Seite, mit umbrochenen Titeln, Punktführungen und rechtsbündigen Seitenbeschriftungen. Es gibt ein AddTOCResult zurück, das meldet, wie viele Einträge gezeichnet wurden und, wenn das Feld zu klein ist, die remainder, die nicht passten.

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

Benannte Ziele

Document.GetNamedDestinations() gibt jede benannte Destination zurück — indem der /Names /Dests-Namensbaum und das Legacy-/Dests-Wörterbuch zusammengeführt werden — als { name, dest }-Paare, wobei dest ein PageDest ({ page, view }) ist. Dies sind dieselben benannten Ziele, die ein OutlineItem.Dest oder eine Linkannotation per Name anstelle einer expliziten Seitennummer referenzieren kann.

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

Getaggter Strukturbaum

Document.AutoTag() erschließt und erstellt ein /StructTreeRoot aus dem Seitenlayout — Überschriften durch Schriftgrößen-Clustering, Absätze durch Textblöcke, Tabellen durch Liniengeometrie und pro Bild /Figure-vs-/Artifact-Entscheidungen — und gibt ein AutoTagReport mit Zählungen für jede Elementart zurück. Document.GetStructTree() liest das resultierende StructTreeRoot aus, oder null, wenn das Dokument nicht getaggt ist.

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

Inhalte, die nach dem Durchlauf von AutoTag() hinzugefügt werden — beispielsweise eine nachträglich gefüllte Seite — werden von diesem Durchlauf nicht erfasst und werden nicht doppelt getaggt. StructTreeRoot.Append() und StructElement.MarkContent() sind die manuellen Autorisierungs-API neben der heuristischen: Append() fügt ein Kindelement eines bestimmten Typs hinzu, und MarkContent() markiert einen Seitenbereich als zu diesem Element gehörend.

Tipps und bewährte Praktiken

• Führen Sie Document.AutoTag() einmal aus, nachdem der Seiteninhalt final ist — es taggt Inhalte, die danach hinzugefügt werden, nicht erneut, daher sollten Sie alles, was später hinzugefügt wird, manuell mit StructTreeRoot.Append() / StructElement.MarkContent() taggen.
• Übergeben Sie opts.title an AutoTag() — es setzt außerdem /ViewerPreferences /DisplayDocTitle, das PDF/UA zusammen mit einem Dokumenttitel erfordert.
• Ein OutlineItem.Dest kann entweder eine explizite Seite oder eine benannte Destination ({ name: '...' }) anvisieren — verwenden Sie benannte Destinationen, wenn sich die Zielseitennummer durch Inhaltsänderungen verschieben kann.
• Prüfen Sie AddTOCResult.remainder, wenn die automatische Seitenerstellung deaktiviert ist — ein Inhaltsverzeichnis-Kasten, der für jeden Eintrag zu klein ist, hört stillschweigend auf zu zeichnen, anstatt den Kasten zu überlaufen.

Häufige Probleme

FAQ

Wie füge ich einer PDF Lesezeichen hinzu?

Erstellen Sie ein Array von OutlineItem-Objekten (Title, Dest, optional Children) und übergeben Sie es an Document.SetOutlines().

Kann ein Inhaltsverzeichnis mehrere Seiten umfassen?

Ja — übergeben Sie autoPaginate: true in den Optionen von Page.AddTOC(), oder prüfen Sie AddTOCResult.remainder und rufen Sie AddTOC() erneut auf einer neuen Seite für das, was nicht passte, auf.

Wie mache ich eine PDF barrierefrei (getaggt)?

Rufen Sie Document.AutoTag() auf, das Überschriften, Absätze, Tabellen und Abbildungen aus dem Seitenlayout ableitet. Für nachträglich hinzugefügten Inhalt oder wenn das heuristische Ergebnis korrigiert werden muss, verwenden Sie StructTreeRoot.Append() und StructElement.MarkContent() direkt.

Was ist der Unterschied zwischen einem Seitenzahlziel und einem benannten Ziel?

Ein Seitenzahlziel (PageDest) verweist auf eine explizite, bei 1 beginnende Seite. Ein benanntes Ziel (NamedDest) verweist auf einen Namen, den ein Betrachter über die benannten Zieltabellen des Dokuments auflöst – nützlich, wenn die Zielseite verschoben werden könnte.

API Reference Zusammenfassung

Siehe auch

• Aspose.PDF — Enterprise Documentation