Facciate API

Facades API

A facade è un wrapper semplificato, orientato al compito, sul core Document / Page / Annotation modello di oggetti. Invece di percorrere manualmente l’albero delle pagine, associ una facade a un PDF di origine, chiami un piccolo insieme di metodi di alto livello e salvi il risultato. Ogni facade in Aspose::Pdf::Facades implementa lo stesso contratto minimo definito da IFacade (BindPdf, Close) e, dove la facade produce output, ISaveableFacade (Save). L’astratto Facade and SaveableFacade le classi base forniscono l’implementazione predefinita bind/close/save su cui si basano gli editor concreti di seguito: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, e il focalizzato sul modulo FormEditor / FormFieldFacade coppia.

Classi base della Facade e il ciclo di vita bind/save

IFacade dichiara BindPdf(srcFile) (anche sovraccaricato per accettare un Document in memoria) e Close(). ISaveableFacade aggiunge Save(destFile) per le facade che scrivono output. Facade implementa IFacade ed espone il Document() legato così puoi tornare al modello di oggetti core quando un metodo della facade non copre ciò di cui hai bisogno; SaveableFacade estende Facade con l’implementazione Save. Ogni editor concreto qui sotto eredita questa struttura, quindi lo stesso schema bind → operate → save si applica a tutto il Facades API.

Compilazione e modifica dei campi AcroForm

FormEditor aggiunge, rimuove, rinomina e riposiziona i campi AcroForm su un documento già associato. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) crea un nuovo campo del tipo FieldType (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) alle coordinate di pagina specificate. RemoveField, RenameField, MoveField e SetFieldAttribute gestiscono i campi esistenti, e SetFieldScript / AddFieldScript collegano le azioni JavaScript. SubmitFlag (un valore SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments o Pdf) controlla come un pulsante di invio invia i dati del modulo, e SetSubmitUrl imposta l’endpoint di destinazione.

L’aspetto visivo che ogni nuovo campo ottiene è controllato tramite FormEditor.Facade(), che restituisce un FormFieldFacade. La sua proprietà Font accetta un valore FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol e varianti correlate), TextEncoding accetta un EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), e BorderStyle / BorderWidth impostano il bordo del campo.

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

Gestire gli outline con PdfBookmarkEditor

PdfBookmarkEditor crea, estrae, modifica e rimuove voci di outline PDF. CreateBookmarks() scrive una collezione Bookmarks (ogni voce è un Bookmark con Title, PageNumber, Action, Level, Open e ChildItems per gli outline annidati) nel documento associato. ExtractBookmarks() legge l’outline esistente restituendolo come una collezione Bookmarks, e DeleteBookmarks() — con un filtro opzionale title — rimuove le voci. ExportBookmarksToXML / ImportBookmarksWithXML effettuano un round-trip di un outline attraverso un file XML, e ExtractBookmarksToHTML / ExportBookmarksToHtml rendono l’outline come una pagina HTML.

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

Modifica delle annotazioni con PdfAnnotationEditor

PdfAnnotationEditor appiattisce e importa le annotazioni su tutto il documento. FlatteningAnnotations() unisce le annotazioni nello stream di contenuto della pagina in modo che vengano renderizzate come contenuto statico invece di oggetti interattivi; la sovraccarico che accetta un intervallo di pagine start/end e un tipo di annotazione limita l’operazione. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf importano le annotazioni da file FDF/XFDF esterni, e DeleteAnnotations() (o DeleteAnnotations(annotType) per un singolo tipo) le rimuove.

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

Riscrivere il contenuto della pagina con PdfContentEditor

PdfContentEditor modifica lo stream di contenuto di una pagina già generata invece di ricostruire la pagina. ReplaceText(srcText, destText) trova e sostituisce il testo corrispondente in tutto il documento, con sovraccarichi che limitano la sostituzione a una singola pagina. ReplaceImage(pageNum, imageNum, fileName) e DeleteImage(pageNum, imageNum) scambiano o rimuovono un XObject immagine esistente. DeleteStampById / HideStampById / ShowStampById / MoveStampById gestiscono gli oggetti timbro su una pagina (il contenuto sottostante di un timbro è Form o Image, secondo l’enumerazione StampType), e AddDocumentAdditionalAction / AddDocumentAttachment collegano azioni JavaScript a livello di documento e allegati di file.

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

Estrazione di testo e allegati con PdfExtractor

PdfExtractor può essere associato sia con BindPdf sia costruito direttamente da un Document già aperto. ExtractText() seguito da HasNextPageText() / GetNextPageText(outputFile) percorre il documento pagina per pagina. Per i file incorporati, GetAttachNames() elenca gli allegati presenti e GetAttachment( outputPath) scrive il successivo su disco:

#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) estrae immagini raster incorporate allo stesso modo in cui GetNextPageText scorre le pagine.

Assemblare e dividere file con PdfFileEditor

PdfFileEditor opera su percorsi di file anziché su un Document legato, quindi ogni metodo accetta direttamente i nomi dei file di input/output. Concatenate (e il suo equivalente non-throwing TryConcatenate) unisce due o più file; Append inserisce un intervallo di pagine da un file in un altro; Extract estrae un intervallo di pagine o una singola pagina in un nuovo file; Delete rimuove una pagina; e SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks dividono un documento a una pagina, pagina per pagina, o in blocchi di dimensione fissa. MakeBooklet e MakeNUp riorganizzano le pagine per stampa a libretto o N-up, e ResizeContents / AddMargins / AddPageBreak regolano la geometria delle pagine lungo un file. La maggior parte delle operazioni ha una controparte prefissata con Try che restituisce false invece di lanciare un’eccezione in caso di errore.

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

Rendering delle pagine in immagini con PdfConverter

PdfConverter rende le pagine di un documento legato in formati raster. DoConvert() prepara l’intervallo di pagine (StartPage / EndPage) per l’iterazione; HasNextImage () / GetNextImage(outputFile) quindi percorrono le pagine una alla volta. SaveAsTIFF scrive l’intero intervallo in un unico TIFF multipagina, con overload per risoluzione, compressione e TiffSettings. RenderingOptions e Resolution controllano la qualità della rasterizzazione, e ImageMergeMode (Vertical, Horizontal, Center) regola come le immagini di pagina renderizzate multiple vengano combinate quando un chiamante le unisce in un’unica immagine.

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

Crittografare documenti con PdfFileSecurity

PdfFileSecurity associa un file sorgente e applica o rimuove la crittografia. EncryptFile(userPassword, ownerPassword, privilege, keySize) cripta con un DocumentPrivilege (creato con il costruttore predefinito e i setter booleani come AllowPrint, AllowCopy, AllowModifyContents) e un KeySize (x40, x128 o x256); la sovraccarico che accetta un quinto argomento cipher seleziona esplicitamente il Algorithm (RC4 o AES). DecryptFile( ownerPassword), ChangePassword e SetPrivilege coprono i casi rimanenti di gestione delle password, ciascuno con una variante non-throwing prefissata da Try.

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

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

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

Firmare e verificare con PdfFileSignature

PdfFileSignature firma, certifica e ispeziona le firme digitali su un documento vincolato. Sign(sigName, reason, contact, location, signature) applica una nuova firma a un campo firma esistente; Certify applica una firma certificante. GetSignatureNames(onlyEmpty) e GetBlankSignatureNames() restituiscono i campi firma del documento come valori SignatureName, e VerifySignature(sigName) / IsCoversWholeDocument (sigName) verificano la validità e la copertura. RemoveSignature e RemoveSignatures() rimuovono le firme esistenti, e SetCertificate(pfxFile, password) fornisce le credenziali di firma prima di chiamare Sign.

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

Stampare intestazioni, piè di pagina e numeri di pagina con PdfFileStamp

PdfFileStamp sovrappone contenuto ricorrente su ogni pagina di un file vincolato. AddPageNumber(format) stampa un’etichetta di numero di pagina usando un numero di partenza e coordinate esplicite opzionali; AddHeader(text, topMargin) e AddFooter(text, bottomMargin) aggiungono testo ricorrente di intestazione/piè di pagina a un determinato margine, con overload per i margini sinistro/destro. KeepSecurity preserva qualsiasi crittografia esistente sul file di output, e Close() finalizza e rilascia il documento vincolato.

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

Leggere e scrivere le informazioni del documento con PdfFileInfo

PdfFileInfo legge e riscrive il classico dizionario PDF /Info e la geometria di base per pagina senza aprire il modello completo degli oggetti. Author, Title, Subject, Keywords, CreationDate e ModDate sono proprietà di lettura/scrittura; Producer e GetPdfVersion() sono solo lettura. GetPageWidth, GetPageHeight e GetPageRotation restituiscono la geometria per pagina in base al numero di pagina, e IsEncrypted() / HasOpenPassword() / HasEditPassword() segnalano lo stato di protezione del documento. SaveNewInfo(outputFile) scrive le modifiche di nuovo.

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

Riposizionare le pagine con PdfPageEditor

PdfPageEditor sposta, ridimensiona e ruota il contenuto della pagina come un blocco. MovePosition(offsetX, offsetY) sposta il contenuto sulle pagine selezionate da ProcessPages; Zoom lo scala. Alignment (un AlignmentType — Left, Center o Right, ciascuno ottenuto dal metodo statico corrispondente) e VerticalAlignment (un VerticalAlignmentType — Top, Center, Bottom) controllano come il contenuto è posizionato all’interno del PageSize di destinazione una volta eseguito ApplyChanges(). GetPageRotation legge la rotazione corrente di una pagina in gradi.

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

Gestire i metadati XMP con PdfXmpMetadata

PdfXmpMetadata è una facciata simile a una mappa sul pacchetto XMP di un documento. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) e TryGetValue(key, value) gestiscono voci individuali; Keys() e Values() enumerano l’intero pacchetto. RegisterNamespaceURI(prefix, namespaceURI) dichiara uno spazio di nomi XMP personalizzato prima di aggiungere proprietà al suo interno. I nomi di proprietà più noti sono elencati in DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails e altri), e PropertyFlag (ReadOnly, Required, NoExport) descrive i vincoli di schema di una proprietà registrata.

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

Suggerimenti e migliori pratiche

• Ogni facciata segue lo stesso BindPdf (o un costruttore che accetta un nome file) → operare → sequenza Save/Close — imparare una facciata si trasferisce direttamente alla successiva.
• Preferisci i metodi con prefisso Try su PdfFileEditor e PdfFileSecurity quando elabori file da una fonte non attendibile o imprevedibile — restituiscono false in caso di errore invece di lanciare.
• I metodi PdfFileEditor accettano percorsi di file, non un Document associato — non è necessario aprire manualmente il file di origine prima di chiamare Concatenate, Extract o SplitFromFirst.
• Le facciate avvolgono il modello di oggetti core invece di sostituirlo: Facade espone il Document() sottostante per i casi in cui un metodo della facciata non lo copre.
• Chiama Close() (o lascia che la facciata esca dallo scope, dove supportato) una volta terminato con un documento associato per rilasciare il gestore di file sottostante.

Problemi comuni

FAQ

Qual è la differenza tra una facade e il Document API core?

Le facade forniscono una piccola superficie di metodi orientata al compito per un’unica operazione — compilare un modulo, unire file, timbrare pagine. Il core API (Document, Page, Annotation) offre pieno accesso a ogni oggetto PDF. Le facade che espongono Document() (tramite la classe base Facade) ti permettono di tornare al modello core per tutto ciò che un metodo della facade non copre.

Devo chiamare BindPdf prima di ogni metodo della facade?

Sì, per le facade che implementano IFacade — BindPdf (o una sovraccarico del costruttore equivalente, come con PdfExtractor(doc)) deve essere eseguito prima di qualsiasi operazione che legge o modifica il documento associato.

Le operazioni PdfFileEditor possono essere concatenate?

Ogni metodo PdfFileEditor legge il proprio file di input e scrive il proprio file di output, così si concatenano le operazioni passando il file di output di un metodo come file di input della chiamata successiva — ad esempio, Concatenate in merged.pdf, poi Extract da merged.pdf.

Quali facade supportano una modalità di errore non-throwing?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, e i relativi metodi Try*) e PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) offrono entrambi alternative prefissate con Try che restituiscono bool invece di lanciare.

API Reference Riepilogo

Vedi anche

• Aspose.PDF — Enterprise Documentation