फ़ासाड्स API

फ़ेसाड्स API

A facade कोर पर एक सरल, कार्य-उन्मुख रैपर है Document / Page / Annotation ऑब्जेक्ट मॉडल। पेज ट्री को स्वयं चलाने के बजाय, आप एक फेसेड को स्रोत PDF से बाइंड करते हैं, उच्च-स्तरीय विधियों के छोटे सेट को कॉल करते हैं, और परिणाम को सहेजते हैं। प्रत्येक फेसेड में Aspose::Pdf::Facades एक ही न्यूनतम कॉन्ट्रैक्ट को लागू करता है जो परिभाषित है IFacade (BindPdf, Close) और, जहाँ फेसेड आउटपुट उत्पन्न करता है, ISaveableFacade (Save). सारभूत Facade and SaveableFacade बेस क्लासेज डिफॉल्ट bind/close/save इम्प्लीमेंटेशन प्रदान करती हैं जिस पर नीचे के कंक्रीट एडिटर्स बनते हैं: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata, और फ़ॉर्म-फ़ोकस्ड FormEditor / FormFieldFacade जोड़ी।

Facade बेस क्लासेस और bind/save जीवनचक्र

IFacade BindPdf(srcFile) घोषित करता है (जिसे इन-मेरी Document स्वीकार करने के लिए भी ओवरलोड किया गया है) और Close()। ISaveableFacade आउटपुट लिखने वाले facades के लिए Save(destFile) जोड़ता है। Facade IFacade को लागू करता है और बाउंड Document() को उजागर करता है ताकि जब कोई facade मेथड आपकी जरूरत को कवर न करे, तो आप कोर ऑब्जेक्ट मॉडल में वापस जा सकें; 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 एक आउटलाइन को 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 enum के अनुसार), और 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) एम्बेडेड रास्टर इमेजेज़ को उसी तरह निकालते हैं जैसे GetNextPageText पृष्ठों को चलाता है।

PdfFileEditor के साथ फ़ाइलों को असेंबल और विभाजित करना

PdfFileEditor फ़ाइल पाथ्स पर काम करता है न कि बाउंड Document पर, इसलिए हर मेथड इनपुट/आउटपुट फ़ाइलनाम सीधे लेता है। Concatenate (और non-throwing 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 बाउंड दस्तावेज़ पृष्ठों को रास्टर फॉर्मैट्स में रेंडर करता है। DoConvert() पृष्ठ रेंज (StartPage / EndPage) को इटरेशन के लिए तैयार करता है; HasNextImage () / GetNextImage(outputFile) फिर पृष्ठों को एक-एक करके पार करता है। SaveAsTIFF पूरी रेंज को एक ही मल्टी-पेज TIFF में लिखता है, जिसमें रेज़ोल्यूशन, कम्प्रेशन, और TiffSettings के लिए ओवरलोड्स होते हैं। RenderingOptions और Resolution रास्टराइज़ेशन क्वालिटी को नियंत्रित करते हैं, और 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 (डिफ़ॉल्ट कंस्ट्रक्टर और बूलियन सेटर जैसे AllowPrint, AllowCopy, AllowModifyContents के साथ निर्मित) और एक KeySize (x40, x128, या x256) के साथ एन्क्रिप्ट करता है; पाँचवाँ cipher आर्ग्युमेंट लेने वाला ओवरलोड स्पष्ट रूप से Algorithm (RC4 या AES) चुनता है। DecryptFile( ownerPassword), ChangePassword, और SetPrivilege शेष पासवर्ड-मैनेजमेंट मामलों को कवर करते हैं, प्रत्येक के पास एक non-throwing 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();

PdfXmpMetadata के साथ XMP मेटाडेटा प्रबंधन

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 क्रम का पालन करता है — एक फ़ेसाड सीखना सीधे अगले में स्थानांतरित हो जाता है।
• अविश्वसनीय या अस्थिर स्रोत से फ़ाइलें प्रोसेस करते समय PdfFileEditor और PdfFileSecurity पर Try-प्रिफ़िक्स वाले मेथड्स को प्राथमिकता दें — वे त्रुटि पर false लौटाते हैं, फेंकने के बजाय।
• PdfFileEditor मेथड्स फ़ाइल पथ लेते हैं, बंधे हुए Document नहीं — आपको Concatenate, Extract, या SplitFromFirst को कॉल करने से पहले स्रोत फ़ाइल स्वयं खोलने की आवश्यकता नहीं है।
• फ़ेसाड कोर ऑब्जेक्ट मॉडल को लपेटते हैं, उसे प्रतिस्थापित नहीं करते: Facade उन मामलों के लिए अंतर्निहित Document() को उजागर करता है जहाँ फ़ेसाड मेथड कवरेज नहीं करता।
• जब आप बंधे हुए दस्तावेज़ के साथ काम समाप्त कर लें, तो अंतर्निहित फ़ाइल हैंडल को रिलीज़ करने के लिए Close() को कॉल करें (या जहाँ समर्थित हो, फ़ेसाड को स्कोप से बाहर निकलने दें)।

सामान्य समस्याएँ

FAQ

Facade और कोर Document API के बीच क्या अंतर है?

Facades एक छोटे, कार्य-उन्मुख मेथड सतह प्रदान करते हैं एक काम के लिए — फ़ॉर्म भरना, फ़ाइलें मिलाना, पृष्ठों को स्टैम्प करना। कोर API (Document, Page, Annotation) प्रत्येक PDF ऑब्जेक्ट तक पूर्ण पहुँच देता है। Facades जो Document() को उजागर करते हैं ( Facade बेस क्लास के माध्यम से) आपको कोर मॉडल में वापस ले जाते हैं उन सभी चीज़ों के लिए जो किसी facade मेथड द्वारा कवर नहीं की गई हों।

क्या मुझे हर facade मेथड से पहले BindPdf को कॉल करना चाहिए?

हाँ, उन facades के लिए जो IFacade को लागू करती हैं — BindPdf (या एक समकक्ष कंस्ट्रक्टर ओवरलोड, जैसे PdfExtractor(doc) के साथ) को किसी भी ऑपरेशन से पहले चलाना आवश्यक है जो बाउंड डॉक्यूमेंट को पढ़ता या संशोधित करता है।

क्या PdfFileEditor ऑपरेशन्स को चेन किया जा सकता है?

प्रत्येक PdfFileEditor मेथड अपना इनपुट फ़ाइल पढ़ता है और अपना आउटपुट फ़ाइल लिखता है, इसलिए आप ऑपरेशन्स को चेन करते हैं एक मेथड की आउटपुट फ़ाइल को अगले कॉल की इनपुट फ़ाइल के रूप में फीड करके — उदाहरण के लिए, Concatenate को merged.pdf में, फिर Extract को merged.pdf से।

कौन से facades non-throwing एरर मोड का समर्थन करते हैं?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, और संबंधित Try* मेथड्स) और PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) दोनों Try-प्रिफिक्स्ड विकल्प प्रदान करते हैं जो bool लौटाते हैं न कि थ्रो करते हैं।

API Reference सारांश

यह भी देखें

• Aspose.PDF — Enterprise Documentation