كيفية العمل مع الواجهات API في Aspose.PDF FOSS for C++

Aspose.PDF FOSS للـ C++ يجمع مجموعة من فئات الواجهة العليا ومحررات — PdfExtractor، PdfBookmarkEditor، PdfContentEditor، PdfAnnotationEditor، FormEditor، PdfFileEditor، وPdfConverter بينها — في مساحة الأسماء Aspose::Pdf::Facades. كل واحدة تغلف مهمة صيانة مستند واحدة فوق الـ Document API الأساسي، بحيث يمكنك استخراج المحتوى، تعديل الإشارات المرجعية، أو ملء حقول النموذج دون الحاجة إلى كتابة روتين يدوي للتنقل عبر الصفحات والكائنات. يركز هذا الدليل على PdfExtractor، الواجهة المستخدمة لسحب المرفقات المضمنة، نص الصفحة، والصور المضمنة من ملف PDF موجود.

دليل خطوة بخطوة

الخطوة 1: تثبيت الحزمة

أضف Aspose.PDF FOSS للـ C++ كدليل فرعي في CMake واربط هدف المكتبة الثابتة:

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp.git

add_subdirectory(Aspose.PDF-FOSS-for-Cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

تأكد من أن سلسلة الأدوات خطوة الربط تحل بشكل صحيح قبل كتابة أي كود للواجهة:

cmake -S . -B build
cmake --build build

بناء نظيف باستخدام مُترجم C++20 يؤكد أن aspose_pdf_foss مرتبط داخل your_app.

الخطوة 2: استيراد الفئات المطلوبة

PdfExtractor موجود تحت aspose/pdf/facades/، جنبًا إلى جنب مع Document من مساحة الاسم الأساسية:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/facades/pdf_extractor.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Facades;

الخطوة 3: ربط مستند بـ PdfExtractor

كل فئة واجهة تستمد من قاعدة Facade مشتركة تُظهر BindPdf(srcFile) و BindPdf(srcDoc) لإرفاقها بمستند بعد الإنشاء. كما يقبل PdfExtractor Document المفتوح مسبقًا مباشرةً في المُنشئ الخاص به، وهو النمط المستخدم طوال هذا الدليل:

Document doc("input.pdf");
PdfExtractor extractor(doc);

الخطوة 4: استخراج المرفقات المضمنة للملفات

تحقق من Document::EmbeddedFiles() أولاً، ثم اقرأ أسماء المرفقات باستخدام GetAttachNames() واسحب بايتات المرفق إلى القرص باستخدام GetAttachment():

#include <iostream>

if (doc.EmbeddedFiles().Count() > 0) {
    std::vector<std::string> names = extractor.GetAttachNames();
    for (const auto& name : names) {
        std::cout << "Attachment: " << name << "\n";
    }

    // Writes the bytes of the first attachment to disk
    extractor.GetAttachment("extracted_attachment.bin");
}

الخطوة 5: استخراج النص من كل صفحة

ExtractText() يليه GetText() يكتب نص المستند بالكامل إلى ملف واحد:

extractor.ExtractText();
extractor.GetText("extracted_text.txt");

للتقاط ملف واحد لكل صفحة بدلاً من ذلك، حدّد نطاق الصفحات باستخدام StartPage() / EndPage()، ثم شغّل HasNextPageText() / GetNextPageText() في حلقة، مع إعطاء كل استدعاء مسار إخراج خاص به:

extractor.StartPage(1);
extractor.EndPage(doc.Pages().Count());

int pageNumber = extractor.StartPage();
while (extractor.HasNextPageText()) {
    std::string outputFile = "page_" + std::to_string(pageNumber) + ".txt";
    extractor.GetNextPageText(outputFile);
    ++pageNumber;
}

الخطوة 6: استخراج الصور المدمجة

ExtractImage() يجهّز مؤشر الصورة؛ ثم HasNextImage() / GetNextImage() يتنقل عبر الصور واحدةً تلو الأخرى، ويكتب كل واحدة إلى المسار الذي تمرره:

extractor.ExtractImage();

int imageIndex = 1;
while (extractor.HasNextImage()) {
    std::string outputFile = "extracted_image_" + std::to_string(imageIndex);
    if (extractor.GetNextImage(outputFile)) {
        ++imageIndex;
    }
}

المشكلات الشائعة والحلول

GetAttachNames() يرجع متجهًا فارغًا. ملف PDF المصدر لا يحتوي على ملفات مضمنة. تحقق doc.EmbeddedFiles().Count() قبل استدعاء أي طريقة مرفق على PdfExtractor حتى لا تحاول استخراج من مستند لم يكن لديه مرفقات أبدًا.

حلقة نص الصفحة لا تدخل الجسم أبدًا. HasNextPageText() returns false فورًا إذا StartPage() / EndPage() لم يتم تعيينها أبدًا، أو إذا تم تعيينها إلى نطاق خارج عدد صفحات المستند الفعلي. عيّن النطاق صراحةً من doc.Pages().Count() قبل الفحص HasNextPageText().

GetNextImage() returns false في الاستدعاء الأول. ExtractImage() يجب استدعاؤه مرة واحدة لتهيئة مؤشر الصورة قبل أن تتحقق HasNextImage() أو استدعاء GetNextImage(). استدعاء GetNextImage() بدون سابقة ExtractImage() استدعاء غير معرف من منظور المستدعي — دائمًا استدعِ ExtractImage() أولاً.

كل صورة أو ملف نص صفحة مستخرج يكتب فوق السابق. GetNextImage() and GetNextPageText() كل منها يأخذ مسار إخراج حرفي؛ الواجهة لا تُنشئ أسماء ملفات فريدة لك. أنشئ مسارًا مميزًا لكل تكرار (على سبيل المثال، عن طريق إلحاق عدّاد متزايد) كما هو موضح في الخطوتين 5 و6.

خطأ ربط: إشارة غير معرفة إلى aspose_pdf_foss الرموز. Confirm add_subdirectory() يشير إلى جذر المستودع المستنسخ و ذلك target_link_libraries() يسمّي الـ aspose_pdf_foss الهدف بدقة، مع معيار C++20 مُكوَّن لـ your_app.

الأسئلة المتكررة

ما الفرق بين الواجهات API والوثيقة الأساسية API؟

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

هل يمكنني تعديل الإشارات المرجعية أو ملء حقول النماذج بنفس الطريقة التي أستخرج بها المحتوى باستخدام PdfExtractor؟

نعم. PdfBookmarkEditor (مع CreateBookmarks()، ModifyBookmarks()، ExtractBookmarks()، وDeleteBookmarks()) وFormEditor (مع AddField()، RemoveField()، وSetFieldAttribute()) يعيشان في نفس مساحة الاسم Aspose::Pdf::Facades ويتبعان نمط include/construct نفسه الموضح في الخطوتين 2 و3 — كل منهما يعمل فقط على جزء مختلف من الوثيقة.

هل يمكن لـ PdfExtractor قراءة ملف PDF محمي بكلمة مرور؟

قم بتعيين كلمة المرور قبل استدعاء أي طريقة استخراج:

extractor.Password("owner-or-user-password");

PdfExtractor::Password() هي خاصية قراءة/كتابة عادية، لذا يجب تعيينها قبل ExtractText()، ExtractImage()، أو طرق المرفقات.

ماذا يحدث إذا كان ملف PDF لا يحتوي على نص أو صور أو مرفقات لاستخراجها؟

لا يحدث أي استثناء. GetAttachNames() تُعيد متجهًا فارغًا، وHasNextPageText() / HasNextImage() تُعيد false في الفحص الأول، لذا فإن جسم الحلقة المقابل ببساطة لا يُنفّذ أبداً.

أي ملف header يجب أن أضمّنه لفئة واجهة معينة؟

كل فئة واجهة (facade) تُرفق ملف header خاص بها تحت aspose/pdf/facades/، مطابقةً لاسم الفئة: pdf_extractor.hpp لـ PdfExtractor، pdf_bookmark_editor.hpp لـ PdfBookmarkEditor، form_editor.hpp لـ FormEditor، وbookmark.hpp لأنواع القيم Bookmark / Bookmarks.