Πρόσοψεις API

Πρόσοψεις API

A facade είναι ένα απλοποιημένο, προσανατολισμένο σε εργασίες wrapper πάνω από τον πυρήνα Document / Page / Annotation μοντέλο αντικειμένου. Αντί να περιηγείστε στο δέντρο σελίδων μόνοι σας, συνδέετε ένα facade με ένα πηγαίο PDF, καλείτε ένα μικρό σύνολο μεθόδων υψηλού επιπέδου και αποθηκεύετε το αποτέλεσμα. Κάθε facade στο Aspose::Pdf::Facades υλοποιεί το ίδιο ελάχιστο συμβόλαιο που ορίζεται από IFacade (BindPdf, Close) και, όπου το facade παράγει έξοδο, ISaveableFacade (Save). Το abstract Facade and SaveableFacade οι βασικές κλάσεις παρέχουν την προεπιλεγμένη υλοποίηση bind/close/save που οι συγκεκριμένοι επεξεργαστές παρακάτω βασίζονται σε: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, και το form-focused FormEditor / FormFieldFacade ζεύγος.

Βασικές κλάσεις πρόσοψης και ο κύκλος ζωής bind/save

IFacade δηλώνει το BindPdf(srcFile) (επίσης υπερφορτωμένο ώστε να δέχεται ένα εν-μνήμης Document) και το Close(). Το ISaveableFacade προσθέτει το Save(destFile) για πρόσοψεις που γράφουν έξοδο. Το Facade υλοποιεί το IFacade και εκθέτει το δεσμευμένο Document() ώστε να μπορείτε να επιστρέψετε στο βασικό μοντέλο αντικειμένων όταν μια μέθοδος πρόσοψης δεν καλύπτει ό,τι χρειάζεστε· το SaveableFacade επεκτείνει το Facade με την υλοποίηση Save. Κάθε συγκεκριμένος επεξεργαστής παρακάτω κληρονομεί αυτή τη δομή, έτσι το ίδιο πρότυπο bind → operate → save εφαρμόζεται σε όλη τη συλλογή Πρόσοψεις API.

Συμπλήρωση και επεξεργασία AcroForm πεδίων

FormEditor προσθέτει, αφαιρεί, μετονομάζει και επανατοποθετεί πεδία AcroForm σε ένα ήδη δεσμευμένο έγγραφο. Το AddField(fieldType, fieldName, pageNum, llx, lly, urx, ury) δημιουργεί ένα νέο πεδίο του συγκεκριμένου FieldType (Text, CheckBox, Radio, ComboBox, ListBox, PushButton, MultiLineText, Barcode, Signature, Image, Numeric, DateTime) στις καθορισμένες συντεταγμένες σελίδας. Τα RemoveField, RenameField, MoveField και SetFieldAttribute διαχειρίζονται υπάρχοντα πεδία, και τα SetFieldScript / AddFieldScript συνδέουν ενέργειες JavaScript. Το SubmitFlag (μια τιμή SubmitFormFlag — Fdf, Html, Xfdf, FdfWithComments, XfdfWithComments ή Pdf) ελέγχει πώς ένα κουμπί υποβολής αποστέλλει τα δεδομένα της φόρμας, και το SetSubmitUrl ορίζει το τελικό σημείο προορισμού.

Η οπτική εμφάνιση που λαμβάνει κάθε νέο πεδίο ελέγχεται μέσω του FormEditor.Facade(), ο οποίος επιστρέφει ένα FormFieldFacade. Η ιδιότητα Font του παίρνει μια τιμή FontStyle (Helvetica, HelveticaBold, Courier, TimesRoman, Symbol και σχετικές παραλλαγές), το TextEncoding παίρνει ένα EncodingType (Winansi, Macroman, Identity_h, Identity_v, Cp1250, Cp1252, Cp1257), και τα BorderStyle / BorderWidth ορίζουν το περίγραμμα του πεδίου.

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

Διαχείριση περιγραμμάτων με PdfBookmarkEditor

PdfBookmarkEditor δημιουργεί, εξάγει, τροποποιεί και αφαιρεί καταχωρήσεις περιγράμματος PDF. CreateBookmarks() γράφει μια συλλογή Bookmarks (κάθε καταχώρηση ένα Bookmark με Title, PageNumber, Action, Level, Open και ChildItems για ένθετα περιγράμματα) στο δεσμευμένο έγγραφο. ExtractBookmarks() διαβάζει το υπάρχον περίγραμμα πίσω ως μια συλλογή Bookmarks, και DeleteBookmarks() — με ένα προαιρετικό φίλτρο title — αφαιρεί καταχωρήσεις. ExportBookmarksToXML / ImportBookmarksWithXML κάνουν round-trip ένα περίγραμμα μέσω ενός αρχείου XML, και ExtractBookmarksToHTML / ExportBookmarksToHtml αποδίδουν το περίγραμμα ως μια σελίδα HTML.

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

Επεξεργασία σημειώσεων με PdfAnnotationEditor

PdfAnnotationEditor ισοπεδώνει και εισάγει σημειώσεις σε όλο το έγγραφο. FlatteningAnnotations() συγχωνεύει τις σημειώσεις στο ρεύμα περιεχομένου της σελίδας ώστε να αποδίδονται ως στατικό περιεχόμενο αντί για διαδραστικά αντικείμενα· η υπερφόρτωση που δέχεται ένα εύρος σελίδων start/end και έναν τύπο σημείωσης περιορίζει τη λειτουργία. ImportAnnotationsFromXfdf / ImportAnnotationsFromFdf φέρνουν σημειώσεις από εξωτερικά αρχεία FDF/XFDF, και DeleteAnnotations() (ή DeleteAnnotations(annotType) για έναν μόνο τύπο) τις αφαιρούν.

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

Επαναγραφή περιεχομένου σελίδας με PdfContentEditor

PdfContentEditor επεξεργάζεται το ρεύμα περιεχομένου μιας ήδη δημιουργημένης σελίδας αντί να ξαναδημιουργεί τη σελίδα. ReplaceText(srcText, destText) εντοπίζει και αντικαθιστά το αντίστοιχο κείμενο σε όλο το έγγραφο, με υπερφορτώσεις που περιορίζουν την αντικατάσταση σε μία μόνο σελίδα. ReplaceImage(pageNum, imageNum, fileName) και DeleteImage(pageNum, imageNum) ανταλλάσσουν ή αφαιρούν ένα υπάρχον XObject εικόνας. DeleteStampById / HideStampById / ShowStampById / MoveStampById διαχειρίζονται αντικείμενα σφραγίδας σε μια σελίδα (το υποκείμενο περιεχόμενο μιας σφραγίδας είναι είτε Form είτε Image, σύμφωνα με την απαρίθμηση StampType), και AddDocumentAdditionalAction / AddDocumentAttachment προσθέτουν ενέργειες JavaScript επιπέδου εγγράφου και συνημμένα αρχεία.

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

Εξαγωγή κειμένου και συνημμένων με PdfExtractor

PdfExtractor μπορεί να δεσμευθεί είτε με BindPdf είτε να κατασκευαστεί απευθείας από ένα ήδη ανοιχτό Document. ExtractText() ακολουθούμενο από HasNextPageText() / GetNextPageText(outputFile) περιηγείται στο έγγραφο σελίδα προς σελίδα. Για ενσωματωμένα αρχεία, GetAttachNames() καταχωρίζει τα διαθέσιμα συνημμένα και GetAttachment( outputPath) γράφει το επόμενο στο δίσκο:

#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) εξάγει ενσωματωμένες raster εικόνες με τον ίδιο τρόπο που το GetNextPageText περιηγείται στις σελίδες.

Συναρμολόγηση και διαίρεση αρχείων με PdfFileEditor

PdfFileEditor λειτουργεί σε διαδρομές αρχείων αντί για ένα δεσμευμένο Document, έτσι κάθε μέθοδος παίρνει άμεσα ονόματα αρχείων εισόδου/εξόδου. Concatenate (και το μη-εξαιρέσιμο TryConcatenate) ενώνει δύο ή περισσότερα αρχεία· Append εισάγει μια σειρά σελίδων από ένα αρχείο σε άλλο· Extract εξάγει μια σειρά σελίδων ή μία μόνο σελίδα σε νέο αρχείο· Delete αφαιρεί μια σελίδα· και τα SplitFromFirst / SplitToEnd / SplitToPages / SplitToBulks διαιρούν ένα έγγραφο σε σελίδα, ανά σελίδα ή σε τμήματα σταθερού μεγέθους. Τα MakeBooklet και MakeNUp αναδιατάσσουν τις σελίδες για βιβλιαδότηση ή εκτύπωση N-up, και τα ResizeContents / AddMargins / AddPageBreak προσαρμόζουν τη γεωμετρία των σελίδων σε όλο το αρχείο. Οι περισσότερες λειτουργίες έχουν μια αντίστοιχη έκδοση με πρόθεμα Try που επιστρέφει false αντί να ρίχνει εξαίρεση σε περίπτωση αποτυχίας.

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

Απόδοση σελίδων σε εικόνες με PdfConverter

PdfConverter αποδίδει τις σελίδες ενός δεσμευμένου εγγράφου σε raster μορφές. DoConvert() προετοιμάζει το εύρος σελίδων (StartPage / EndPage) για επανάληψη· HasNextImage () / GetNextImage(outputFile) στη συνέχεια προχωρούν στις σελίδες μία τη φορά. SaveAsTIFF γράφει ολόκληρο το εύρος σε ένα ενιαίο πολυσελιδικό TIFF, με υπερφορτώσεις για ανάλυση, συμπίεση και TiffSettings. Τα RenderingOptions και Resolution ελέγχουν την ποιότητα rasterization, και το ImageMergeMode (Vertical, Horizontal, Center) καθορίζει πώς συνδυάζονται πολλές αποδοθείσες εικόνες σελίδων όταν ένας καλών ενοποιεί τις σε μία εικόνα.

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

Κρυπτογράφηση εγγράφων με PdfFileSecurity

PdfFileSecurity δεσμεύει ένα αρχείο πηγής και εφαρμόζει ή αφαιρεί κρυπτογράφηση. EncryptFile(userPassword, ownerPassword, privilege, keySize) κρυπτογραφεί με ένα DocumentPrivilege (δημιουργημένο με τον προεπιλεγμένο κατασκευαστή και boolean setters όπως τα AllowPrint, AllowCopy, AllowModifyContents) και ένα KeySize (x40, x128 ή x256); η υπερφόρτωση που δέχεται ένα πέμπτο όρισμα cipher επιλέγει ρητά το Algorithm (RC4 ή AES). Τα DecryptFile( ownerPassword), ChangePassword και SetPrivilege καλύπτουν τις υπόλοιπες περιπτώσεις διαχείρισης κωδικού πρόσβασης, καθεμία με μια μη-εξαιρέσιμη παραλλαγή με πρόθεμα Try.

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

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

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

Υπογραφή και επαλήθευση με PdfFileSignature

PdfFileSignature υπογράφει, πιστοποιεί και ελέγχει ψηφιακές υπογραφές σε δεσμευμένο έγγραφο. Sign(sigName, reason, contact, location, signature) εφαρμόζει νέα υπογραφή σε υπάρχον πεδίο υπογραφής· Certify εφαρμόζει πιστοποιητική υπογραφή. GetSignatureNames(onlyEmpty) και GetBlankSignatureNames() επιστρέφουν τα πεδία υπογραφής του εγγράφου ως τιμές SignatureName, και VerifySignature(sigName) / IsCoversWholeDocument (sigName) ελέγχουν την εγκυρότητα και την κάλυψη. RemoveSignature και RemoveSignatures() αφαιρούν τις υπάρχουσες υπογραφές, και SetCertificate(pfxFile, password) παρέχει το διαπιστευτήριο υπογραφής πριν καλέσει το Sign.

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

Επισήμανση κεφαλίδων, υποσέλιδων και αριθμών σελίδων με PdfFileStamp

PdfFileStamp τοποθετεί επαναλαμβανόμενο περιεχόμενο σε κάθε σελίδα ενός δεσμευμένου αρχείου. AddPageNumber(format) τοποθετεί μια ετικέτα αριθμού σελίδας χρησιμοποιώντας έναν αρχικό αριθμό και προαιρετικές ρητές συντεταγμένες· AddHeader(text, topMargin) και AddFooter(text, bottomMargin) προσθέτουν επαναλαμβανόμενο κείμενο κεφαλίδας/υποσέλιδου σε συγκεκριμένο περιθώριο, με υπερφορτώσεις για αριστερά/δεξιά περιθώρια. KeepSecurity διατηρεί τυχόν υπάρχουσα κρυπτογράφηση στο αρχείο εξόδου, και Close() ολοκληρώνει και απελευθερώνει το δεσμευμένο έγγραφο.

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

Ανάγνωση και εγγραφή πληροφοριών εγγράφου με PdfFileInfo

PdfFileInfo διαβάζει και ξαναγράφει το κλασικό λεξικό PDF /Info και τη βασική γεωμετρία ανά σελίδα χωρίς να ανοίγει το πλήρες μοντέλο αντικειμένων. Author, Title, Subject, Keywords, CreationDate και ModDate είναι ιδιότητες ανάγνωσης/εγγραφής· Producer και GetPdfVersion() είναι μόνο για ανάγνωση. GetPageWidth, GetPageHeight και GetPageRotation επιστρέφουν τη γεωμετρία ανά σελίδα βάσει αριθμού σελίδας, και IsEncrypted() / HasOpenPassword() / HasEditPassword() αναφέρουν την κατάσταση προστασίας του εγγράφου. SaveNewInfo(outputFile) γράφει τις αλλαγές πίσω.

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

Επανατοποθέτηση σελίδων με PdfPageEditor

PdfPageEditor μετακινεί, αλλάζει το μέγεθος και περιστρέφει το περιεχόμενο της σελίδας ως ένα μπλοκ. MovePosition(offsetX, offsetY) μετατοπίζει το περιεχόμενο στις σελίδες που επιλέγονται από το ProcessPages; Zoom το κλιμακώνει. Alignment (ένα AlignmentType — Left, Center ή Right, το καθένα λαμβάνεται από τη αντίστοιχη στατική μέθοδο) και VerticalAlignment (ένα VerticalAlignmentType — Top, Center, Bottom) ελέγχουν πώς το περιεχόμενο τοποθετείται μέσα στο στοχευόμενο PageSize μόλις εκτελεστεί το ApplyChanges(). GetPageRotation διαβάζει την τρέχουσα περιστροφή μιας σελίδας σε μοίρες.

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

Διαχείριση μεταδεδομένων XMP με PdfXmpMetadata

PdfXmpMetadata είναι μια διεπαφή τύπου χάρτη πάνω από το πακέτο XMP ενός εγγράφου. Οι Add(key, value), Remove(key), Contains(key) / ContainsKey(key) και TryGetValue(key, value) διαχειρίζονται μεμονωμένες καταχωρήσεις· οι Keys() και Values() απαριθμούν ολόκληρο το πακέτο. Ο RegisterNamespaceURI(prefix, namespaceURI) δηλώνει ένα προσαρμοσμένο χώρο ονομάτων XMP πριν προσθέσετε ιδιότητες σε αυτό. Τα γνωστά ονόματα ιδιοτήτων παρατίθενται στο DefaultMetadataProperties (CreateDate, CreatorTool, Identifier, ModifyDate, Nickname, Thumbnails και άλλα), και το PropertyFlag (ReadOnly, Required, NoExport) περιγράφει τους περιορισμούς του σχήματος μιας καταχωρημένης ιδιότητας.

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

Συμβουλές και Καλές Πρακτικές

• Κάθε διεπαφή ακολουθεί το ίδιο BindPdf (ή έναν κατασκευαστή που δέχεται όνομα αρχείου) → λειτουργία → ακολουθία Save/Close — η εκμάθηση μιας διεπαφής μεταφέρεται άμεσα στην επόμενη.
• Προτιμήστε τις μεθόδους με πρόθεμα Try στο PdfFileEditor και PdfFileSecurity όταν επεξεργάζεστε αρχεία από μη αξιόπιστη ή απρόβλεπτη πηγή — επιστρέφουν false σε περίπτωση αποτυχίας αντί να ρίχνουν εξαίρεση.
• Οι μέθοδοι PdfFileEditor δέχονται διαδρομές αρχείων, όχι ένα δεσμευμένο Document — δεν χρειάζεται να ανοίξετε το πηγαίο αρχείο μόνοι σας πριν καλέσετε τις Concatenate, Extract ή SplitFromFirst.
• Οι διεπαφές τυλίγουν το βασικό μοντέλο αντικειμένων αντί να το αντικαθιστούν: το Facade εκθέτει το υποκείμενο Document() για περιπτώσεις που μια μέθοδος διεπαφής δεν καλύπτει.
• Καλέστε το Close() (ή αφήστε τη διεπαφή να βγει εκτός εμβέλειας, όπου υποστηρίζεται) μόλις τελειώσετε με ένα δεσμευμένο έγγραφο ώστε να απελευθερώσετε το υποκείμενο άνοιγμα αρχείου.

Κοινά Προβλήματα

FAQ

Ποια είναι η διαφορά μεταξύ μιας facade και του core Document API;

Οι facades παρέχουν μια μικρή, καθοδηγούμενη από εργασία επιφάνεια μεθόδων για μία εργασία — τη συμπλήρωση μιας φόρμας, τη συγχώνευση αρχείων, τη σήμανση σελίδων. Ο core API (Document, Page, Annotation) δίνει πλήρη πρόσβαση σε κάθε αντικείμενο PDF. Οι facades που εκθέτουν το Document() (μέσω της βασικής κλάσης Facade) σας επιτρέπουν να επιστρέψετε στο core μοντέλο για οτιδήποτε δεν καλύπτεται από μια μέθοδο facade.

Χρειάζεται να καλέσω το BindPdf πριν από κάθε μέθοδο facade;

Ναι, για τις facades που υλοποιούν το IFacade — το BindPdf (ή μια ισοδύναμη υπερφόρτωση κατασκευής, όπως με το PdfExtractor(doc)) πρέπει να εκτελεστεί πριν από οποιαδήποτε λειτουργία που διαβάζει ή τροποποιεί το συνδεδεμένο έγγραφο.

Μπορούν οι λειτουργίες PdfFileEditor να αλυσιδωθούν;

Κάθε μέθοδος PdfFileEditor διαβάζει το δικό της αρχείο εισόδου και γράφει το δικό της αρχείο εξόδου, έτσι ώστε να αλυσίδετε τις λειτουργίες τροφοδοτώντας το αρχείο εξόδου μιας μεθόδου στην είσοδο της επόμενης κλήσης — για παράδειγμα, Concatenate στο merged.pdf, έπειτα Extract από το merged.pdf.

Ποιες facades υποστηρίζουν λειτουργία σφάλματος χωρίς εξαίρεση (non-throwing error mode);

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, και σχετικές Try* μεθόδους) και PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) προσφέρουν και τα δύο εναλλακτικές με πρόθεμα Try που επιστρέφουν bool αντί να ρίχνουν.

Περίληψη API Reference

Δείτε επίσης

• Aspose.PDF — Enterprise Documentation