Einleitung

Jede Fähigkeit in Aspose.PDF FOSS für TypeScript wird über zwei Klassen erreicht: Document und Page. Document verwaltet die Seitensammlung und alles, was dokumentbezogen ist — Metadaten, Lesezeichen, Seitenbeschriftungen und Speichern/Laden —, während jede Page in doc.Pages alles verwaltet, das sich auf diese eine Seite bezieht: Inhalt, Anmerkungen und Formularfelder. Sobald man diese beiden Klassen kennt, ist der Rest der Bibliotheksoberfläche — Konvertierung, Anmerkungen, Formulare, Sicherheit — im Grunde nur weitere Methoden auf denselben beiden Objekten.

Dieser Beitrag wirft einen genaueren Blick auf die Teile dieser Kernoberfläche, die der introductory post nur beiläufig erwähnt: das Zusammenstellen von Dokumenten aus anderen Dokumenten, das Erstellen von Seiten aus dem Nichts, das Hinzufügen eines Lesezeichenbaums zur Navigation und das Kennzeichnen von Inhalten für Barrierefreiheit. Alle vier sind einfache Methodenaufrufe — kein separates Modul zum Importieren, keine zusätzliche Abhängigkeit über das @asposefoss/pdf-Paket selbst.

Dies sind die Operationen, die auftreten, sobald eine PDF-Pipeline über “open one file, change it, save it” hinausgeht: das Kombinieren von Berichten aus mehreren Quellen zu einem Dokument, das programmgesteuerte Erzeugen von Seiten anstatt von einer Vorlage auszugehen, und das Erstellen einer navigierbaren und barrierefreien Ausgabe, die nicht nur visuell korrekt ist.

Was enthalten ist

Zusammenstellen und Neuordnen von Dokumenten

Document.Split() zerlegt ein Dokument in ein neues einseitiges Document pro Seite, in Seitenreihenfolge. Document.ExtractPages() kopiert eine gegebene Menge von 1-basierten Seitennummern in ein neues eigenständiges Document, in der angegebenen Reihenfolge — dieselbe Seite kann wiederholt werden. Seiten aus einem Dokument können auch in ein anderes kopiert werden: Document.Append() kopiert jede Seite eines Quell-Dokuments an das Ende des Ziel-Dokuments, und Document.InsertPage() kopiert eine einzelne Seite über Dokumente hinweg an einer bestimmten 1-basierten Position.

import { Document } from '@asposefoss/pdf';

const report = Document.OpenFile('report.pdf');

const parts = report.Split();                      // one Document per page
const chapter = report.ExtractPages([3, 4, 5]);     // subset (1-based, repeats allowed) as a new Document

const cover = Document.OpenFile('cover.pdf');
report.InsertPage(1, cover.Pages[0]);               // copy a single page across documents
report.Append(chapter);                             // copy chapter's pages onto report

report.WriteTo('assembled.pdf');

Mehrere Dokumente können ebenfalls in einem einzigen Aufruf mit Document.Merge() zu einem Dokument kombiniert werden, wobei ein neues Document aus Kopien jeder Seite jedes übergebenen Dokuments in Reihenfolge erstellt wird.

Seiten von Grund auf erstellen

Document.New() erstellt ein Dokument aus dem Nichts: null Seiten, wenn ein Format weggelassen wird, oder eine leere Seite des angegebenen PageFormat, wenn eines übergeben wird. Weitere leere Seiten stammen von Document.AddPage(), das außerdem ein PageFormat akzeptiert (oder ein vorhandenes Page, um dessen Größe zu übernehmen). Text wird mit Page.AddText() auf eine Seite gezeichnet und an einem (x, y)-Punkt im PDF-Benutzerraum positioniert.

import { Document, PageFormat } from '@asposefoss/pdf';

const doc = Document.New(PageFormat.A4);          // one blank A4 page
doc.Pages[0].AddText('Hello', 72, 720, { fontSize: 14 });
doc.AddPage(PageFormat.A4.landscape());           // append more as you go
doc.WriteTo('scratch.pdf');

Lesezeichen und Dokumentnavigation

Die Dokumentgliederung (die Lesezeichen-Leiste, die die meisten PDF-Reader neben der Seite anzeigen) wird mit Document.GetOutlines() ausgelesen und vollständig durch Document.SetOutlines() ersetzt, wobei beide mit einem Baum von OutlineItem-Werten arbeiten. Jeder OutlineItem enthält ein Title, ein Dest-Ziel und optional Children für verschachtelte Einträge sowie Anzeigehinweise wie Open (standardmäßig erweitert) und Bold.

import { Document, OutlineItem } from '@asposefoss/pdf';

const items: OutlineItem[] = [
  { Title: 'Introduction', Dest: { name: 'intro' } },
  {
    Title: 'Chapters',
    Open: true,
    Children: [
      { Title: 'Chapter 1', Dest: { name: 'ch1' } },
      { Title: 'Chapter 2', Dest: { name: 'ch2' } },
    ],
  },
];
doc.SetOutlines(items);

Auf diese Weise benannte Ziele ({ name: 'intro' }) werden über die benannte Ziel-Tabelle des Dokuments aufgelöst, die Document.GetNamedDestinations() und Document.SetNamedDestination() direkt verwalten, wenn ein Lesezeichen auf ein Ziel zeigen muss, das nicht an Seiteninhalt gebunden ist.

Strukturierter Text und Barrierefreiheits-Tagging

Document.GetStructTree() gibt den logischen Strukturbaum des Dokuments zurück (oder null, wenn das Dokument nicht getaggt ist), und Document.CreateStructTree() erstellt einen, wobei das Dokument als Tagged markiert wird. Sobald ein Strukturbaum existiert, gibt Page.GetStructuredText() den Text der Seite als TextBlock-Werte zurück – positionierte Fragmente, die bereits zu Zeilen und absatzähnlichen Blöcken gruppiert sind – was die Eingabe für einen manuellen Tagging-Durchgang ist: die Blöcke durchlaufen, entscheiden, welche Überschriften und welche Fließtext sind, und die entsprechenden Elemente dem Baum hinzufügen.

function handTagPage(doc: Document, page: Page, heading: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('handTagPage: 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(heading) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

Ein getaggter Strukturbaum ist die Grundlage, auf der nachgelagerte Funktionen aufbauen: Der semantische HTML Export fließt daraus um, anstatt zu einem einfachen heuristischen Layout zurückzufallen, und Document.ValidatePdfUa() prüft das Dokument gegen einen Teil der PDF/UA Barrierefreiheitsnorm, die davon abhängt, dass Tagging vorhanden ist.

Schnellstart

Installieren Sie das Paket, öffnen Sie dann ein Dokument, ziehen Sie einen Teil seiner Seiten heraus und setzen Sie ihn wieder zusammen und speichern Sie das Ergebnis:

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

const doc = Document.OpenFile('report.pdf');

const chapter = doc.ExtractPages([3, 4, 5]);   // subset (1-based, repeats allowed) as a new Document
const cover = Document.OpenFile('cover.pdf');

doc.InsertPage(1, cover.Pages[0]);             // copy a single page across documents
doc.Append(chapter);                           // copy chapter's pages onto doc

doc.WriteTo('assembled.pdf');

Unterstützte Formate

FormatErweiterungLesenSchreiben
PDFpdf✓✓
Markdownmd✓✓
SVGsvg✓✓
TIFFtiff✓✓
DOCXdocx—✓
HTMLhtml—✓
PNGpng—✓
EPUBepub—✓

Open Source & Lizenzierung

Aspose.PDF FOSS für TypeScript wird unter der MIT-Lizenz veröffentlicht, mit Quellcode, der auf GitHub veröffentlicht ist. Es gibt kein Evaluationswasserzeichen, keine Nutzungslimitierung und keine separate Lizenzdatei zu verwalten, und die Bibliothek kann in kommerziellen Produkten ohne Lizenzgebühren verwendet werden.

Das Paket befindet sich derzeit in Version 0.1.0, was die aktive Frühphasenentwicklung widerspiegelt. Node.js (>=22) ist die einzige Laufzeitanforderung, und das Paket hat keine weiteren Drittanbieterabhängigkeiten.

Erste Schritte

Verwandte Ressourcen