Façades API

Façades API

A facade est un wrapper simplifié, orienté tâche, sur le noyau Document / Page / Annotation modèle d’objet. Au lieu de parcourir vous-même l’arbre de pages, vous liez une façade à un PDF source, appelez un petit ensemble de méthodes de haut niveau et enregistrez le résultat. Chaque façade dans Aspose::Pdf::Facades implémente le même contrat minimal défini par IFacade (BindPdf, Close) et, lorsque la façade produit une sortie, ISaveableFacade (Save). L’abstrait Facade and SaveableFacade les classes de base fournissent l’implémentation par défaut bind/close/save sur laquelle les éditeurs concrets ci-dessous s’appuient : PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, et l’approche axée sur les formulaires FormEditor / FormFieldFacade paire.

Classes de base des façades et le cycle de vie bind/save

IFacade déclare BindPdf(srcFile) (également surchargé pour accepter un Document en mémoire) et Close(). ISaveableFacade ajoute Save(destFile) pour les façades qui écrivent une sortie. Facade implémente IFacade et expose le Document() lié afin que vous puissiez revenir au modèle d’objets de base lorsqu’une méthode de façade ne couvre pas vos besoins ; SaveableFacade étend Facade avec l’implémentation Save. Chaque éditeur concret ci-dessous hérite de cette structure, de sorte que le même schéma bind → operate → save s’applique à l’ensemble des Façades API.

Remplissage et édition des champs AcroForm

FormEditor ajoute, supprime, renomme et repositionne les champs AcroForm sur un document déjà lié. AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) crée un nouveau champ du FieldType indiqué (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) aux coordonnées de page spécifiées. RemoveField, RenameField, MoveField et SetFieldAttribute gèrent les champs existants, et SetFieldScript / AddFieldScript attachent des actions JavaScript. SubmitFlag (une valeur SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments ou Pdf) contrôle la façon dont un bouton de soumission envoie les données du formulaire, et SetSubmitUrl définit le point de terminaison cible.

L’apparence visuelle attribuée à chaque nouveau champ est contrôlée via FormEditor.Facade(), qui renvoie un FormFieldFacade. Sa propriété Font accepte une valeur FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol, et variantes associées), TextEncoding accepte un EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), et BorderStyle / BorderWidth définissent la bordure du champ.

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

Gestion des repères avec PdfBookmarkEditor

PdfBookmarkEditor crée, extrait, modifie et supprime les entrées de repérage PDF. CreateBookmarks() écrit une collection Bookmarks (chaque entrée étant un Bookmark avec Title, PageNumber, Action, Level, Open et ChildItems pour les repères imbriqués) dans le document lié. ExtractBookmarks() lit le repérage existant et le restitue sous forme d’une collection Bookmarks, et DeleteBookmarks() — avec un filtre optionnel title — supprime les entrées. ExportBookmarksToXML / ImportBookmarksWithXML effectuent un aller-retour d’un repérage via un fichier XML, et ExtractBookmarksToHTML / ExportBookmarksToHtml rendent le repérage comme une page HTML.

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

Modification des annotations avec PdfAnnotationEditor

PdfAnnotationEditor aplati et importe les annotations dans l’ensemble du document. FlatteningAnnotations() fusionne les annotations dans le flux de contenu de la page afin qu’elles s’affichent comme du contenu statique plutôt que comme des objets interactifs; la surcharge acceptant une plage de pages start/end et un type d’annotation limite l’opération. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf importent les annotations depuis des fichiers externes FDF/XFDF, et DeleteAnnotations() (ou DeleteAnnotations(annotType) pour un type unique) les supprime.

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

Réécriture du contenu de la page avec PdfContentEditor

PdfContentEditor modifie le flux de contenu d’une page déjà générée au lieu de reconstruire la page. ReplaceText(srcText, destText) trouve et remplace le texte correspondant dans l’ensemble du document, avec des surcharges qui limitent le remplacement à une seule page. ReplaceImage(pageNum, imageNum, fileName) et DeleteImage(pageNum, imageNum) échangent ou suppriment un XObject image existant. DeleteStampById / HideStampById / ShowStampById / MoveStampById gèrent les objets tampon sur une page (le contenu sous-jacent d’un tampon est soit Form soit Image, selon l’énumération StampType), et AddDocumentAdditionalAction / AddDocumentAttachment attachent des actions JavaScript au niveau du document ainsi que des pièces jointes de fichiers.

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

Extraction du texte et des pièces jointes avec PdfExtractor

PdfExtractor peut être lié soit avec BindPdf, soit construit directement à partir d’un Document déjà ouvert. ExtractText() suivi de HasNextPageText() / GetNextPageText(outputFile) parcourt le document page par page. Pour les fichiers incorporés, GetAttachNames() répertorie les pièces jointes présentes et GetAttachment( outputPath) écrit la suivante sur le disque:

#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) extraient des images raster intégrées de la même façon que GetNextPageText parcourt les pages.

Assembler et scinder des fichiers avec PdfFileEditor

PdfFileEditor fonctionne sur les chemins de fichiers plutôt que sur un Document lié, ainsi chaque méthode prend directement les noms de fichiers d’entrée/sortie. Concatenate (et le TryConcatenate qui ne lève pas d’exception) fusionne deux fichiers ou plus; Append insère une plage de pages d’un fichier dans un autre; Extract extrait une plage de pages ou une page unique vers un nouveau fichier; Delete supprime une page; et SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks divisent un document à une page, page par page, ou en morceaux de taille fixe. MakeBooklet et MakeNUp réarrangent les pages pour l’impression de livret ou N-up, et ResizeContents / AddMargins / AddPageBreak ajustent la géométrie des pages dans un fichier. La plupart des opérations ont une version préfixée par Try qui renvoie false au lieu de lever une exception en cas d’échec.

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

Rendu des pages en images avec PdfConverter

PdfConverter rend les pages d’un document lié vers des formats raster. DoConvert() prépare la plage de pages (StartPage / EndPage) pour l’itération; HasNextImage () / GetNextImage(outputFile) parcourent ensuite les pages une par une. SaveAsTIFF écrit l’ensemble de la plage dans un seul TIFF multipage, avec des surcharges pour la résolution, la compression et TiffSettings. RenderingOptions et Resolution contrôlent la qualité de la rasterisation, et ImageMergeMode (Vertical, Horizontal, Center) détermine comment plusieurs images de pages rendues sont combinées lorsqu’un appelant les fusionne en une seule image.

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

Chiffrement de documents avec PdfFileSecurity

PdfFileSecurity lie un fichier source et applique ou retire le chiffrement. EncryptFile(userPassword, ownerPassword, privilege, keySize) chiffre avec un DocumentPrivilege (construit avec le constructeur par défaut et des setters booléens tels que AllowPrint, AllowCopy, AllowModifyContents) et un KeySize (x40, x128 ou x256); la surcharge qui accepte un cinquième argument cipher sélectionne explicitement le Algorithm (RC4 ou AES). DecryptFile( ownerPassword), ChangePassword et SetPrivilege couvrent les autres cas de gestion de mot de passe, chacun avec une variante préfixée par Try qui ne lève pas d’exception.

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

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

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

Signature et vérification avec PdfFileSignature

PdfFileSignature signe, certifie et inspecte les signatures numériques sur un document lié. Sign(sigName, reason, contact, location, signature) applique une nouvelle signature à un champ de signature existant; Certify applique une signature de certification. GetSignatureNames(onlyEmpty) et GetBlankSignatureNames() renvoient les champs de signature du document sous forme de valeurs SignatureName, et VerifySignature(sigName) / IsCoversWholeDocument (sigName) vérifient la validité et la couverture. RemoveSignature et RemoveSignatures() suppriment les signatures existantes, et SetCertificate(pfxFile, password) fournit les informations d’identification de signature avant d’appeler Sign.

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

Apposer des en-têtes, pieds de page et numéros de page avec PdfFileStamp

PdfFileStamp superpose du contenu récurrent sur chaque page d’un fichier lié. AddPageNumber(format) appose une étiquette de numéro de page en utilisant un numéro de départ et des coordonnées explicites facultatives; AddHeader(text, topMargin) et AddFooter(text, bottomMargin) ajoutent du texte d’en-tête/pied de page récurrent à une marge donnée, avec des surcharges pour les marges gauche/droite. KeepSecurity conserve tout chiffrement existant sur le fichier de sortie, et Close() finalise et libère le document lié.

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

Lecture et écriture des informations du document avec PdfFileInfo

PdfFileInfo lit et réécrit le dictionnaire classique PDF /Info ainsi que la géométrie de base par page sans ouvrir le modèle complet d’objets. Author, Title, Subject, Keywords, CreationDate et ModDate sont des propriétés lecture/écriture; Producer et GetPdfVersion() sont en lecture seule. GetPageWidth, GetPageHeight et GetPageRotation renvoient la géométrie par page selon le numéro de page, et IsEncrypted() / HasOpenPassword() / HasEditPassword() indiquent l’état de protection du document. SaveNewInfo(outputFile) écrit les modifications en sortie.

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

Repositionner les pages avec PdfPageEditor

PdfPageEditor déplace, redimensionne et pivote le contenu d’une page en tant que bloc. MovePosition(offsetX, offsetY) décale le contenu sur les pages sélectionnées par ProcessPages; Zoom le redimensionne. Alignment (un AlignmentType — Left, Center ou Right, chacun obtenu via la méthode statique correspondante) et VerticalAlignment (un VerticalAlignmentType — Top, Center, Bottom) contrôlent la façon dont le contenu est positionné dans le PageSize cible une fois que ApplyChanges() s’exécute. GetPageRotation lit la rotation actuelle d’une page en degrés.

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

Gestion des métadonnées XMP avec PdfXmpMetadata

PdfXmpMetadata est une façade de type carte sur le paquet XMP d’un document. Add(key, value), Remove(key), Contains(key) / ContainsKey(key) et TryGetValue(key, value) gèrent les entrées individuelles; Keys() et Values() parcourent l’ensemble du paquet. RegisterNamespaceURI(prefix, namespaceURI) déclare un espace de noms XMP personnalisé avant d’ajouter des propriétés dedans. Les noms de propriétés connus sont répertoriés dans DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails et d’autres), et PropertyFlag (ReadOnly, Required, NoExport) décrit les contraintes de schéma d’une propriété enregistrée.

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

Conseils et meilleures pratiques

• Chaque façade suit le même BindPdf (ou un constructeur acceptant un nom de fichier) → opérer → séquence Save/Close — apprendre une façade se transfère directement à la suivante.
• Préférez les méthodes préfixées par Try sur PdfFileEditor et PdfFileSecurity lors du traitement de fichiers provenant d’une source non fiable ou imprévisible — elles renvoient false en cas d’échec au lieu de lever une exception.
• Les méthodes PdfFileEditor prennent des chemins de fichier, pas un Document lié — vous n’avez pas besoin d’ouvrir le fichier source vous-même avant d’appeler Concatenate, Extract ou SplitFromFirst.
• Les façades enveloppent le modèle d’objet central plutôt que de le remplacer: Facade expose le Document() sous-jacent pour les cas où une méthode de façade ne couvre pas la situation.
• Appelez Close() (ou laissez la façade sortir de la portée, si pris en charge) une fois que vous avez terminé avec un document lié pour libérer le descripteur de fichier sous-jacent.

Problèmes courants

FAQ

Quelle est la différence entre une façade et le core Document API?

Les Facades offrent une petite surface de méthodes orientée tâche pour une seule tâche — remplir un formulaire, fusionner des fichiers, tamponner des pages. Le core API (Document, Page, Annotation) donne un accès complet à chaque objet PDF. Les Facades qui exposent Document() (via la classe de base Facade) vous permettent de revenir au modèle core pour tout ce qu’une méthode de façade ne couvre pas.

Dois-je appeler BindPdf avant chaque méthode de façade?

Oui, pour les facades qui implémentent IFacade — BindPdf (ou une surcharge de constructeur équivalente, comme avec PdfExtractor(doc)) doit être exécutée avant toute opération qui lit ou modifie le document lié.

Les opérations PdfFileEditor peuvent-elles être enchaînées?

Chaque méthode PdfFileEditor lit son propre fichier d’entrée et écrit son propre fichier de sortie, ainsi vous enchaînez les opérations en alimentant le fichier de sortie d’une méthode dans le fichier d’entrée de l’appel suivant — par exemple, Concatenate dans merged.pdf, puis Extract depuis merged.pdf.

Quelles facades supportent un mode d’erreur sans exception?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, et les méthodes Try* associées) et PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) offrent toutes deux des alternatives préfixées par Try qui renvoient bool au lieu de lever une exception.

API Reference Résumé

Voir aussi

• Aspose.PDF — Enterprise Documentation