Facades API

Facade’s API

Een facade is een vereenvoudigde, taakgerichte wrapper rond de core Document / Page / Annotation objectmodel. In plaats van zelf de paginaboom te doorlopen, bind je een façade aan een bron-PDF, roep je een kleine reeks high-level methoden aan en sla je het resultaat op. Elke façade in Aspose::Pdf::Facades implementeert hetzelfde minimale contract gedefinieerd door IFacade (BindPdf, Close) en, waar de façade output produceert, ISaveableFacade (Save). De abstracte Facade and SaveableFacade basis-klassen bieden de standaard bind/close/save-implementatie waar de concrete editors hieronder op voortbouwen: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, en de formulier-gerichte FormEditor / FormFieldFacade paar.

Facade basis klassen en de bind/save levenscyclus

IFacade declareert BindPdf(srcFile) (ook overbelast om een in-memory Document te accepteren) en Close(). ISaveableFacade voegt Save(destFile) toe voor facades die output schrijven. Facade implementeert IFacade en maakt de gebonden Document() bloot zodat je kunt terugvallen op het kern-objectmodel wanneer een facade-methode niet biedt wat je nodig hebt; SaveableFacade breidt Facade uit met de Save implementatie. Elke concrete editor hieronder erft deze vorm, zodat hetzelfde bind → operate → save-patroon geldt voor alle Facade’s API.

Vullen en bewerken van AcroForm velden

FormEditor voegt AcroForm velden toe, verwijdert ze, hernoemt ze en verplaatst ze op een reeds gebonden document. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) maakt een nieuw veld aan van het opgegeven FieldType (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) op de gespecificeerde paginacoördinaten. RemoveField, RenameField, MoveField en SetFieldAttribute beheren bestaande velden, en SetFieldScript / AddFieldScript koppelen JavaScript acties. SubmitFlag (een SubmitFormFlag waarde — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments of Pdf) bepaalt hoe een verzendknop formulierdata post, en SetSubmitUrl stelt het doel-endpoint in.

Het visuele uiterlijk dat elk nieuw veld krijgt, wordt geregeld via FormEditor.Facade(), die een FormFieldFacade retourneert. Zijn Font eigenschap neemt een FontStyle waarde (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol en verwante varianten) aan, TextEncoding neemt een EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257) aan, en BorderStyle / BorderWidth stellen de rand van het veld in.

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

Outlines beheren met PdfBookmarkEditor

PdfBookmarkEditor maakt, extraheert, wijzigt en verwijdert PDF outline-items. CreateBookmarks() schrijft een Bookmarks collectie (elk item een Bookmark met Title, PageNumber, Action, Level, Open en ChildItems voor geneste outlines) in het gekoppelde document. ExtractBookmarks() leest de bestaande outline terug als een Bookmarks collectie, en DeleteBookmarks() — met een optioneel title filter — verwijdert items. ExportBookmarksToXML / ImportBookmarksWithXML voeren een outline via een XML bestand heen en terug, en ExtractBookmarksToHTML / ExportBookmarksToHtml renderen de outline als een HTML pagina.

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

Annotaties bewerken met PdfAnnotationEditor

PdfAnnotationEditor flatten en importeert annotaties over het hele document. FlatteningAnnotations() voegt annotaties samen in de paginacontent-stream zodat ze worden weergegeven als statische inhoud in plaats van interactieve objecten; de overload die een start/end paginabereik en een annotatietype accepteert, beperkt de bewerking. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf halen annotaties binnen uit externe FDF/XFDF bestanden, en DeleteAnnotations() (of DeleteAnnotations(annotType) voor een enkel type) verwijdert ze.

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

Paginainhoud herschrijven met PdfContentEditor

PdfContentEditor bewerkt de content-stream van een al gegenereerde pagina in plaats van de pagina opnieuw op te bouwen. ReplaceText(srcText, destText) zoekt en vervangt overeenkomende tekst door het hele document, met overloads die de vervanging beperken tot één pagina. ReplaceImage(pageNum, imageNum, fileName) en DeleteImage(pageNum, imageNum) wisselen of verwijderen een bestaand image XObject. DeleteStampById / HideStampById / ShowStampById / MoveStampById beheren stempel-objecten op een pagina (de onderliggende inhoud van een stempel is of Form of Image, volgens de StampType enum), en AddDocumentAdditionalAction / AddDocumentAttachment voegen document-niveau JavaScript acties en bestandsbijlagen toe.

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

Tekst en bijlagen extraheren met PdfExtractor

PdfExtractor kan worden gebonden ofwel met BindPdf of direct worden geconstrueerd vanuit een reeds geopende Document. ExtractText() gevolgd door HasNextPageText() / GetNextPageText(outputFile) doorloopt het document pagina voor pagina. Voor ingebedde bestanden, GetAttachNames() lijst de aanwezige bijlagen en GetAttachment( outputPath) schrijft de volgende naar de schijf:

#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) extraheren ingesloten rasterafbeeldingen op dezelfde manier als GetNextPageText pagina’s doorloopt.

Bestanden samenstellen en splitsen met PdfFileEditor.

PdfFileEditor werkt op bestandspaden in plaats van een gebonden Document, zodat elke methode invoer-/uitvoernaam direct accepteert. Concatenate (en de niet-gooiende TryConcatenate) voegt twee of meer bestanden samen; Append voegt een paginabereik van het ene bestand in het andere in; Extract haalt een paginabereik of enkele pagina in een nieuw bestand; Delete verwijdert een pagina; en SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks delen een document op een pagina, per pagina, of in blokken van vaste grootte. MakeBooklet en MakeNUp herschikken pagina’s voor boekje- of N-up-afdrukken, en ResizeContents / AddMargins / AddPageBreak passen de paginageometrie over een bestand aan. De meeste bewerkingen hebben een tegenhanger met het Try-voorvoegsel die false retourneert in plaats van een uitzondering te gooien bij falen.

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

Pagina’s renderen naar afbeeldingen met PdfConverter.

PdfConverter renderen gebonden documentpagina’s naar rasterformaten. DoConvert() bereidt het paginabereik (StartPage / EndPage) voor op iteratie; HasNextImage () / GetNextImage(outputFile) stappen vervolgens één voor één door de pagina’s. SaveAsTIFF schrijft het volledige bereik naar één multi-page TIFF, met overloads voor resolutie, compressie en TiffSettings. RenderingOptions en Resolution regelen de rasterisatie-kwaliteit, en ImageMergeMode (Vertical, Horizontal, Center) bepaalt hoe meerdere gerenderde pagina-afbeeldingen worden gecombineerd wanneer een aanroeper ze tot één afbeelding samenvoegt.

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

Documenten versleutelen met PdfFileSecurity.

PdfFileSecurity bindt een bronbestand en past versleuteling toe of verwijdert deze. EncryptFile(userPassword, ownerPassword, privilege, keySize) versleutelt met een DocumentPrivilege (gecreëerd met de standaardconstructor en booleaanse setters zoals AllowPrint, AllowCopy, AllowModifyContents) en een KeySize (x40, x128 of x256); de overload die een vijfde cipher-argument accepteert selecteert expliciet de Algorithm (RC4 of AES). DecryptFile( ownerPassword), ChangePassword en SetPrivilege dekken de overige wachtwoord-beheerscenario’s, elk met een niet-gooiende Try-voorvoegsel-variant.

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

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

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

Ondertekenen en verifiëren met PdfFileSignature.

PdfFileSignature tekent, certificeert en inspecteert digitale handtekeningen op een gebonden document. Sign(sigName, reason, contact, location, signature) past een nieuwe handtekening toe op een bestaand handtekeningenveld; Certify past een certificerende handtekening toe. GetSignatureNames(onlyEmpty) en GetBlankSignatureNames() geven de handtekeningenvelden van het document terug als SignatureName waarden, en VerifySignature(sigName) / IsCoversWholeDocument (sigName) controleren geldigheid en dekking. RemoveSignature en RemoveSignatures() verwijderen bestaande handtekeningen, en SetCertificate(pfxFile, password) levert de ondertekeningsreferentie voordat Sign wordt aangeroepen.

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

Koppen, voetteksten en paginanummers stampen met PdfFileStamp

PdfFileStamp legt herhalende inhoud over op elke pagina van een gebonden bestand. AddPageNumber(format) stempelt een paginanummerlabel met een startnummer en optionele expliciete coördinaten; AddHeader(text, topMargin) en AddFooter(text, bottomMargin) voegen terugkerende kop-/voettekst toe op een gegeven marge, met overloads voor linker-/rechtermarge. KeepSecurity behoudt eventuele bestaande encryptie op het uitvoerbestand, en Close() finaliseert en vrijgeeft het gebonden document.

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

Documentinformatie lezen en schrijven met PdfFileInfo

PdfFileInfo leest en herschrijft de klassieke PDF /Info dictionary en basis per-pagina geometrie zonder het volledige objectmodel te openen. Author, Title, Subject, Keywords, CreationDate en ModDate zijn lees-/schrijfeigenschappen; Producer en GetPdfVersion() zijn alleen-lees. GetPageWidth, GetPageHeight en GetPageRotation geven per-pagina geometrie terug op paginanummer, en IsEncrypted() / HasOpenPassword() / HasEditPassword() rapporteren de beschermingsstatus van het document. SaveNewInfo(outputFile) schrijft de wijzigingen terug.

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

Pagina’s herpositioneren met PdfPageEditor

PdfPageEditor verplaatst, schaalt en roteert paginainhoud als een blok. MovePosition(offsetX, offsetY) verschuift inhoud op de pagina’s die zijn geselecteerd door ProcessPages; Zoom schaalt deze. Alignment (een AlignmentType — Left, Center of Right, elk verkregen via de bijbehorende statische methode) en VerticalAlignment (een VerticalAlignmentType — Top, Center, Bottom) bepalen hoe inhoud wordt gepositioneerd binnen de doel-PageSize zodra ApplyChanges() wordt uitgevoerd. GetPageRotation leest de huidige rotatie van een pagina in graden.

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

XMP-metadata beheren met PdfXmpMetadata

PdfXmpMetadata is een map-achtige façade over het XMP-pakket van een document. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) en TryGetValue(key, value) beheren individuele items; Keys() en Values() enumereren het volledige pakket. RegisterNamespaceURI(prefix, namespaceURI) declareert een aangepaste XMP-namespace voordat je er eigenschappen aan toevoegt. Bekende eigenschapsnamen staan opgesomd in DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails en andere), en PropertyFlag (ReadOnly, Required, NoExport) beschrijft de schema-beperkingen van een geregistreerde eigenschap.

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

Tips en best practices

• Elke façade volgt dezelfde BindPdf (of een constructor die een bestandsnaam accepteert) → opereren → Save/Close-volgorde — het leren van één façade wordt direct toepasbaar op de volgende.
• Geef de Try-voorvoegsel-methoden op PdfFileEditor en PdfFileSecurity de voorkeur bij het verwerken van bestanden van een onbetrouwbare of onvoorspelbare bron — ze retourneren false bij falen in plaats van een uitzondering te werpen.
• PdfFileEditor-methoden nemen bestands-paden, niet een gebonden Document — je hoeft het bronbestand niet zelf te openen voordat je Concatenate, Extract of SplitFromFirst aanroept.
• Façades wikkelen het kern-objectmodel in plaats van het te vervangen: Facade onthult de onderliggende Document() voor gevallen die een façade-methode niet dekt.
• Roep Close() aan (of laat de façade buiten scope gaan, waar ondersteund) zodra je klaar bent met een gebonden document om de onderliggende bestands-handle vrij te geven.

Veelvoorkomende problemen

FAQ

Wat is het verschil tussen een facade en de core Document API?

Facades bieden een kleine, taakgerichte methodesurface voor één taak — een formulier invullen, bestanden samenvoegen, pagina’s stempelen. De core API (Document, Page, Annotation) geeft volledige toegang tot elk PDF-object. Facades die Document() blootstellen (via de Facade basisklasse) laten je terugvallen op het core-model voor alles wat een facade-methode niet dekt.

Moet ik BindPdf aanroepen vóór elke facade-methode?

Ja, voor facades die IFacade implementeren — BindPdf (of een gelijkwaardige constructor-overload, zoals bij PdfExtractor(doc)) moet worden uitgevoerd vóór elke operatie die het gekoppelde document leest of wijzigt.

Kunnen PdfFileEditor-operaties aaneengeschakeld worden?

Elke PdfFileEditor-methode leest zijn eigen invoerbestand en schrijft zijn eigen uitvoerbestand, dus je schakelt operaties aaneen door het uitvoerbestand van de ene methode als invoerbestand voor de volgende aan te geven — bijvoorbeeld Concatenate naar merged.pdf, dan Extract van merged.pdf.

Welke facades ondersteunen een niet-gooiende foutmodus?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, en verwante Try* methoden) en PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) bieden beide Try-geprefixeerde alternatieven die bool teruggeven in plaats van een uitzondering te werpen.

API Reference Samenvatting

Zie ook

• Aspose.PDF — Enterprise Documentation