חזיתות API

חזיתות API

א facade הוא עטיפה מפושטת, ממוקדת משימה, על הליבה Document / Page / Annotation מודל האובייקטים. במקום לנווט בעצמך בעץ העמודים, אתה קושר facade למקור PDF, קורא למספר קטן של שיטות ברמה גבוהה, ושומר את התוצאה. כל facade ב- Aspose::Pdf::Facades מיישמת את אותו חוזה מינימלי שהוגדר על-ידי IFacade (BindPdf, Close) ו-כאשר ה-facade מייצר פלט, 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 מוסיף Save(destFile) עבור facades שמייצרות פלט. 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 (ו-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 מכסים את שאר מקרי ניהול הסיסמאות, כל אחד עם גרסה עם קידומת 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

מה ההבדל בין חזית לבין המסמך הליבה API?

חזיות מספקות ממשק שיטות קטן, ממוקד משימה לעבודה אחת — מילוי טופס, מיזוג קבצים, חותמת על דפים. הליבה API (Document, Page, Annotation) נותנת גישה מלאה לכל אובייקט PDF. חזיות שמחשיפות Document() (דרך מחלקת הבסיס Facade) מאפשרות לחזור למודל הליבה לכל דבר ששיטת חזית אינה מכסה.

האם עליי לקרוא ל-BindPdf לפני כל שיטת חזית?

כן, עבור חזיות שמיישמות IFacade — BindPdf (או עומס בנאי שווה ערך, כמו עם PdfExtractor(doc)) חייב לרוץ לפני כל פעולה שקוראת או משנה את המסמך הקשור.

האם ניתן לקשר פעולות PdfFileEditor?

כל שיטת PdfFileEditor קוראת את קובץ הקלט שלה וכותבת את קובץ הפלט שלה, ולכן אתה יוצר שרשרת של פעולות על-ידי הזנת קובץ הפלט של שיטה אחת לקובץ הקלט של הקריאה הבאה — לדוגמה, Concatenate אל merged.pdf, ואז Extract מ-merged.pdf.

אילו חזיות תומכות במצב שגיאה non-throwing?

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst, ו-Try* שיטות קשורות) ו-PdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) שניהם מציעים חלופות עם קידומת Try שמחזירות bool במקום לזרוק.

API Reference סיכום

ראה גם

• Aspose.PDF — Enterprise Documentation