Fasader API

Fasader API

A facade är ett förenklat, uppgiftsorienterat omslag över kärnan Document / Page / Annotation objektmodell. Istället för att gå igenom sidträdet själv, binder du en fasad till en källa-PDF, anropar en liten uppsättning hög-nivå-metoder och sparar resultatet. Varje fasad i Aspose::Pdf::Facades implementerar samma minimala kontrakt som definieras av IFacade (BindPdf, Close) och, där fasaden producerar utdata, ISaveableFacade (Save). Den abstrakta Facade and SaveableFacade bas-klasserna tillhandahåller standard-bind/close/save-implementationen som de konkreta redigerarna nedan bygger på: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, och den formulär-fokuserade FormEditor / FormFieldFacade par.

Facadens basklasser och bind/save-livscykeln

IFacade deklarerar BindPdf(srcFile) (även överlagrad för att acceptera ett minnes-in-Document) och Close(). ISaveableFacade lägger till Save(destFile) för facader som skriver utdata. Facade implementerar IFacade och exponerar den bundna Document() så att du kan återgå till kärn-objektmodellen när en facademetod inte täcker det du behöver; SaveableFacade utökar Facade med Save-implementationen. Varje konkret redigerare nedan ärver denna struktur, så samma bind → operate → save-mönster gäller för hela Fasader API.

Fyllning och redigering av AcroForm-fält

FormEditor lägger till, tar bort, byter namn på och ompositionerar AcroForm-fält i ett redan bundet dokument. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) skapar ett nytt fält av den angivna FieldType (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) på de specificerade sidkoordinaterna. RemoveField, RenameField, MoveField och SetFieldAttribute hanterar befintliga fält, och SetFieldScript / AddFieldScript fäster JavaScript-åtgärder. SubmitFlag (ett SubmitFormFlag-värde — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments eller Pdf) styr hur en skicka-knapp postar formulärdata, och SetSubmitUrl anger mål-endpointen.

Det visuella utseendet som varje nytt fält får styrs via FormEditor.Facade(), som returnerar en FormFieldFacade. Dess Font-egenskap tar ett FontStyle-värde (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol och relaterade varianter), TextEncoding tar en EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), och BorderStyle / BorderWidth sätter fältets kant.

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

Hantera dispositioner med PdfBookmarkEditor

PdfBookmarkEditor skapar, extraherar, modifierar och tar bort PDF-dispositionsposter. CreateBookmarks() skriver en Bookmarks-samling (varje post är ett Bookmark med Title, PageNumber, Action, Level, Open och ChildItems för nästlade dispositioner) till det bundna dokumentet. ExtractBookmarks() läser den befintliga dispositionen tillbaka som en Bookmarks-samling, och DeleteBookmarks() — med ett valfritt title-filter — tar bort poster. ExportBookmarksToXML / ImportBookmarksWithXML gör en rundresa för en disposition genom en XML-fil, och ExtractBookmarksToHTML / ExportBookmarksToHtml renderar dispositionen som en HTML-sida.

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

Redigera annotationer med PdfAnnotationEditor

PdfAnnotationEditor plattar till och importerar annotationer i hela dokumentet. FlatteningAnnotations() slår samman annotationer i sidans innehållsström så att de renderas som statiskt innehåll istället för interaktiva objekt; överlagringen som tar ett start/end sidintervall och en annotationstyp begränsar operationen. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf hämtar in annotationer från externa FDF/XFDF-filer, och DeleteAnnotations() (eller DeleteAnnotations(annotType) för en enda typ) tar bort dem.

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

Skriva om sidinnehåll med PdfContentEditor

PdfContentEditor redigerar en redan genererad sidas innehållsström istället för att bygga om sidan. ReplaceText(srcText, destText) hittar och ersätter matchande text i hela dokumentet, med överlagringar som begränsar ersättningen till en enskild sida. ReplaceImage(pageNum, imageNum, fileName) och DeleteImage(pageNum, imageNum) byter eller tar bort ett befintligt bild-XObject. DeleteStampById / HideStampById / ShowStampById / MoveStampById hanterar stämpelobjekt på en sida (stämplingens underliggande innehåll är antingen Form eller Image, enligt StampType-enumerationen), och AddDocumentAdditionalAction / AddDocumentAttachment bifogar dokumentnivå-JavaScript-åtgärder och filbilagor.

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

Extrahera text och bilagor med PdfExtractor

PdfExtractor kan bindas antingen med BindPdf eller konstrueras direkt från en redan öppen Document. ExtractText() följt av HasNextPageText() / GetNextPageText(outputFile) går igenom dokumentet sida för sida. För inbäddade filer listar GetAttachNames() de befintliga bilagorna och GetAttachment( outputPath) skriver den nästa till disk:

#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) extraherar inbäddade rasterbilder på samma sätt som GetNextPageText går igenom sidor.

Sammansätta och dela upp filer med PdfFileEditor

PdfFileEditor arbetar på filsökvägar snarare än på ett bundet Document, så varje metod tar in-/utdatafilnamn direkt. Concatenate (och den icke-kastande TryConcatenate) slår ihop två eller fler filer; Append infogar ett sidintervall från en fil till en annan; Extract extraherar ett sidintervall eller en enskild sida till en ny fil; Delete tar bort en sida; och SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks delar ett dokument vid en sida, sida för sida, eller i fasta storleksdelar. MakeBooklet och MakeNUp omarrangerar sidor för häfte- eller N-up-utskrift, och ResizeContents / AddMargins / AddPageBreak justerar sidgeometri i en fil. De flesta operationer har en Try-prefixad motsvarighet som returnerar false istället för att kasta vid fel.

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

Rendera sidor till bilder med PdfConverter

PdfConverter renderar bundna dokumentsidor till rasterformat. DoConvert() förbereder sidintervallet (StartPage / EndPage) för iteration; HasNextImage () / GetNextImage(outputFile) går sedan igenom sidorna en i taget. SaveAsTIFF skriver hela intervallet till en enda flersidig TIFF, med överladdningar för upplösning, kompression och TiffSettings. RenderingOptions och Resolution styr rasteriseringskvaliteten, och ImageMergeMode (Vertical, Horizontal, Center) bestämmer hur flera renderade sidbilder kombineras när en anropar slår ihop dem till en bild.

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

Kryptera dokument med PdfFileSecurity

PdfFileSecurity binder en källfil och tillämpar eller tar bort kryptering. EncryptFile(userPassword, ownerPassword, privilege, keySize) krypterar med en DocumentPrivilege (byggd med standardkonstruktorn och booleska setternas som AllowPrint, AllowCopy, AllowModifyContents) och en KeySize (x40, x128 eller x256); överladdningen som tar ett femte cipher-argument väljer Algorithm (RC4 eller AES) explicit. DecryptFile( ownerPassword), ChangePassword och SetPrivilege täcker de återstående lösenordshanteringsfallen, var och en med en icke-kastande Try-prefixad variant.

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

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

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

Signera och verifiera med PdfFileSignature

PdfFileSignature signerar, certifierar och granskar digitala signaturer på ett bundet dokument. Sign(sigName, reason, contact, location, signature) lägger till en ny signatur i ett befintligt signaturfält; Certify lägger till en certifierande signatur. GetSignatureNames(onlyEmpty) och GetBlankSignatureNames() returnerar dokumentets signaturfält som SignatureName-värden, och VerifySignature(sigName) / IsCoversWholeDocument (sigName) kontrollerar giltighet och täckning. RemoveSignature och RemoveSignatures() tar bort befintliga signaturer, och SetCertificate(pfxFile, password) tillhandahåller signeringsuppgiften innan Sign anropas.

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

Stämplar rubriker, sidfötter och sidnummer med PdfFileStamp

PdfFileStamp överlagrar återkommande innehåll på varje sida i en bunden fil. AddPageNumber(format) stämplar en sidnumreringsetikett med ett startnummer och valfria explicita koordinater; AddHeader(text, topMargin) och AddFooter(text, bottomMargin) lägger till återkommande rubrik-/sidfotstext vid en given marginal, med överlagringar för vänster/höger marginaler. KeepSecurity bevarar eventuell befintlig kryptering i utdatafilen, och Close() slutför och frigör det bundna dokumentet.

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

Läser och skriver dokumentinformation med PdfFileInfo

PdfFileInfo läser och skriver om den klassiska PDF /Info-ordlistan och grundläggande per-sida-geometri utan att öppna hela objektmodellen. Author, Title, Subject, Keywords, CreationDate och ModDate är läs/skriv-egenskaper; Producer och GetPdfVersion() är skrivskyddade. GetPageWidth, GetPageHeight och GetPageRotation returnerar per-sida-geometri efter sidnummer, och IsEncrypted() / HasOpenPassword() / HasEditPassword() rapporterar dokumentets skyddstillstånd. SaveNewInfo(outputFile) skriver tillbaka ändringarna.

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

Ompositionerar sidor med PdfPageEditor

PdfPageEditor flyttar, ändrar storlek på och roterar sidinnehåll som ett block. MovePosition(offsetX, offsetY) förskjuter innehåll på de sidor som valts av ProcessPages; Zoom skalar det. Alignment (en AlignmentType — Left, Center eller Right, var och en hämtad via motsvarande statiska metod) och VerticalAlignment (en VerticalAlignmentType — Top, Center, Bottom) styr hur innehållet positioneras inom mål PageSize när ApplyChanges() körs. GetPageRotation läser sidans aktuella rotation i grader.

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

Hantera XMP-metadata med PdfXmpMetadata

PdfXmpMetadata är en karta-liknande fasad över ett dokuments XMP-paket. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) och TryGetValue(key, value) hanterar enskilda poster; Keys() och Values() enumererar hela paketet. RegisterNamespaceURI(prefix, namespaceURI) deklarerar ett anpassat XMP-namnrum innan du lägger till egenskaper i det. Välkända egenskapsnamn listas i DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails och andra), och PropertyFlag (ReadOnly, Required, NoExport) beskriver ett registrerat egenskaps schemarestriktioner.

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

Tips och bästa praxis

• Varje fasad följer samma BindPdf (eller en konstruktor som tar ett filnamn) → operera → Save/Close sekvens — att lära sig en fasad överförs direkt till nästa.
• Föredra de Try-prefixade metoderna på PdfFileEditor och PdfFileSecurity när du bearbetar filer från en opålitlig eller oförutsägbar källa — de returnerar false vid fel istället för att kasta ett undantag.
• PdfFileEditor-metoder tar filvägar, inte en bunden Document — du behöver inte öppna källfilen själv innan du anropar Concatenate, Extract eller SplitFromFirst.
• Fasadernas omsluter kärnobjektmodellen snarare än att ersätta den: Facade exponerar den underliggande Document() för fall där en fasadmetod inte täcker.
• Anropa Close() (eller låt fasaden gå ur scope, där det stöds) när du är klar med ett bundet dokument för att frigöra den underliggande filhandtaget.

Vanliga problem

FAQ

Vad är skillnaden mellan en fasad och den centrala Document API?

Fasader tillhandahåller en liten, uppgiftsorienterad metodyta för en uppgift — fylla i ett formulär, slå samman filer, stämpla sidor. Kärnan API (Document, Page, Annotation) ger full åtkomst till varje PDF-objekt. Fasader som exponerar Document() (via bas-klassen Facade) låter dig återgå till kärnmodellen för allt som en fasadmetod inte täcker.

Behöver jag anropa BindPdf före varje fasadmetod?

Ja, för fasader som implementerar IFacade — BindPdf (eller en motsvarande konstruktoröverladdning, som med PdfExtractor(doc)) måste köras före någon operation som läser eller ändrar det bundna dokumentet.

Kan PdfFileEditor-operationer kedjas?

Varje PdfFileEditor-metod läser sin egen indatafil och skriver sin egen utdatafil, så du kedjar operationer genom att mata en metods utdatafil till nästa anrops indatafil — till exempel Concatenate till merged.pdf, sedan Extract från merged.pdf.

Vilka fasader stödjer ett icke-kastande fel-läge?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst och relaterade Try* metoder) och PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) erbjuder båda Try-prefixade alternativ som returnerar bool istället för att kasta ett undantag.

API Reference Sammanfattning

Se även

• Aspose.PDF — Enterprise Documentation