Comment travailler avec les façades API dans Aspose.PDF FOSS for C++

Aspose.PDF FOSS for C++ regroupe un ensemble de classes de façade et d’éditeur de haut niveau — PdfExtractor, PdfBookmarkEditor, PdfContentEditor, PdfAnnotationEditor, FormEditor, PdfFileEditor et PdfConverter parmi elles — dans l’espace de noms Aspose::Pdf::Facades. Chacune encapsule une tâche unique de maintenance de document au-dessus du noyau Document API, de sorte que vous pouvez extraire du contenu, modifier les signets ou remplir les champs de formulaire sans implémenter manuellement les parcours de pages et d’objets sous-jacents. Ce guide se concentre sur PdfExtractor, la façade utilisée pour extraire les pièces jointes de fichiers intégrées, le texte des pages et les images incorporées d’un PDF existant.

Guide étape par étape

Étape 1: Installer le paquet

Ajoutez Aspose.PDF FOSS for C++ en tant que sous-répertoire CMake et liez la cible de bibliothèque statique:

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)

Vérifiez que la chaîne d’outils et l’étape de liaison se résolvent correctement avant d’écrire du code de façade:

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

Une construction propre avec un compilateur C++20 confirme que aspose_pdf_foss est lié à your_app.

Étape 2: Importer les classes requises

PdfExtractor se trouve sous aspose/pdf/facades/, aux côtés de Document du namespace core:

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

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

Étape 3: Lier un document à PdfExtractor

Chaque classe façade dérive d’une base commune Facade qui expose BindPdf(srcFile) et BindPdf(srcDoc) pour l’attacher à un document après construction. PdfExtractor accepte également un Document déjà ouvert directement dans son constructeur, ce qui constitue le modèle utilisé tout au long de ce guide:

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

Étape 4: Extraire les pièces jointes de fichiers incorporés

Vérifiez d’abord Document::EmbeddedFiles(), puis lisez les noms des pièces jointes avec GetAttachNames() et extrayez les octets d’une pièce jointe vers le disque avec 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");
}

Étape 5: Extraire le texte de chaque page

ExtractText() suivi de GetText() écrit le texte complet du document dans un seul fichier:

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

Pour capturer un fichier par page à la place, définissez la plage de pages avec StartPage() / EndPage(), puis pilotez HasNextPageText() / GetNextPageText() dans une boucle, en donnant à chaque appel son propre chemin de sortie:

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

Étape 6: Extraire les images intégrées

ExtractImage() prépare le curseur d’image; HasNextImage() / GetNextImage() parcourt ensuite les images une par une, en écrivant chacune dans le chemin que vous fournissez:

extractor.ExtractImage();

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

Problèmes courants et solutions

GetAttachNames() renvoie un vecteur vide. Le PDF source ne contient aucun fichier intégré. Vérifiez doc.EmbeddedFiles().Count() avant d’appeler toute méthode d’attachement sur PdfExtractor afin de ne pas tenter d’extraire d’un document qui n’a jamais eu de pièces jointes.

La boucle de texte de page n’entre jamais dans le corps. HasNextPageText() returns false immédiatement si StartPage() / EndPage() n’ont jamais été définies, ou si elles ont été définies sur une plage en dehors du nombre réel de pages du document. Définissez explicitement la plage à partir de doc.Pages().Count() avant de vérifier HasNextPageText().

GetNextImage() returns false lors du premier appel. ExtractImage() doit être appelé une fois pour initialiser le curseur d’image avant de vérifier HasNextImage() ou appeler GetNextImage(). En appelant GetNextImage() sans un appel préalable ExtractImage() l’appel est indéfini du point de vue de l’appelant — appelez toujours ExtractImage() d’abord.

Chaque image extraite ou fichier texte de page écrase le précédent. GetNextImage() and GetNextPageText() chacun prend un chemin de sortie littéral ; la façade ne génère pas de noms de fichiers uniques pour vous. Construisez un chemin distinct pour chaque itération (par exemple, en ajoutant un compteur incrémental) comme indiqué aux étapes 5 et 6.

Erreur de liaison : référence indéfinie à aspose_pdf_foss symboles. Confirm add_subdirectory() pointe vers la racine du dépôt cloné et que target_link_libraries() nomme le aspose_pdf_foss cible exactement, avec une norme C++20 configurée pour your_app.

Foire aux questions

Quelle est la différence entre les façades API et le Document API principal?

Le Document API de base (Document, PageCollection, Annotation, etc.) expose directement le modèle d’objet PDF. Les classes façade telles que PdfExtractor se placent au-dessus et encapsulent une tâche multi-étapes spécifique — extraction de contenu, édition des signets, remplissage de champs de formulaire — derrière une interface plus étroite, conçue à cet effet.

Puis-je modifier les signets ou remplir les champs de formulaire de la même manière que j’extrais le contenu avec PdfExtractor?

Oui. PdfBookmarkEditor (avec CreateBookmarks(), ModifyBookmarks(), ExtractBookmarks() et DeleteBookmarks()) et FormEditor (avec AddField(), RemoveField() et SetFieldAttribute()) résident dans le même espace de noms Aspose::Pdf::Facades et suivent le même modèle d’inclusion/construction montré dans les Étapes 2 et 3 — chacun ne fait qu’opérer sur une partie différente du document.

Est-ce que PdfExtractor peut lire un PDF protégé par mot de passe?

Définissez le mot de passe avant d’appeler toute méthode d’extraction :

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

PdfExtractor::Password() est une propriété en lecture/écriture simple, il faut donc la définir avant ExtractText(), ExtractImage() ou les méthodes d’attachement.

Que se passe-t-il si le PDF ne contient aucun texte, image ou pièce jointe à extraire ?

Rien ne lance d’exception. GetAttachNames() renvoie un vecteur vide, et HasNextPageText() / HasNextImage() renvoient false lors de la première vérification, de sorte que le corps de boucle correspondant ne s’exécute jamais.

Quel en-tête dois-je inclure pour une classe de façade spécifique ?

Chaque classe de façade fournit son propre en-tête sous aspose/pdf/facades/, correspondant au nom de la classe : pdf_extractor.hpp pour PdfExtractor, pdf_bookmark_editor.hpp pour PdfBookmarkEditor, form_editor.hpp pour FormEditor, et bookmark.hpp pour les types de valeur Bookmark / Bookmarks.