Cómo trabajar con las fachadas API en Aspose.PDF FOSS for C++

Aspose.PDF FOSS for C++ agrupa un conjunto de clases de fachada y editor de nivel superior — PdfExtractor, PdfBookmarkEditor, PdfContentEditor, PdfAnnotationEditor, FormEditor, PdfFileEditor y PdfConverter entre ellas — en el espacio de nombres Aspose::Pdf::Facades. Cada una envuelve una única tarea de mantenimiento de documentos sobre el núcleo Document API, de modo que puedes extraer contenido, editar marcadores o rellenar campos de formulario sin tener que implementar manualmente los recorridos de páginas y objetos subyacentes. Esta guía se centra en PdfExtractor, la fachada utilizada para extraer archivos adjuntos incrustados, texto de página e imágenes incrustadas de un PDF existente.

Guía paso a paso

Paso 1: Instalar el paquete

Agrega Aspose.PDF FOSS for C++ como un subdirectorio de CMake y enlaza el objetivo de 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)

Confirma que la cadena de herramientas y el paso de enlace se resuelvan correctamente antes de escribir cualquier código de fachada:

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

Una compilación limpia con un compilador C++20 confirma que aspose_pdf_foss está enlazado en your_app.

Paso 2: Importar clases requeridas

PdfExtractor se encuentra bajo aspose/pdf/facades/, junto a Document del espacio de nombres principal:

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

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

Paso 3: Vincular un documento a PdfExtractor

Cada clase fachada deriva de una base común Facade que expone BindPdf(srcFile) y BindPdf(srcDoc) para adjuntarla a un documento después de la construcción. PdfExtractor también acepta un Document ya abierto directamente en su constructor, que es el patrón usado a lo largo de esta guía:

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

Paso 4: Extraer archivos adjuntos incrustados

Primero verifica Document::EmbeddedFiles(), luego lee los nombres de los adjuntos con GetAttachNames() y extrae los bytes de un adjunto al 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");
}

Paso 5: Extraer texto de cada página

ExtractText() seguido de GetText() escribe el texto completo del documento en un solo archivo:

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

Para capturar un archivo por página en su lugar, establezca el rango de páginas con StartPage() / EndPage(), luego ejecute HasNextPageText() / GetNextPageText() en un bucle, asignando a cada llamada su propia ruta de salida:

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

Paso 6: Extraer imágenes incrustadas

ExtractImage() prepara el cursor de imágenes; HasNextImage() / GetNextImage() luego recorren las imágenes una a una, escribiendo cada una en la ruta que usted proporcione:

extractor.ExtractImage();

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

Problemas comunes y soluciones

GetAttachNames() devuelve un vector vacío. El PDF de origen no tiene archivos incrustados. Comprueba doc.EmbeddedFiles().Count() antes de llamar a cualquier método de adjuntos en PdfExtractor para que no intentes extraer de un documento que nunca tuvo adjuntos.

El bucle de texto de página nunca entra al cuerpo. HasNextPageText() returns false inmediatamente si StartPage() / EndPage() nunca se establecieron, o si se establecieron a un rango fuera del recuento real de páginas del documento. Establece el rango explícitamente desde doc.Pages().Count() antes de comprobar HasNextPageText().

GetNextImage() returns false en la primera llamada. ExtractImage() debe llamarse una vez para preparar el cursor de imagen antes de verificar HasNextImage() o llamar GetNextImage(). Llamar GetNextImage() sin una previa ExtractImage() llamada es indefinida desde la perspectiva del llamador — siempre llame ExtractImage() primero.

Cada imagen extraída o archivo de texto de página sobrescribe al anterior. GetNextImage() and GetNextPageText() cada una toma una ruta de salida literal; la fachada no genera nombres de archivo únicos por ti. Construye una ruta distinta por iteración (por ejemplo, añadiendo un contador incremental) como se muestra en los Pasos 5 y 6.

Error de enlace: referencia indefinida a aspose_pdf_foss símbolos. Confirm add_subdirectory() apunta al raíz del repositorio clonado y eso target_link_libraries() nombra el aspose_pdf_foss objetivo exactamente, con un estándar C++20 configurado para your_app.

Preguntas frecuentes

¿Cuál es la diferencia entre las Facades API y el núcleo Document API?

El núcleo Document API (Document, PageCollection, Annotation, etc.) expone directamente el modelo de objetos PDF. Las clases fachada como PdfExtractor se sitúan sobre él y empaquetan una tarea multietapa específica — extraer contenido, editar marcadores, rellenar campos de formulario — detrás de una interfaz más estrecha y diseñada para ese propósito.

¿Puedo editar marcadores o rellenar campos de formulario de la misma manera que extraigo contenido con PdfExtractor?

Sí. PdfBookmarkEditor (con CreateBookmarks(), ModifyBookmarks(), ExtractBookmarks() y DeleteBookmarks()) y FormEditor (con AddField(), RemoveField() y SetFieldAttribute()) viven en el mismo espacio de nombres Aspose::Pdf::Facades y siguen el mismo patrón de inclusión/constructo mostrado en los Pasos 2 y 3 — cada uno opera simplemente en una parte diferente del documento.

¿Puede PdfExtractor leer un PDF protegido con contraseña?

Establezca la contraseña antes de llamar a cualquier método de extracción:

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

PdfExtractor::Password() es una propiedad de lectura/escritura simple, por lo que debe establecerse antes de ExtractText(), ExtractImage() o los métodos de adjuntos.

¿Qué ocurre si el PDF no tiene texto, imágenes o adjuntos para extraer?

No se lanza ninguna excepción. GetAttachNames() devuelve un vector vacío, y HasNextPageText() / HasNextImage() devuelven false en la primera comprobación, por lo que el cuerpo del bucle correspondiente simplemente nunca se ejecuta.

¿Qué encabezado debo incluir para una clase fachada específica?

Cada clase fachada incluye su propio encabezado bajo aspose/pdf/facades/, coincidiendo con el nombre de la clase: pdf_extractor.hpp para PdfExtractor, pdf_bookmark_editor.hpp para PdfBookmarkEditor, form_editor.hpp para FormEditor, y bookmark.hpp para los tipos de valor Bookmark / Bookmarks.