Fațade API

Fațade API

A facade este un înveliș simplificat, orientat pe sarcini, peste core Document / Page / Annotation modelul de obiecte. În loc să parcurgi tu singur arborele de pagini, leagă o fațadă de un PDF sursă, apelează un mic set de metode de nivel înalt și salvează rezultatul. Fiecare fațadă în Aspose::Pdf::Facades implementează același contract minimal definit de IFacade (BindPdf, Close) și, acolo unde fațada produce ieșire, ISaveableFacade (Save). Clasa abstractă Facade and SaveableFacade clasele de bază furnizează implementarea implicită bind/close/save pe care editorii concreți de mai jos se bazează: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, și cele axate pe formulare FormEditor / FormFieldFacade pereche.

Clase de bază ale fațadei și ciclul de viață bind/save

IFacade declară BindPdf(srcFile) (de asemenea supraîncărcat pentru a accepta un Document în memorie) și Close(). ISaveableFacade adaugă Save(destFile) pentru fațadele care scriu ieșire. Facade implementează IFacade și expune Document() legat, astfel încât poți reveni la modelul de obiecte de bază când o metodă a fațadei nu acoperă ceea ce ai nevoie; SaveableFacade extinde Facade cu implementarea Save. Fiecare editor concret de mai jos moștenește această structură, astfel că același tipar bind → operate → save se aplică în întregul Fațade API.

Completarea și editarea câmpurilor AcroForm

FormEditor adaugă, elimină, redenumește și repoziționează AcroForm pe un document deja legat. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) creează un nou câmp de tipul FieldType dat (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) la coordonatele de pagină specificate. RemoveField, RenameField, MoveField și SetFieldAttribute gestionează câmpurile existente, iar SetFieldScript / AddFieldScript atașează acțiuni JavaScript. SubmitFlag (o valoare SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments sau Pdf) controlează modul în care un buton de trimitere postează datele formularului, iar SetSubmitUrl stabilește endpoint-ul țintă.

Aspectul vizual pe care îl primește fiecare câmp nou este controlat prin FormEditor.Facade(), care returnează un FormFieldFacade. Proprietatea sa Font acceptă o valoare FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol și variantele aferente), TextEncoding primește un EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), iar BorderStyle / BorderWidth setează bordura câmpului.

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

Gestionarea cuprinsurilor cu PdfBookmarkEditor

PdfBookmarkEditor creează, extrage, modifică și elimină intrări de cuprins PDF. CreateBookmarks() scrie o colecție Bookmarks (fiecare intrare este un Bookmark cu Title, PageNumber, Action, Level, Open și ChildItems pentru cuprinsuri imbricate) în documentul legat. ExtractBookmarks() citește cuprinsul existent și îl returnează ca o colecție Bookmarks, iar DeleteBookmarks() — cu un filtru opțional title — elimină intrările. ExportBookmarksToXML / ImportBookmarksWithXML fac un ciclu complet al unui cuprins printr-un fișier XML, și ExtractBookmarksToHTML / ExportBookmarksToHtml redau cuprinsul ca o pagină HTML.

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

Editarea adnotărilor cu PdfAnnotationEditor

PdfAnnotationEditor aplatizează și importă adnotări în întregul document. FlatteningAnnotations() fuzionează adnotările în fluxul de conținut al paginii astfel încât acestea să fie redate ca conținut static în loc de obiecte interactive; supraîncărcarea care primește un interval de pagini start/end și un tip de adnotare limitează operațiunea. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf importă adnotări din fișiere externe FDF/XFDF, iar DeleteAnnotations() (sau DeleteAnnotations(annotType) pentru un singur tip) le elimină.

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

Rescrierea conținutului paginii cu PdfContentEditor

PdfContentEditor editează fluxul de conținut al unei pagini deja generate în loc să reconstruiască pagina. ReplaceText(srcText, destText) găsește și înlocuiește textul potrivit în întregul document, cu supraîncărcări care limitează înlocuirea la o singură pagină. ReplaceImage(pageNum, imageNum, fileName) și DeleteImage(pageNum, imageNum) înlocuiesc sau elimină un XObject de imagine existent. DeleteStampById / HideStampById / ShowStampById / MoveStampById gestionează obiectele ștampilă pe o pagină (conținutul de bază al unei ștampile este fie Form, fie Image, conform enumului StampType), iar AddDocumentAdditionalAction / AddDocumentAttachment atașează acțiuni JavaScript la nivel de document și atașamente de fișiere.

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

Extracția textului și a atașamentelor cu PdfExtractor

PdfExtractor poate fi legat fie cu BindPdf, fie construit direct dintr-un Document deja deschis. ExtractText() urmat de HasNextPageText() / GetNextPageText(outputFile) parcurge documentul pagină cu pagină. Pentru fișierele încorporate, GetAttachNames() enumeră atașamentele prezente și GetAttachment( outputPath) scrie următorul pe disc:

#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) extrage imagini raster încorporate în același mod în care GetNextPageText parcurge paginile.

Asamblarea și despărțirea fișierelor cu PdfFileEditor

PdfFileEditor operează pe căi de fișier în loc de un Document legat, astfel încât fiecare metodă primește direct numele fișierelor de intrare/ieșire. Concatenate (și versiunea non-throwing TryConcatenate) îmbină două sau mai multe fișiere; Append inserează un interval de pagini dintr-un fișier în altul; Extract extrage un interval de pagini sau o singură pagină într-un fișier nou; Delete elimină o pagină; și SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks împarte un document la o pagină, pagină cu pagină sau în bucăți de dimensiune fixă. MakeBooklet și MakeNUp rearanjează paginile pentru tipărire tip broșură sau N-up, iar ResizeContents / AddMargins / AddPageBreak ajustează geometria paginii în întregul fișier. Majoritatea operațiunilor au o variantă cu prefixul Try care returnează false în loc să arunce o excepție la eșec.

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

Randarea paginilor în imagini cu PdfConverter

PdfConverter redă paginile unui document legat în formate raster. DoConvert() pregătește intervalul de pagini (StartPage / EndPage) pentru iterare; HasNextImage () / GetNextImage(outputFile) parcurg apoi paginile una câte una. SaveAsTIFF scrie întregul interval într-un singur TIFF multipagină, cu suprasarcini pentru rezoluție, compresie și TiffSettings. RenderingOptions și Resolution controlează calitatea rasterizării, iar ImageMergeMode (Vertical, Horizontal, Center) guvernează modul în care multiple imagini de pagini randate sunt combinate când un apelant le îmbină într-o singură imagine.

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

Criptarea documentelor cu PdfFileSecurity

PdfFileSecurity leagă un fișier sursă și aplică sau elimină criptarea. EncryptFile(userPassword, ownerPassword, privilege, keySize) criptează cu un DocumentPrivilege (creat cu constructorul implicit și setteri booleeni precum AllowPrint, AllowCopy, AllowModifyContents) și un KeySize (x40, x128 sau x256); suprasarcina care primește un al cincilea argument cipher selectează explicit Algorithm (RC4 sau AES). DecryptFile( ownerPassword), ChangePassword și SetPrivilege acoperă cazurile rămase de gestionare a parolei, fiecare având o variantă non-throwing cu prefixul Try.

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

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

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

Semnarea și verificarea cu PdfFileSignature

PdfFileSignature semnează, certifică și inspectează semnăturile digitale pe un document legat. Sign(sigName, reason, contact, location, signature) aplică o semnătură nouă într-un câmp de semnătură existent; Certify aplică o semnătură de certificare. GetSignatureNames(onlyEmpty) și GetBlankSignatureNames() returnează câmpurile de semnătură ale documentului ca valori SignatureName, iar VerifySignature(sigName) / IsCoversWholeDocument (sigName) verifică valabilitatea și acoperirea. RemoveSignature și RemoveSignatures() elimină semnăturile existente, iar SetCertificate(pfxFile, password) furnizează acreditarea de semnare înainte de a apela Sign.

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

Stamparea antetelor, subsolurilor și numerelor de pagină cu PdfFileStamp

PdfFileStamp suprapune conținut repetitiv pe fiecare pagină a unui fișier legat. AddPageNumber(format) inscripționează o etichetă cu numărul paginii utilizând un număr de pornire și coordonate explicite opționale; AddHeader(text, topMargin) și AddFooter(text, bottomMargin) adaugă text recurent de antet/subsol la o margine dată, cu suprasarcini pentru marginile stânga/dreapta. KeepSecurity păstrează orice criptare existentă în fișierul de ieșire, iar Close() finalizează și eliberează documentul legat.

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

Citirea și scrierea informațiilor documentului cu PdfFileInfo

PdfFileInfo citește și rescrie dicționarul clasic PDF /Info și geometria de bază pe pagină fără a deschide modelul complet de obiecte. Author, Title, Subject, Keywords, CreationDate și ModDate sunt proprietăți de citire/scriere; Producer și GetPdfVersion() sunt numai de citire. GetPageWidth, GetPageHeight și GetPageRotation returnează geometria pe pagină în funcție de numărul paginii, iar IsEncrypted() / HasOpenPassword() / HasEditPassword() raportează starea de protecție a documentului. SaveNewInfo(outputFile) scrie modificările înapoi.

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

Repoziționarea paginilor cu PdfPageEditor

PdfPageEditor mută, redimensionează și rotește conținutul paginii ca un bloc. MovePosition(offsetX, offsetY) deplasează conținutul pe paginile selectate de ProcessPages; Zoom îl scalează. Alignment (un AlignmentType — Left, Center sau Right, fiecare obținut din metoda statică corespunzătoare) și VerticalAlignment (un VerticalAlignmentType — Top, Center, Bottom) controlează modul în care conținutul este poziționat în cadrul PageSize țintă odată ce ApplyChanges() se execută. GetPageRotation citește rotația curentă a paginii în grade.

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

Gestionarea metadatelor XMP cu PdfXmpMetadata

PdfXmpMetadata este o fațadă de tip mapă peste pachetul XMP al unui document. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) și TryGetValue(key, value) gestionează intrări individuale; Keys() și Values() enumeră întregul pachet. RegisterNamespaceURI(prefix, namespaceURI) declară un spațiu de nume XMP personalizat înainte de a adăuga proprietăți în el. Numele de proprietăți bine cunoscute sunt listate în DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails și altele), iar PropertyFlag (ReadOnly, Required, NoExport) descrie constrângerile de schemă ale unei proprietăți înregistrate.

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

Sfaturi și cele mai bune practici

• Fiecare fațadă urmează același BindPdf (sau un constructor care primește un nume de fișier) → operează → secvența Save/Close — învățarea unei fațade se transferă direct la următoarea.
• Preferă metodele cu prefixul Try pe PdfFileEditor și PdfFileSecurity când procesezi fișiere dintr-o sursă neîncredere sau imprevizibilă — ele returnează false în caz de eșec în loc să arunce excepție.
• Metodele PdfFileEditor acceptă căi de fișier, nu un Document legat — nu trebuie să deschizi fișierul sursă manual înainte de a apela Concatenate, Extract sau SplitFromFirst.
• Fațadele învelesc modelul de obiecte de bază în loc să îl înlocuiască: Facade expune Document() subiacente pentru cazurile în care o metodă a fațadei nu acoperă.
• Apelează Close() (sau lasă fațada să iasă din domeniu, acolo unde este suportat) odată ce ai terminat cu un document legat pentru a elibera descriptorul de fișier subiacente.

Probleme comune

FAQ

Care este diferența dintre o fațadă și Documentul de bază API?

Fațadele oferă o suprafață de metode mică, orientată pe sarcini, pentru o singură activitate — completarea unui formular, îmbinarea fișierelor, ștampilarea paginilor. Nucleul API (Document, Page, Annotation) oferă acces complet la fiecare obiect PDF. Fațadele care expun Document() (prin clasa de bază Facade) îți permit să revii la modelul de bază pentru orice nu este acoperit de o metodă a fațadei.

Trebuie să apelez BindPdf înainte de fiecare metodă a fațadei?

Da, pentru fațadele care implementează IFacade — BindPdf (sau o suprasarcină echivalentă a constructorului, ca în cazul PdfExtractor(doc)) trebuie să fie executat înainte de orice operație care citește sau modifică documentul asociat.

Pot operațiile PdfFileEditor să fie înlănțuite?

Fiecare metodă PdfFileEditor citește propriul fișier de intrare și scrie propriul fișier de ieșire, așa că înlănțuiți operațiile introducând fișierul de ieșire al unei metode în fișierul de intrare al următoarei apelări — de exemplu, Concatenate în merged.pdf, apoi Extract din merged.pdf.

Ce fațade suportă un mod de eroare fără aruncare?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, și metodele Try* conexe) și PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) oferă ambele alternative prefixate cu Try care returnează bool în loc să arunce.

Rezumat API Reference

Vezi și:

• Aspose.PDF — Enterprise Documentation