الواجهات API

الواجهات API

أ facade هو غلاف مبسط وموجه للمهام فوق النواة Document / Page / Annotation نموذج الكائن. بدلاً من استعراض شجرة الصفحات بنفسك، تقوم بربط واجهة إلى ملف PDF مصدر، تستدعي مجموعة صغيرة من الأساليب عالية المستوى، وتحفظ النتيجة. كل واجهة في Aspose::Pdf::Facades تنفّذ نفس العقدة الدنيا المحددة بواسطة IFacade (BindPdf, Close) وحيث تُنتج الواجهة مخرجات، ISaveableFacade (Save). الفئة المجردة Facade and SaveableFacade توفر الفئات الأساسية التنفيذ الافتراضي للربط/الإغلاق/الحفظ الذي تبني عليه المحررات الملموسة أدناه: PdfAnnotationEditor, PdfBookmarkEditor, PdfContentEditor, PdfConverter, PdfExtractor, PdfFileEditor, PdfFileInfo, PdfFileSecurity, PdfFileSignature, PdfFileStamp, PdfPageEditor, PdfXmpMetadata، والتركيز على النماذج FormEditor / FormFieldFacade زوج.

فئات القاعدة للواجهة ودورة حياة الربط/الحفظ

IFacade يعلن عن BindPdf(srcFile) (كما أنه محمل فوق لقبول Document في الذاكرة) وClose(). ISaveableFacade يضيف Save(destFile) للواجهات التي تكتب مخرجات. Facade ينفّذ IFacade ويكشف عن Document() المرتبط بحيث يمكنك الرجوع إلى نموذج الكائنات الأساسي عندما لا يغطي أسلوب الواجهة ما تحتاجه؛ SaveableFacade يمدّ Facade بتنفيذ 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)، و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

ما الفرق بين الـ facade والنواة Document API?

توفر الـ facades سطح طريقة صغير وموجه للمهمة لعمل واحد — ملء نموذج، دمج ملفات، ختم صفحات. النواة API (Document, Page, Annotation) تمنح وصولاً كاملاً إلى كل كائن PDF. الـ facades التي تكشف عن Document() (عبر الفئة الأساسية Facade) تسمح لك بالعودة إلى نموذج النواة لأي شيء لا تغطيه طريقة الـ facade.

هل يجب عليّ استدعاء BindPdf قبل كل طريقة facade؟

نعم، بالنسبة للـ facades التي تُنفّذ IFacade — يجب تشغيل BindPdf (أو تحميل مُماثل للمنشئ، كما هو الحال مع PdfExtractor(doc)) قبل أي عملية تقرأ أو تعدّل المستند المرتبط.

هل يمكن ربط عمليات PdfFileEditor سلسلةً؟

كل طريقة من PdfFileEditor تقرأ ملف الإدخال الخاص بها وتكتب ملف الإخراج الخاص بها، لذا يمكنك ربط العمليات عن طريق تمرير ملف إخراج طريقة إلى ملف إدخال الطريقة التالية — على سبيل المثال، Concatenate إلى merged.pdf، ثم Extract من merged.pdf.

ما هي الـ facades التي تدعم وضع الأخطاء غير المتسبب في استثناء؟

PdfFileEditor (TryConcatenate, TryAppend, TryExtract, TrySplitFromFirst، وطرق Try* ذات الصلة) وPdfFileSecurity (TryEncryptFile, TryDecryptFile, TrySetPrivilege, TryChangePassword) كلاهما يقدمان بدائل مسبوقة بـTry تُعيد bool بدلاً من إلقاء استثناء.

API Reference ملخص

انظر أيضاً

• Aspose.PDF — Enterprise Documentation