Fassaden API

Fassaden API

A facade ist ein vereinfachter, aufgabenorientierter Wrapper über dem Kern Document / Page / Annotation Objektmodell. Anstatt den Seitenbaum selbst zu durchlaufen, binden Sie eine Fassade an ein Quell-PDF, rufen eine kleine Menge hoch-leveliger Methoden auf und speichern das Ergebnis. Jede Fassade in Aspose::Pdf::Facades implementiert denselben minimalen Vertrag, der definiert ist durch IFacade (BindPdf, Close) und, wo die Fassade Ausgaben erzeugt, ISaveableFacade (Save). Der abstrakte Facade and SaveableFacade Basisklassen bieten die Standard-Bind/Close/Save-Implementierung, auf der die untenstehenden konkreten Editoren aufbauen: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, und die formular-fokussierte FormEditor / FormFieldFacade Paar.

Fassade-Basisklassen und der Bind/Save-Lebenszyklus

IFacade deklariert BindPdf(srcFile) (auch überladen, um ein im Speicher befindliches Document zu akzeptieren) und Close(). ISaveableFacade fügt Save(destFile) für Fassaden hinzu, die Ausgabe schreiben. Facade implementiert IFacade und stellt die gebundene Document() bereit, sodass Sie zum Kern-Objektmodell zurückkehren können, wenn eine Fassaden-Methode nicht abdeckt, was Sie benötigen; SaveableFacade erweitert Facade mit der Save-Implementierung. Jeder konkrete Editor unten erbt diese Struktur, sodass das gleiche Bind → Operate → Save-Muster über das gesamte Fassaden API gilt.

Ausfüllen und Bearbeiten von AcroForm-Feldern

FormEditor fügt AcroForm-Felder zu einem bereits gebundenen Dokument hinzu, entfernt, benennt um und repositioniert sie. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) erstellt ein neues Feld des angegebenen FieldType (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) an den spezifizierten Seitenkoordinaten. RemoveField, RenameField, MoveField und SetFieldAttribute verwalten vorhandene Felder, und SetFieldScript / AddFieldScript hängen JavaScript-Aktionen an. SubmitFlag (ein SubmitFormFlag-Wert — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments oder Pdf) steuert, wie ein Submit-Button Formulardaten sendet, und SetSubmitUrl legt den Ziel-Endpunkt fest.

Das visuelle Erscheinungsbild jedes neuen Feldes wird über FormEditor.Facade() gesteuert, das ein FormFieldFacade zurückgibt. Seine Font-Eigenschaft akzeptiert einen FontStyle-Wert (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol und verwandte Varianten), TextEncoding nimmt ein EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257) entgegen, und BorderStyle / BorderWidth setzen den Rand des Feldes.

FormEditor editor;
editor.SrcFileName("template.pdf");
editor.DestFileName("output.pdf");
editor.AddField(FieldType::Text, "FirstName", 1, 100, 700, 300, 720);
editor.SetFieldAttribute("FirstName", AnnotationFlags::Print);
editor.Save();

Verwalten von Outlines mit PdfBookmarkEditor

PdfBookmarkEditor erstellt, extrahiert, ändert und entfernt PDF-Outline-Einträge. CreateBookmarks() schreibt eine Bookmarks-Sammlung (jeder Eintrag ist ein Bookmark mit Title, PageNumber, Action, Level, Open und ChildItems für verschachtelte Outlines) in das gebundene Dokument. ExtractBookmarks() liest das vorhandene Outline wieder aus als eine Bookmarks-Sammlung, und DeleteBookmarks() — mit einem optionalen title-Filter — entfernt Einträge. ExportBookmarksToXML / ImportBookmarksWithXML führen ein Outline im Round-Trip durch eine XML-Datei, und ExtractBookmarksToHTML / ExportBookmarksToHtml rendern das Outline als eine HTML-Seite.

PdfBookmarkEditor editor;
editor.BindPdf("input.pdf");
Bookmarks bookmarks = editor.ExtractBookmarks();
editor.DeleteBookmarks("Draft");
editor.Save("output.pdf");

Bearbeiten von Anmerkungen mit PdfAnnotationEditor

PdfAnnotationEditor flacht Anmerkungen ab und importiert sie im gesamten Dokument. FlatteningAnnotations() fügt Anmerkungen in den Seiteninhaltsstrom ein, sodass sie als statischer Inhalt statt als interaktive Objekte gerendert werden; die Überladung, die einen start/end-Seitenbereich und einen Anmerkungstyp annimmt, begrenzt die Operation. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf holen Anmerkungen aus externen FDF/XFDF-Dateien, und DeleteAnnotations() (oder DeleteAnnotations(annotType) für einen einzelnen Typ) entfernt sie.

PdfAnnotationEditor editor;
editor.BindPdf("commented.pdf");
editor.FlatteningAnnotations();
editor.Save("flattened.pdf");

Umschreiben von Seiteninhalt mit PdfContentEditor

PdfContentEditor bearbeitet den Inhaltsstrom einer bereits erzeugten Seite, anstatt die Seite neu zu erstellen. ReplaceText(srcText, destText) findet und ersetzt passenden Text im gesamten Dokument, mit Überladungen, die den Ersatz auf eine einzelne Seite beschränken. ReplaceImage(pageNum, imageNum, fileName) und DeleteImage(pageNum, imageNum) tauschen ein vorhandenes Bild-XObject aus oder entfernen es. DeleteStampById / HideStampById / ShowStampById / MoveStampById verwalten Stempelobjekte auf einer Seite (der zugrunde liegende Inhalt eines Stempels ist entweder Form oder Image, gemäß dem StampType-Enum), und AddDocumentAdditionalAction / AddDocumentAttachment hängen dokumentenweite JavaScript-Aktionen und Dateianhänge an.

PdfContentEditor editor;
editor.BindPdf("template.pdf");
editor.ReplaceText("{{CustomerName}}", "Jane Doe");
editor.Save("output.pdf");

Extrahieren von Text und Anhängen mit PdfExtractor

PdfExtractor kann entweder mit BindPdf gebunden werden oder direkt aus einem bereits geöffneten Document konstruiert werden. ExtractText() gefolgt von HasNextPageText() / GetNextPageText(outputFile) durchläuft das Dokument Seite für Seite. Für eingebettete Dateien listet GetAttachNames() die vorhandenen Anhänge auf und GetAttachment( outputPath) schreibt den nächsten auf die Festplatte:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/facades/pdf_extractor.hpp>
#include <iostream>

int main() {
    Aspose::Pdf::Document doc("attachments.pdf");
    Aspose::Pdf::Facades::PdfExtractor extractor(doc);

    auto names = extractor.GetAttachNames();
    std::cout << "Attachments found: " << names.size() << "\n";

    if (!names.empty()) {
        extractor.GetAttachment("extracted-attachment.bin");
    }
}

ExtractImage() / HasNextImage() / GetNextImage(outputFile) extrahieren eingebettete Rasterbilder auf die gleiche Art, wie GetNextPageText Seiten durchblättert.

Dateien zusammenführen und teilen mit PdfFileEditor

PdfFileEditor arbeitet mit Dateipfaden statt mit einem gebundenen Document, sodass jede Methode Eingabe-/Ausgabedateinamen direkt verwendet. Concatenate (und das nicht-werfende TryConcatenate) fügt zwei oder mehr Dateien zusammen; Append fügt einen Seitenbereich von einer Datei in eine andere ein; Extract extrahiert einen Seitenbereich oder eine einzelne Seite in eine neue Datei; Delete entfernt eine Seite; und SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks teilen ein Dokument an einer Seite, seitenweise oder in gleichgroße Abschnitte. MakeBooklet und MakeNUp ordnen Seiten für Broschüren- oder N-up-Druck neu an, und ResizeContents / AddMargins / AddPageBreak passen die Seitengeometrie über eine Datei hinweg an. Die meisten Operationen haben ein Try-präfixiertes Gegenstück, das false zurückgibt, anstatt bei einem Fehler eine Ausnahme zu werfen.

PdfFileEditor editor;
editor.Concatenate("part1.pdf", "part2.pdf", "merged.pdf");
editor.Extract("merged.pdf", 1, 3, "first-three-pages.pdf");

Rendern von Seiten zu Bildern mit PdfConverter

PdfConverter rendert gebundene Dokumentseiten in Rasterformate. DoConvert() bereitet den Seitenbereich (StartPage / EndPage) für die Iteration vor; HasNextImage () / GetNextImage(outputFile) gehen dann die Seiten einzeln durch. SaveAsTIFF schreibt den gesamten Bereich in ein einzelnes mehrseitiges TIFF, mit Überladungen für Auflösung, Kompression und TiffSettings. RenderingOptions und Resolution steuern die Rasterisierungsqualität, und ImageMergeMode (Vertical, Horizontal, Center) bestimmt, wie mehrere gerenderte Seitenbilder kombiniert werden, wenn ein Aufrufer sie zu einem Bild zusammenführt.

PdfConverter converter;
converter.BindPdf("report.pdf");
converter.Resolution(Aspose::Pdf::Devices::Resolution(150));
converter.DoConvert();
while (converter.HasNextImage()) {
    converter.GetNextImage("page.png");
}

Verschlüsseln von Dokumenten mit PdfFileSecurity

PdfFileSecurity bindet eine Quelldatei und wendet Verschlüsselung an oder entfernt sie. EncryptFile(userPassword, ownerPassword, privilege, keySize) verschlüsselt mit einem DocumentPrivilege (erstellt mit dem Standardkonstruktor und booleschen Settern wie AllowPrint, AllowCopy, AllowModifyContents) und einem KeySize (x40, x128 oder x256); die Überladung, die ein fünftes cipher-Argument annimmt, wählt das Algorithm (RC4 oder AES) explizit aus. DecryptFile( ownerPassword), ChangePassword und SetPrivilege decken die übrigen Passwortverwaltungsfälle ab, jeweils mit einer nicht-werfenden Try-präfixierten Variante.

PdfFileSecurity security;
security.BindPdf("input.pdf");

DocumentPrivilege privilege;
privilege.AllowPrint(true);
privilege.AllowModifyContents(false);

security.EncryptFile("user-pass", "owner-pass", privilege, KeySize::x256);

Signieren und Verifizieren mit PdfFileSignature

PdfFileSignature signiert, zertifiziert und prüft digitale Signaturen in einem gebundenen Dokument. Sign(sigName, reason, contact, location, signature) legt eine neue Signatur in ein bestehendes Signaturfeld; Certify legt eine zertifizierende Signatur an. GetSignatureNames(onlyEmpty) und GetBlankSignatureNames() geben die Signaturfelder des Dokuments als SignatureName-Werte zurück, und VerifySignature(sigName) / IsCoversWholeDocument (sigName) prüfen Gültigkeit und Abdeckung. RemoveSignature und RemoveSignatures() entfernen vorhandene Signaturen, und SetCertificate(pfxFile, password) stellt die Signatur-Anmeldeinformationen bereit, bevor Sign aufgerufen wird.

PdfFileSignature signature;
signature.BindPdf("contract.pdf");
signature.SetCertificate("signing-cert.pfx", "cert-password");
bool signed_ok = signature.ContainsSignature();
signature.Save();

Kopf-, Fuß- und Seitenzahlen mit PdfFileStamp stempeln.

PdfFileStamp legt wiederkehrenden Inhalt auf jeder Seite einer gebundenen Datei als Overlay an. AddPageNumber(format) stempelt ein Seitenzahl-Label mit einer Startzahl und optional expliziten Koordinaten; AddHeader(text, topMargin) und AddFooter(text, bottomMargin) fügen wiederkehrenden Kopf-/Fußzeilentext an einem angegebenen Rand hinzu, mit Überladungen für linken/rechten Rand. KeepSecurity bewahrt jede vorhandene Verschlüsselung der Ausgabedatei, und Close() finalisiert und gibt das gebundene Dokument frei.

PdfFileStamp stamp;
stamp.InputFile("input.pdf");
stamp.OutputFile("stamped.pdf");
stamp.AddPageNumber("Page # of #", 1);
stamp.Close();

Lesen und Schreiben von Dokumentinformationen mit PdfFileInfo.

PdfFileInfo liest und überschreibt das klassische PDF /Info-Wörterbuch sowie die grundlegende Geometrie pro Seite, ohne das vollständige Objektmodell zu öffnen. Author, Title, Subject, Keywords, CreationDate und ModDate sind Lese-/Schreib-Eigenschaften; Producer und GetPdfVersion() sind nur lesbar. GetPageWidth, GetPageHeight und GetPageRotation geben die Geometrie pro Seite anhand der Seitennummer zurück, und IsEncrypted() / HasOpenPassword() / HasEditPassword() melden den Schutzstatus des Dokuments. SaveNewInfo(outputFile) schreibt die Änderungen zurück.

PdfFileInfo info;
info.BindPdf(document);
info.Title("Updated Report Title");
info.SaveNewInfo("output.pdf");

Neupositionieren von Seiten mit PdfPageEditor.

PdfPageEditor verschiebt, skaliert und rotiert Seiteninhalt als Block. MovePosition(offsetX, offsetY) verschiebt Inhalt auf den durch ProcessPages ausgewählten Seiten; Zoom skaliert ihn. Alignment (ein AlignmentType – Left, Center oder Right, jeweils über die passende statische Methode erhalten) und VerticalAlignment (ein VerticalAlignmentType – Top, Center, Bottom) steuern, wie Inhalt innerhalb des Ziel-PageSize positioniert wird, sobald ApplyChanges() ausgeführt wird. GetPageRotation liest die aktuelle Rotation einer Seite in Grad.

PdfPageEditor editor;
editor.BindPdf("input.pdf");
editor.Alignment(AlignmentType::Center());
editor.MovePosition(0, -20);
editor.ApplyChanges();

Verwalten von XMP-Metadaten mit PdfXmpMetadata.

PdfXmpMetadata ist eine kartenähnliche Fassade über dem XMP-Paket eines Dokuments. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) und TryGetValue(key, value) verwalten einzelne Einträge; Keys() und Values() enumerieren das gesamte Paket. RegisterNamespaceURI(prefix, namespaceURI) deklariert einen benutzerdefinierten XMP-Namespace, bevor Sie Eigenschaften darin hinzufügen. Bekannte Eigenschaftsnamen sind in DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails und andere) aufgeführt, und PropertyFlag (ReadOnly, Required, NoExport) beschreibt die Schema-Beschränkungen einer registrierten Eigenschaft.

PdfXmpMetadata xmp;
xmp.BindPdf(document);
xmp.Add("dc:creator", "Report Generator");
xmp.Save("output.pdf");

Tipps und bewährte Vorgehensweisen

• Jede Fassade folgt dem gleichen BindPdf (oder einem konstruktor, der einen Dateinamen entgegennimmt) → ausführen → Save/Close Sequenz — das Erlernen einer Fassade überträgt sich direkt auf die nächste.
• Bevorzugen Sie die mit Try vorangestellten Methoden auf PdfFileEditor und PdfFileSecurity beim Verarbeiten von Dateien aus einer nicht vertrauenswürdigen oder unvorhersehbaren Quelle — sie geben false bei einem Fehler zurück, anstatt eine Ausnahme zu werfen.
• PdfFileEditor-Methoden erwarten Dateipfade, nicht ein gebundenes Document — Sie müssen die Quelldatei nicht selbst öffnen, bevor Sie Concatenate, Extract oder SplitFromFirst aufrufen.
• Fassaden umhüllen das Kern-Objektmodell, anstatt es zu ersetzen: Facade legt das zugrunde liegende Document() offen für Fälle, die von einer Fassaden-Methode nicht abgedeckt werden.
• Rufen Sie Close() auf (oder lassen Sie die Fassade, wo unterstützt, aus dem Gültigkeitsbereich verschwinden), sobald Sie mit einem gebundenen Dokument fertig sind, um den zugrunde liegenden Dateihandle freizugeben.

Häufige Probleme

FAQ

Was ist der Unterschied zwischen einer Fassade und dem Kern-Dokument API?

Fassaden bieten eine kleine, aufgabenorientierte Methodenschnittstelle für einen einzelnen Vorgang — ein Formular ausfüllen, Dateien zusammenführen, Seiten versehen. Das Kern-API (Document, Page, Annotation) ermöglicht vollständigen Zugriff auf jedes PDF-Objekt. Fassaden, die Document() (über die Basisklasse Facade) freigeben, erlauben es, zum Kernmodell zurückzukehren, wenn eine Fassaden-Methode etwas nicht abdeckt.

Muss ich BindPdf vor jeder Fassaden-Methode aufrufen?

Ja, bei Fassaden, die IFacade implementieren — BindPdf (oder eine entsprechende Konstruktor-Überladung, wie bei PdfExtractor(doc)) muss vor jeder Operation ausgeführt werden, die das gebundene Dokument liest oder verändert.

Können PdfFileEditor-Operationen verkettet werden?

Jede PdfFileEditor-Methode liest ihre eigene Eingabedatei und schreibt ihre eigene Ausgabedatei, sodass Sie Operationen verketten, indem Sie die Ausgabedatei einer Methode als Eingabedatei der nächsten Aufrufes verwenden — zum Beispiel Concatenate in merged.pdf, dann Extract aus merged.pdf.

Welche Fassaden unterstützen einen nicht-auswerfenden Fehlermodus?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst und verwandte Try* Methoden) und PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) bieten beide Try-gekennzeichnete Alternativen, die bool zurückgeben, anstatt zu werfen.

API Reference Zusammenfassung

Siehe auch

• Aspose.PDF — Enterprise Documentation