نمایه‌ها 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) را اعلام می‌کند (همچنین به‌صورت overload برای پذیرش یک Document در حافظهٔ موقت موجود است) و Close(). ISaveableFacade Save(destFile) را برای facadeهایی که خروجی می‌نویسند اضافه می‌کند. 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) نحوهٔ ارسال داده‌های فرم توسط دکمهٔ submit را کنترل می‌کند، و 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 است، بر حسب enum 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) تصاویر رستری تعبیه‌شده را به همان شیوه‌ای که 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 چندصفحه‌ای می‌نویسد، با overloadهایی برای وضوح، فشرده‌سازی و 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 (که با سازندهٔ پیش‌فرض و setterهای بولی مانند AllowPrint، AllowCopy، AllowModifyContents ساخته می‌شود) و یک KeySize (x40، x128 یا x256) رمزنگاری می‌کند؛ overloadی که پنجمین آرگومان 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 و سند اصلی API چیست؟

Facadeها سطح متد کوچک و ماموریت‌محور برای یک کار را فراهم می‌کنند — پر کردن فرم، ادغام فایل‌ها، مهرگذاری صفحات. API اصلی (Document, Page, Annotation) دسترسی کامل به هر شیء PDF را می‌دهد. Facadeهایی که Document() را (از طریق کلاس پایه Facade) افشا می‌کنند، به شما امکان می‌دهند برای هر کاری که متد facade پوشش نمی‌دهد، به مدل اصلی بازگردید.

آیا باید قبل از هر متد facade، BindPdf را فراخوانی کنم؟

بله، برای facadeهایی که IFacade را پیاده‌سازی می‌کنند — BindPdf (یا یک overload سازنده معادل، همانند PdfExtractor(doc)) باید قبل از هر عملیاتی که سند مرتبط را می‌خواند یا تغییر می‌دهد، اجرا شود.

آیا می‌توان عملیات PdfFileEditor را زنجیر کرد؟

هر متد PdfFileEditor فایل ورودی خود را می‌خواند و فایل خروجی خود را می‌نویسد، بنابراین برای زنجیر کردن عملیات، خروجی یک متد را به عنوان ورودی متد بعدی می‌دهید — به عنوان مثال، Concatenate به merged.pdf، سپس Extract از merged.pdf.

کدام facadeها حالت خطای بدون پرتاب (non-throwing) را پشتیبانی می‌کنند؟

PdfFileEditor (TryConcatenate، TryAppend، TryExtract، TrySplitFromFirst، و روش‌های مرتبط Try*) و PdfFileSecurity (TryEncryptFile، TryDecryptFile، TrySetPrivilege، TryChangePassword) هر دو گزینه‌های پیش‌وند Try ارائه می‌دهند که به جای پرتاب کردن، bool برمی‌گردانند.

API Reference خلاصه

همچنین ببینید:

• Aspose.PDF — Enterprise Documentation