Como Trabalhar com as Fachadas API em Aspose.PDF FOSS for C++

Aspose.PDF FOSS for C++ agrupa um conjunto de classes de fachada e editor de nível superior — PdfExtractor, PdfBookmarkEditor, PdfContentEditor, PdfAnnotationEditor, FormEditor, PdfFileEditor e PdfConverter entre elas — no namespace Aspose::Pdf::Facades. Cada uma encapsula uma única tarefa de manutenção de documento sobre o núcleo Document API, permitindo extrair conteúdo, editar marcadores ou preencher campos de formulário sem precisar implementar manualmente a navegação de páginas e objetos. Este guia foca em PdfExtractor, a fachada usada para extrair anexos de arquivos incorporados, texto da página e imagens incorporadas de um PDF existente.

Guia passo a passo

Etapa 1: Instalar o pacote

Adicione Aspose.PDF FOSS for C++ como um subdiretório CMake e vincule o alvo da biblioteca estática:

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)

Confirme que a cadeia de ferramentas e a etapa de linkagem sejam resolvidas corretamente antes de escrever qualquer código de fachada:

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

Uma compilação limpa com um compilador C++20 confirma que aspose_pdf_foss está vinculado a your_app.

Etapa 2: Importar Classes Necessárias

PdfExtractor está sob aspose/pdf/facades/, ao lado de Document do core namespace:

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

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

Etapa 3: Vincular um Documento a PdfExtractor

Toda classe fachada deriva de uma base Facade comum que expõe BindPdf(srcFile) e BindPdf(srcDoc) para anexá-la a um documento após a construção. PdfExtractor também aceita um Document já aberto diretamente em seu construtor, que é o padrão usado ao longo deste guia:

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

Etapa 4: Extrair Anexos de Arquivo Incorporados

Verifique Document::EmbeddedFiles() primeiro, depois leia os nomes dos anexos com GetAttachNames() e extraia os bytes de um anexo para o disco com 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");
}

Etapa 5: Extrair Texto de Cada Página

ExtractText() seguido por GetText() grava o texto completo do documento em um único arquivo:

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

Para capturar um arquivo por página, em vez disso, defina o intervalo de páginas com StartPage() / EndPage(), então execute HasNextPageText() / GetNextPageText() em um loop, atribuindo a cada chamada seu próprio caminho de saída:

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

Etapa 6: Extrair Imagens Incorporadas

ExtractImage() prepara o cursor de imagem; HasNextImage() / GetNextImage() então percorre as imagens uma a uma, gravando cada uma no caminho que você fornece:

extractor.ExtractImage();

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

Problemas Comuns e Soluções

GetAttachNames() retorna um vetor vazio. O PDF de origem não possui arquivos incorporados. Verifique doc.EmbeddedFiles().Count() antes de chamar qualquer método de anexo em PdfExtractor para que você não tente extrair de um documento que nunca teve anexos.

O loop de texto da página nunca entra no corpo. HasNextPageText() returns false imediatamente se StartPage() / EndPage() nunca foram definidos, ou se foram definidos para um intervalo fora da contagem real de páginas do documento. Defina o intervalo explicitamente a partir de doc.Pages().Count() antes de verificar HasNextPageText().

GetNextImage() returns false na primeira chamada. ExtractImage() deve ser chamado uma vez para preparar o cursor de imagem antes de você verificar HasNextImage() ou chamar GetNextImage(). Chamando GetNextImage() sem um prévio ExtractImage() chamada ExtractImage() primeiro.

Todo arquivo de imagem ou texto de página extraído sobrescreve o anterior. GetNextImage() and GetNextPageText() cada um recebe um caminho de saída literal; a fachada não gera nomes de arquivos exclusivos para você. Crie um caminho distinto por iteração (por exemplo, adicionando um contador incremental) como mostrado nas Etapas 5 e 6.

Erro de link: referência indefinida a aspose_pdf_foss símbolos. Confirm add_subdirectory() aponta para a raiz do repositório clonado e que target_link_libraries() nomeia o aspose_pdf_foss alvo exatamente, com o padrão C++20 configurado para your_app.

Perguntas Frequentes

Qual a diferença entre as Fachadas API e o Documento API principal?

O Document API central (Document, PageCollection, Annotation, etc.) expõe o modelo de objeto PDF diretamente. Classes de fachada como PdfExtractor ficam acima dele e empacotam uma tarefa multi-etapa específica — extrair conteúdo, editar marcadores, preencher campos de formulário — por trás de uma interface mais restrita e feita sob medida.

Posso editar marcadores ou preencher campos de formulário da mesma forma que extraio conteúdo com PdfExtractor?

Sim. PdfBookmarkEditor (com CreateBookmarks(), ModifyBookmarks(), ExtractBookmarks() e DeleteBookmarks()) e FormEditor (com AddField(), RemoveField() e SetFieldAttribute()) vivem no mesmo namespace Aspose::Pdf::Facades e seguem o mesmo padrão de inclusão/construção mostrado nas Etapas 2 e 3 — cada um opera apenas em uma parte diferente do documento.

O PdfExtractor pode ler um PDF protegido por senha?

Defina a senha antes de chamar qualquer método de extração:

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

PdfExtractor::Password() é uma propriedade simples de leitura/escrita, portanto deve ser definida antes de ExtractText(), ExtractImage() ou os métodos de anexo.

O que acontece se o PDF não contiver texto, imagens ou anexos para extrair?

Nenhuma exceção é lançada. GetAttachNames() devolve um vetor vazio, e HasNextPageText() / HasNextImage() devolvem false na primeira verificação, portanto o corpo do loop correspondente simplesmente nunca é executado.

Qual cabeçalho devo incluir para uma classe facade específica?

Cada classe facade fornece seu próprio cabeçalho em aspose/pdf/facades/, correspondendo ao nome da classe: pdf_extractor.hpp para PdfExtractor, pdf_bookmark_editor.hpp para PdfBookmarkEditor, form_editor.hpp para FormEditor, e bookmark.hpp para os tipos de valor Bookmark / Bookmarks.