Wie man mit den Facades API in Aspose.PDF FOSS for C++ arbeitet

Aspose.PDF FOSS for C++ gruppiert einen Satz von höherwertigen Fassaden- und Editor-Klassen — PdfExtractor, PdfBookmarkEditor, PdfContentEditor, PdfAnnotationEditor, FormEditor, PdfFileEditor und PdfConverter darunter — im Aspose::Pdf::Facades Namespace. Jede von ihnen kapselt eine einzelne Dokumenten-Wartungsaufgabe auf dem Kern-Document API, sodass Sie Inhalte extrahieren, Lesezeichen bearbeiten oder Formularfelder ausfüllen können, ohne selbst die zugrunde liegenden Seiten- und Objekt-Durchläufe manuell zu implementieren. Dieser Leitfaden konzentriert sich auf PdfExtractor, die Fassade, die verwendet wird, um eingebettete Dateianhänge, Seitentext und eingebettete Bilder aus einem bestehenden PDF zu extrahieren.

Schritt-für-Schritt-Anleitung

Schritt 1: Paket installieren

Fügen Sie Aspose.PDF FOSS for C++ als CMake-Unterverzeichnis hinzu und verlinken Sie das statische Bibliotheksziel:

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)

Stellen Sie sicher, dass die Toolchain und der Link-Schritt korrekt aufgelöst werden, bevor Sie irgendeinen Fassaden-Code schreiben:

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

Ein sauberer Build mit einem C++20-Compiler bestätigt, dass aspose_pdf_foss in your_app verlinkt ist.

Schritt 2: Erforderliche Klassen importieren

PdfExtractor befindet sich unter aspose/pdf/facades/, zusammen mit Document aus dem Kern-Namespace:

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

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

Schritt 3: Ein Dokument an PdfExtractor binden

Jede Fassadenklasse leitet sich von einer gemeinsamen Facade-Basis ab, die BindPdf(srcFile) und BindPdf(srcDoc) bereitstellt, um sie nach der Konstruktion an ein Dokument anzuhängen. PdfExtractor akzeptiert außerdem ein bereits geöffnetes Document direkt im Konstruktor, was das in dieser Anleitung verwendete Muster ist:

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

Schritt 4: Eingebettete Dateianhänge extrahieren

Prüfen Sie zuerst Document::EmbeddedFiles(), lesen Sie dann die Anhangsnamen mit GetAttachNames() und holen Sie die Bytes eines Anhangs mit GetAttachment() auf die Festplatte:

#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");
}

Schritt 5: Text von jeder Seite extrahieren

ExtractText() gefolgt von GetText() schreibt den gesamten Text des Dokuments in eine einzelne Datei:

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

Um stattdessen eine Datei pro Seite zu erfassen, setzen Sie den Seitenbereich mit StartPage() / EndPage(), und steuern dann HasNextPageText() / GetNextPageText() in einer Schleife, wobei jedem Aufruf sein eigener Ausgabepfad zugewiesen wird:

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;
}

Schritt 6: Eingebettete Bilder extrahieren

ExtractImage() initialisiert den Bildcursor; HasNextImage() / GetNextImage() gehen dann die Bilder nacheinander durch und schreiben jedes in den von Ihnen übergebenen Pfad:

extractor.ExtractImage();

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

Häufige Probleme und Lösungen

GetAttachNames() gibt einen leeren Vektor zurück. Die Quell-PDF enthält keine eingebetteten Dateien. Überprüfen doc.EmbeddedFiles().Count() bevor Sie irgendeine Anhangsmethode aufrufen PdfExtractor damit Sie nicht versuchen, aus einem Dokument zu extrahieren, das nie Anhänge hatte.

Die Seiten-Text-Schleife betritt nie den Body. HasNextPageText() returns false sofort, wenn StartPage() / EndPage() nie gesetzt wurden, oder wenn sie auf einen Bereich außerhalb der tatsächlichen Seitenanzahl des Dokuments gesetzt wurden. Setzen Sie den Bereich explizit von doc.Pages().Count() vor dem Überprüfen HasNextPageText().

GetNextImage() returns false beim ersten Aufruf. ExtractImage() muss einmal aufgerufen werden, um den Bildcursor zu initialisieren, bevor Sie prüfen HasNextImage() oder aufrufen GetNextImage(). Aufrufen GetNextImage() ohne vorherigen ExtractImage() Aufruf ist aus Sicht des Aufrufers undefiniert — rufen Sie immer ExtractImage() zuerst auf.

Jede extrahierte Bild- oder Seitentextdatei überschreibt die vorherige. GetNextImage() and GetNextPageText() jede nimmt einen wörtlichen Ausgabepfad; die Fassade erzeugt keine eindeutigen Dateinamen für Sie. Erstellen Sie pro Durchlauf einen eindeutigen Pfad (zum Beispiel, indem Sie einen inkrementierenden Zähler anhängen), wie in Schritt5 und6 gezeigt.

Link-Fehler: undefinierte Referenz auf aspose_pdf_foss Symbole. Confirm add_subdirectory() zeigt auf die Wurzel des geklonten Repositorys und dass target_link_libraries() benennt das aspose_pdf_foss Ziel exakt, mit einem für C++20 konfigurierten Standard your_app.

Häufig gestellte Fragen

Was ist der Unterschied zwischen den Fassaden API und dem Kern-Dokument API?

Der Kern-Document API (Document, PageCollection, Annotation usw.) stellt das PDF-Objektmodell direkt bereit. Fassaden-Klassen wie PdfExtractor bauen darauf auf und verpacken eine spezifische mehrstufige Aufgabe—Extrahieren von Inhalten, Bearbeiten von Lesezeichen, Ausfüllen von Formularfeldern—hinter einer schmaleren, zweckgerichteten Schnittstelle.

Kann ich Lesezeichen bearbeiten oder Formularfelder ausfüllen, genau wie ich Inhalte mit PdfExtractor extrahiere?

Ja. PdfBookmarkEditor (mit CreateBookmarks(), ModifyBookmarks(), ExtractBookmarks() und DeleteBookmarks()) und FormEditor (mit AddField(), RemoveField() und SetFieldAttribute()) befinden sich im selben Aspose::Pdf::Facades-Namensraum und folgen dem gleichen Include-/Konstruktions-Muster, das in den Schritten2 und3 gezeigt wird—jeder arbeitet lediglich an einem anderen Teil des Dokuments.

Kann PdfExtractor ein passwortgeschütztes PDF lesen?

Setzen Sie das Passwort, bevor Sie irgendeine Extraktionsmethode aufrufen:

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

PdfExtractor::Password() ist eine einfache Lese-/Schreib-Eigenschaft, daher muss sie vor ExtractText(), ExtractImage() oder den Anhangsmethoden gesetzt werden.

Was passiert, wenn das PDF keinen Text, keine Bilder oder Anhänge zum Extrahieren enthält?

Es wird nichts geworfen. GetAttachNames() liefert einen leeren Vektor, und HasNextPageText() / HasNextImage() geben beim ersten Check false zurück, sodass der entsprechende Schleifenkörper einfach nie ausgeführt wird.

Welche Header-Datei soll ich für eine bestimmte Facade-Klasse einbinden?

Jede Facade-Klasse liefert ihren eigenen Header unter aspose/pdf/facades/, der dem Klassennamen entspricht: pdf_extractor.hpp für PdfExtractor, pdf_bookmark_editor.hpp für PdfBookmarkEditor, form_editor.hpp für FormEditor und bookmark.hpp für die Bookmark / Bookmarks Wertetypen.