Come lavorare con le facciate API in Aspose.PDF FOSS for C++

Aspose.PDF FOSS for C++ raggruppa un insieme di classi facciata e editor di livello superiore — PdfExtractor, PdfBookmarkEditor, PdfContentEditor, PdfAnnotationEditor, FormEditor, PdfFileEditor e PdfConverter tra esse — nello spazio dei nomi Aspose::Pdf::Facades. Ognuna di esse incapsula un singolo compito di manutenzione del documento sopra il nucleo Document API, così puoi estrarre contenuti, modificare segnalibri o compilare campi di modulo senza dover implementare manualmente le camminate di pagine e oggetti. Questa guida si concentra su PdfExtractor, la facciata usata per estrarre allegati di file incorporati, testo di pagina e immagini incorporate da un PDF esistente.

Guida passo-passo

Passo 1: Installa il pacchetto

Aggiungi Aspose.PDF FOSS for C++ come sottodirectory CMake e collega il target della libreria statica:

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)

Conferma che la toolchain e il passaggio di linking si risolvano correttamente prima di scrivere qualsiasi codice facciata:

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

Una compilazione pulita con un compilatore C++20 conferma che aspose_pdf_foss è collegato in your_app.

Passo 2: Importa le classi richieste

PdfExtractor si trova sotto aspose/pdf/facades/, accanto a Document dal namespace core:

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

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

Passo 3: Associa un documento a PdfExtractor

Ogni classe facade deriva da una base comune Facade che espone BindPdf(srcFile) e BindPdf(srcDoc) per collegarla a un documento dopo la costruzione. PdfExtractor accetta anche un Document già aperto direttamente nel suo costruttore, che è il modello utilizzato in tutta questa guida:

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

Passo 4: Estrai gli allegati di file incorporati

Controlla prima Document::EmbeddedFiles(), poi leggi i nomi degli allegati con GetAttachNames() e estrai i byte di un allegato su disco con 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");
}

Passo 5: Estrai il testo da ogni pagina

ExtractText() seguito da GetText() scrive l’intero testo del documento in un unico file:

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

Per acquisire invece un file per pagina, imposta l’intervallo di pagine con StartPage() / EndPage(), quindi esegui HasNextPageText() / GetNextPageText() in un ciclo, assegnando a ogni chiamata il proprio percorso di output:

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

Passo 6: Estrai le immagini incorporate

ExtractImage() prepara il cursore delle immagini; HasNextImage() / GetNextImage() quindi percorre le immagini una alla volta, scrivendo ciascuna nel percorso che fornisci:

extractor.ExtractImage();

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

Problemi comuni e soluzioni

GetAttachNames() restituisce un vettore vuoto. Il PDF di origine non contiene file incorporati. Controlla doc.EmbeddedFiles().Count() prima di chiamare qualsiasi metodo di allegato su PdfExtractor così non tenti di estrarre da un documento che non aveva mai allegati.

Il ciclo di testo della pagina non entra mai nel corpo. HasNextPageText() returns false immediatamente se StartPage() / EndPage() non erano mai impostati, o se erano impostati a un intervallo al di fuori del conteggio reale delle pagine del documento. Imposta l’intervallo esplicitamente da doc.Pages().Count() prima di verificare HasNextPageText().

GetNextImage() returns false alla prima chiamata. ExtractImage() deve essere chiamato una volta per inizializzare il cursore dell’immagine prima di verificare HasNextImage() oppure chiamare GetNextImage(). Chiamare GetNextImage() senza un precedente ExtractImage() chiamata è indefinita dal punto di vista del chiamante — chiamare sempre ExtractImage() prima.

Ogni immagine estratta o file di testo di pagina sovrascrive quello precedente. GetNextImage() and GetNextPageText() ognuno prende un percorso di output letterale; la facciata non genera nomi file unici per te. Costruisci un percorso distinto per iterazione (ad esempio, aggiungendo un contatore incrementale) come mostrato nei Passi 5 e 6.

Errore di collegamento: riferimento indefinito a aspose_pdf_foss simboli. Confirm add_subdirectory() punta alla radice del repository clonato e che target_link_libraries() nomina il aspose_pdf_foss target esattamente, con lo standard C++20 configurato per your_app.

Domande frequenti

Qual è la differenza tra le Facade API e il core Document API?

Il core Document API (Document, PageCollection, Annotation, e così via) espone direttamente il modello a oggetti PDF. Classi Facade come PdfExtractor si trovano sopra di esso e incapsulano un compito multi-passo specifico — estrazione del contenuto, modifica dei segnalibri, compilazione dei campi modulo — dietro un’interfaccia più ristretta e progettata appositamente.

Posso modificare i segnalibri o compilare i campi modulo nello stesso modo in cui estraggo il contenuto con PdfExtractor?

Sì. PdfBookmarkEditor (con CreateBookmarks(), ModifyBookmarks(), ExtractBookmarks() e DeleteBookmarks()) e FormEditor (con AddField(), RemoveField() e SetFieldAttribute()) vivono nello stesso namespace Aspose::Pdf::Facades e seguono lo stesso modello include/construct mostrato nei Passi 2 e 3 — ognuno opera semplicemente su una diversa parte del documento.

Può PdfExtractor leggere un PDF protetto da password?

Imposta la password prima di chiamare qualsiasi metodo di estrazione:

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

PdfExtractor::Password() è una proprietà di lettura/scrittura semplice, quindi deve essere impostata prima di ExtractText(), ExtractImage() o i metodi di allegato.

Cosa succede se il PDF non contiene testo, immagini o allegati da estrarre?

Non viene sollevata alcuna eccezione. GetAttachNames() restituisce un vettore vuoto, e HasNextPageText() / HasNextImage() restituiscono false al primo controllo, quindi il corpo del ciclo corrispondente non viene mai eseguito.

Quale header devo includere per una classe facade specifica?

Ogni classe facade fornisce il proprio header sotto aspose/pdf/facades/, corrispondente al nome della classe: pdf_extractor.hpp per PdfExtractor, pdf_bookmark_editor.hpp per PdfBookmarkEditor, form_editor.hpp per FormEditor, e bookmark.hpp per i tipi di valore Bookmark / Bookmarks.